Creating a Theme (Advanced Mode)Started by Arceus at Apr 24, 2019 at 4:27 am
They don't think that I listen, oh but I know who they are.
Creating a Theme (Advanced)
Of course, I'm sure everyone was waiting on this post-guide specifically, and now that the theme system is more thoroughly hammered in, I actually have something to type here. Unfortunately, the first iteration of Gaia will have only advanced mode available for theme management, but hopefully it won't be too terrifying. As most of you are from SMF, Gaia's theme logic should be somewhat familiar.
Creating the Theme
So, the first thing you'll need to do, is click the Themes Manager link in the sidebar in the admin panel. You'll be taken to a screen that lists all your front-end themes (admin themes cannot be edited through Gaia itself just yet). Just click the create button in the top right. From there, you'll need to give it a name, denote a folder name, and name the first variant, variant theme colour, denote any fonts you want loaded, and set the theme's editor colour scheme. At the bottom of this screen is a browse button. This will collect more than one image file that you want uploaded to the theme's images folder, for ease of use in your theme.
Once created, you'll be able to manage the given theme. This is where you can change which variant it uses as its default, alter its folder name, and upload more images to the theme's image folder, or remove existing images from it. This is all very straight-forward. Now you'll be wondering where the rest of the settings are: these are in the variant settings, which don't ship with version 1 just yet. Because... frankly I forgot. xD
When you click the CSS Files button, you'll have a selection of which CSS file to edit. Clicking any one will load that file's contents into a large textarea, so you can edit it at will. This is direct file editing. It's all straight CSS.
Leave the framework.css file in place. Edit it if you'd like to, but make sure it's there. It controls some "global" things about your theme, CSS rules that are used across all its variants.
The same thing happens when you click Template Files, you have a selection of available template files in the given theme's folder. Clicking any given one will drop that file's contents, in full, into a textarea. Again, this is straight PHP and HTML. If you're not familiar with either, just, don't.
I will also note that there is a noted issue where the template files with textarea fields in them will cause the textarea box to break, so uh, I know that's there, I'll fix it eventually, sorry.
Finally, creating a new variant does the same thing that creating the default variant did; you'll give it a name, set some basic settings for it, and then head on out. Unfortunately once created, variants cannot be altered directly, and cannot be removed yet, either.
You'll notice a lot of this is really incomplete; yes, it is. The theme system is actually a lot more complicated than I thought, so neither the advanced mode is finished, nor the easy mode even... really functional. Improvements, adjustmnets, and expansions to the theme system will come in future versions, when I have taken a sabbatical and am not as stressed out anymore.
For those that want more control over their templates, I greatly recommend you do most of your template and CSS file editing outside of Gaia itself. The file editor in the admin panel is really more of a convenience thing, so if you just need to make a tiny tweak, you don't need to boot up your entire FTP programme or what have you. Creating a new theme will also only copy frame.template.php, this is the base template, think of it as the wrappers (SMF's index.template.php?). You'll need to manually copy over any other file you want into the new theme's folder.
Finally, while deleting a theme works, it only takes out the files in the folders, not the folder structure itself, so you'll need to do some clean-up on it later. (I really honestly don't know why.)
(I'm sorry this is so incomplete.)
Hopefully, though, some of you will go poking at it and get to making your own themes. The variables that are available are in the global lines, and none of the templates have any real PHP logic in them, so they shouldn't be too terrible. I will note, Gaia does not use procedural PHP ($var['thing']), it uses object-oriented ($var->thing), so it may be a bit weird to you and operate in strange ways. It's worth it to learn, most of the internet these days uses object-oriented PHP, and it is a decent stepping-stone into the world of scripting. (Nyx works. After getting familiar with OOPHP, I figured out jQuery enough to make Nyx work. That's wild, trust me.) If you need to know what properties are in a variable, print_r() it. =) And might I suggest using xmp instead of pre?
The next guide will be on manipulating the blocks to display how you want them to, and calling them manually into templates. (If it also makes anyone feel any better, I will be making premade themes for Gaia later.)
Check out my writing blog!