Hey everyone, today I'm going to walk through proper theme installation. This is in reference specifically to XenForo 1, though XenForo 2 will be mostly the exact same thing. I may write a separate blog post for XenForo 2 theme installation at a later point, but for now you can use this as a guide for XF2 as well. You can comment on the article we have featured at XenForo.com here.
The Conventional Installation
Most theme designers will list a similar 3 or 4 step process:
- Download the files to a place you are familiar with. Inside that folder that you downloaded you will see an .xml file and an /upload/ folder.
- Upload the contents of /upload/ to your root xenforo directory, typically something like /www/ or /www/forums/
- Go to your XenForo ACP > Appearance > Styles > [Click on] Import a style. Browse for the .xml file that you downloaded and click install. (Some may have had you upload the .xml file, so you'll want to use the Import file from server field instead)
And while this is mostly correct, I find that a bit more attention should be given for the sake of upgrades and adding more themes down the line.
While the installation process listed above is necessary, I want to give it just a few extra considerations. Namely spin-off themes, upgrading the third-party themes, and upgrading XenForo itself.
If extra consideration is not given, you may find your theme settings and skins get a bit jumbled and hard to maintain, especially if you are using a third-party theme.
I decided to write this resource because I find many people just install the skin without thinking about the above issues. Here is what I find many people doing:
First, they install the theme. Then any changes they want to make they apply directly to what they installed, directly to the third-party skins. So now the changes the developer/designer made and the ones the site owner has made are not separated. And this makes upgrading an absolute nightmare!
So, let's run through an example. I am the owner of a forum called MikesLikes, clever isn't it! We discuss all the things Mike, myself, likes; what I enjoy. I enjoy soccer (EPL, playing), books (Tolkien, Rowling, Paolini), and games (Chess, Catan, Poker, CoD). And I want to make some themes for these topics.
First, I check out the resource manager at XenForo.com and search for a few themes that I like. Some themes are frameworks, so if I want all my themes to look the same and have extended functionality, that might be something to look into. Or maybe I find a theme that has an awesome design but no special functionality, which is still good! I might want to make sub-themes based off of any of these. Maybe some of these themes come with light and dark versions too. And I know Ill want one that is a fixed width (960px) and fluid width (90%), and perhaps some that are not responsive, do or don't have a sticky header/navigation, etc. The options are endless, and good organization makes all of this possible.
So I choose AwesomeSkin1 as the main theme of choice, because it comes with a dark version and I might want to use that later down the road. So now, how do I install this correctly? Whether you develop the skins yourself the concerns Ill bring up will be similar.
The first step is to install the first skin you want conventionally. BUT here is the part I need to do that is extra. This is third-party and I plan on making changes. It is not wise to make the changes directly to the installed skin. Doing so will make any updates that third-party designer makes difficult. So, I install "AwesomSkin1". After that, I go to the style section again and click the + Create New Style button. Set the parent to AwesomeSkin1 and the name should be something like AwesomeSkin1 - EDIT ME or something that makes sure you know that this is where you will make the majority of your template and style property changes. You should NEVER edit the third-party installation. Nothing at all.
The next step is to actually hide AwesomeSkin1 AND AwesomeSkin1 - EDIT ME from public view. Just toggle the Allow User Selection checkbox. Only admins can see this now. So now, you want to actually create the skin that people actually can see. Just simply go to that same + Create New Style button and select the parent to be "AwesomeSkin1 - EDIT ME" I generally think you should name it what it is. Naming is important in technology. Something like: [AwesomeSkin1] Base, [AwesomeSkin1] Light (if you plan on having a dark version", MikesLikes - Main, anything like that. The name you choose shouldn't JUST be the name of the third-party skin, that means nothing to your members.
So at this stage I have a style listing that might look like this:
AwesomeSkin1 [Untouched third-party theme]
--- AwesomeSkin - EDIT ME [Where you make any template edits and global style property changes -The "BASE" theme
------ MikesLikes - Light
Since MikeLikes - Light is unedited, it will actually look exactly like AwesomeSkin1 since it is a child. And I can create more sub-themes. I can create MikesLikes - Soccer or MikesLikes - CoD or anything I want and just modify the style properties for these skin to change the background and colors however I want, all the while still pulling from the base theme I chose.
Any significant changes that should apply to ALL sub-themes you will want to apply to the AwesomeSkin - EDIT ME version.
The third-party designer made an update, lets upgrade!
Good for him or her! Bring em on! We have our installation setup where all we have to do is:
- Download the updated theme files
- Again, upload the contents of /upload/ to your root XenForo directory if asked to
- Go to ACP > Appearance > Styles > [Click the] Import style button, then browse for the file you downloaded. Make sure to click the select menu Overwrite style: and choose AwesomeSkin1 or whatever third-party skin. NOT our base skin or the ones we've created!
Why did we do this again?
Because now, all the specific changes we wanted for our skin (changing the color, the width, the background-images, responsive fixes, etc.) are not grouped in with the third-party designer. And any changes the designer makes to his or her resource will not get confused with your changes. We also assume that a good resource developer is going to make their product up-to-date with XenForo. So upgrading should be a snap and limited to just YOUR changes.
Checking for outdated templates and the upgrade process
Now that your base third-party theme is upgraded, it is time to check for outdated templates (and style properties*).
As it currently stands, XenForo cannot check for outdated style properties. That means you'll just have to compare your site and the demo, depending on what features are missing and the release notes on the upgrade. So this part isn't an exact science yet but updating outdated templates is.
If there are outdated templates, XenForo will let you know. What does it mean to have outdated templates? It means that there were edits made to a template by you or another admin that XenForo software or the third-party skin has modified in the latest update. To fix this, you can use the XenForo merge tools, the TM system. Please see Chris' A Guide to XenForo 1.2 and templates but in general it is a very intuitive system that will make sure that you can automatically or manually fix any outdated bits of code.
It is always a good idea once your theme is upgraded to just give everything a once-over, especially plugins you've installed and any new sub-themes you've created. Constantly checking is a good practice to get into, you never know what can go wrong! But using this system should make sure that whatever can go wrong is minimized.
Let's go over everything again:
- Install your third-party theme by following their installation constructions (the conventional way most likely)
- After installation, create a base child theme to make all your specific customizations and template modifications/style property changes to
- Hide the third-party theme and your child base theme from public view by toggling the Allow User Selection tick box
- Create a third level child style (under your base theme) and name it something specific to what it is to you, unique from the name of the third-party theme itself.
- Any sub-themes or variations should be children of at least the base skin created in step 2.
- When upgrading, you only have to upgrade the third-party skin then fix any outdated issues on the base skin (and possibly the sub-themes depending on how much you customized them)
The main things to take away is:
- Child themes are your friend and make future upgrades and edits a breeze!
- Never edit any third-party sources directly if you can help it, which you can in 99.99% of all situations.
- Upgrading doesn't have to be difficult if you keep good organization!
- You can create as many sub-themes as you want using this method and all the skins will be upgraded at once! Have sub-themes that are fluid, have ones that are not responsive, have a green, a blue, and a yellow version! As many as your heart will be content with!