Picture this: You wake up one morning, pour a cup of coffee, and check your emails. You scroll down past the boring stuff until you see one titled “Latest Version of XenForo Released” (or something like that, I don’t know the specific title) and you’ve gotta have that upgrade now. You login to XenForo to download the files (or upgrade using the new one-click install if you’re already on XF2.1). You let it run until it says it’s been completed, and asks you to click that button to view your forum. You click it and BAM, your site is broken. You login to the ACP to see what the heck happened, and that’s when you realize you have outdated templates.
You’ve got a sweet theme from Themehouse (or any other good theme developer 🙂 ), and you’ve even customized your own child theme too. And while the default theme seems to be working fine, your custom theme certainly does not. If you haven’t experienced this before you may be saying to yourself, “Self, how hard can this be?” And if you have experienced this before, then you’re probably feeling sorry for those people who don’t realize the predicament they might be in.
Fortunately, getting your theme back into tip top shape doesn’t have to be as hard as it might seem. I’ve worked with who knows how many clients at this point to get their themes’ outdated templates resolved. Sometimes they are small point upgrades, and sometimes they are massively outdated (think 1.4 to 1.5.20 😲). I’ve made a lot of mistakes, tried a lot of different tricks, and eventually came up with a bit of a formula to help me through the process. So that’s what I’m here to talk to you about today. Without further ado, let’s get started fixing those themes!
Theme Inheritance
So before we begin talking about how you can fix up those nasty outdated templates, first we need to understand what is going on and why. Knowing specifically what the problem is is crucial to knowing how to fix it.
The first thing to understand is the theme inheritance system, which XenForo uses to keep track of updates and ensure that they never overwrite your customizations. The way it works is like this. XenForo has a “master” theme, which is what any default theme starts out as. The difference is that each installation only has one single master theme, and anytime you create or edit any theme (including the default) you are actually making a “fork” of that theme. You can’t edit the master theme unless you are in debug mode, which is a good thing because you should NEVER edit the master theme under any circumstances whatsoever. So instead, you edit/create a new theme.
Now, your theme seems to start with everything that the master theme has, but that is not entirely correct. See, any theme you make actually contains only the changes you have specifically made to that theme. For example, if you edit the default theme and change some of the color palette values, then that theme consists only of a couple color values. So where does the rest of the styling come from? Well, that’s where the inheritance comes in. Each theme inherits everything from the master theme with the exception of the things you’ve edited yourself.
The inheritance system does not stop just at that level though. You can continue making and nesting themes, and they will continue to inherit everything from the themes above them, other than the things specifically edited in the theme in question. Let me give you an example. Let’s say you have purchased UI.X (thank you for your support 😀 ) and you have also created a child theme of UI.X that you have edited yourself. We’ll call it Custom Child Theme. So your theme inheritance looks like this: Master theme > UI.X > Custom Child Theme. This means that UI.X inherits everything from the master theme other than things edited or added in UI.X. Your custom child theme then inherits everything from UI.X, and anything that is not edited in either UI.X or the Custom Child Theme itself will also be inherited from the Master theme. This may seem a little confusing, but I think it will make sense as we keep talking about it. Honestly though, the only thing you need to keep in mind here is that each theme can potentially have it’s own version of any template. Take PAGE_CONTAINER for example. Assuming it has been edited in all themes, there is a master version, a UI.X version, and a Custom Child Version. And that specifically is why we have outdated templates.
Outdated Templates and Template Merging
So now that you understand that each theme can have it’s own version of every single template, we can talk about outdated templates. A template is “outdated” if there are edits in a parent theme that are not yet added to a child theme. For example, XenForo may make changes to the PAGE_CONTAINER template. When you update XenForo, every theme will inherit these changes to PAGE_CONTAINER if they do not have their own version. Even if they do have their own version, it is possible for them to continue inheriting so long as the edits are not to the same portions of those templates (more on this later). Templates only become outdated when changes are made specifically to the same line of code in multiple themes. So again, a template is “outdated” if a parent theme (such as the master theme or UI.X) has changed in a template that your child theme does not yet have. The process of getting these changes into your themes’ custom version is called “merging.”
We just learned in the last section that XenForo has theme inheritance at multiple levels, such as the example with Custom Child Theme. That means changes could be coming from multiple places, which complicates the matter. How do you know if a specific change is coming from XenForo, from a theme you’ve purchased such as UI.X, or if it was an intentional change in your child theme (especially if you made it long ago)?
The good news is that XenForo can oftentimes handle these changes for you. There is a nifty “Automatically merge outdated templates” button at the top right of the outdated templates page, and it is always safe to use. Sometimes when the edits are pretty simple, XenForo can handle most, if not all of them by itself. That is fantastic, but that’s not what we are here to talk about. We are here to talk about the templates it cannot merge, and how we can gracefully handle the rest by ourselves. Alright, now that we know what’s going on, let’s talk about what things we can do to avoid having outdated templates in the first place.
Preventative Measures
The good news is that if we are careful with our edits, there is a lot of damage reduction we can do just by being organized and writing clean code. Here are a few tips on ways you can customize your theme safely:
Never edit purchased themesJust like you should never edit the master theme, you should also never edit a theme you have purchased or downloaded from another developer. These should more or less be thought about the same way as the master theme because editing them has the same pitfalls.
- Your customizations may get overwritten when you upgrade the theme.
- You do not know if changes in the theme were made by yourself or if they were made by the theme developer.
Because XenForo has theme inheritance, we can always make all of our changes to a child style of that purchased theme. That way, all of our edits are in one place, they will never be overwritten, and we know who’s code belongs to who.
Comments, comments, comments!
It is always a good practice to write useful comments to yourself when you are editing templates. Whether it is in CSS or in an html template, comments help us remember what changes we are making, and why we are making them. If you work on a project with multiple people, you can put your name in parenthesis so that everybody knows who wrote that code. You can even add a date so that everyone knows when the change was made.
You can use XenForo’s comment syntax in all templates. Start the comment with <xf:comment> and end it with </xf:comment>. Anything inside of these brackets will be ignored entirely. Just make sure you don’t put one XenForo comment inside of another one, or XenForo will yell at you when you try to save the template.
New templates for new code
Another good practice is to keep all of your new code separate whenever possible. After all, you can’t have outdated templates if you make all of your changes to new templates you have created yourself. This is obviously fairly easy when we’re talking about CSS. You can either use the extra.less template provided by XenForo, or just make your own. As far as markup goes, anytime you write your own custom HTML in full, make a new template and save yourself the trouble. You can then use <xf:include template=”templateName” /> to insert that markup wherever you’d like, which results in have very little customization needed to an existing template.
Back that theme up
The House of Pain said it in 1992, but I’ll say it again today. Back. It. Up! The best way to make sure your theme never breaks is to make sure you make a backup before attempting to upgrade XenForo or a third party theme. This way, you always have a clean saved version of your code preserved as it was intended.
Update in the correct order
This is an easy one that you won’t see anybody suggest anywhere, and I have no idea why. Updating everything in the correct order will save you a ton of headaches. The reason this is important is again because of the inheritance system. We need to make sure we start at the top of that inheritance list and work our way down. The correct order is as follows
- Update XenForo software (I.E. the master theme).
- Update all add-ons if applicable (some themes edit add-on templates, and add-on templates are always part of the master style).
- Update all third party themes. This is important because they are top level themes and direct descendents of the master theme. You should also update any of your own custom themes that are also direct descendents of the master theme.
- Update child themes by level. If you have a ton of nested themes such as Master > UI.X > Custom Child > UI.X Dark > Custom Child Dark, then you should edit them in that order. Always do the top most themes first and move your way down the list.
Actually Merging Templates
I’m sorry that it took us this long to get here, but everything I have said so far is all very important stuff for you to understand. So now that we understand the problem, and we have done everything we can to prevent it, let’s talk about some neat tips that can help you actually merge outdated templates.
Use a Diff tool
Diffing (or differentiating) tools will help you see the differences between two files. For example, you can use these tools to see what things are different between a version of the PAGE_CONTAINER template in one theme vs another. I personally use a free one called Diffchecker which you can check out here.
One thing that you’ll see a lot of are the differences with tabs and spaces, which don’t affect the code at all, and just make it harder to find the changes that actually matter. Fortunately, you can use the “Trim whitespace” tool to remove these unnecessary spaces, which will help you better visualize the differences.
Duplicate your theme
This is the best tip I am going to give you on this post, so make sure you store this one away. Install a duplicate copy of your theme of your forum before you start any upgrade processes. It is very important that you do this before anything else, otherwise it is of no use to you. To do this, simply export your theme, and then re-import it. If it is a child theme, then make sure to duplicate the parent theme as well. The goal here being that when you go through the upgrade process, you have an untouched version of your theme to make comparisons with. This is going to be a life saver, and I will explain why in another tip here in a moment. For now, just know that this one tip has saved me hours and hours and hours of time updating templates. Just remember, the purpose here is to have an untouched version of your theme. So whichever one is your duplicate, do not edit it whatsoever.
Make Smart Comparisons
When merging one of your outdated templates, it’s not always clear where new code is coming from, or why the old code is there. And if you don’t know what that code is, or what you’ve changed yourself, then how are you supposed to know which versions of the code you need to keep?
This is where having those duplicate themes and that diffchecker tool really come in handy. If you are staring at those code changes, and not sure which to pick, you can figure out where the code is coming from by comparing different versions of the file. There are 3 different comparisons that I use.
- Compare old XenForo to new XenForo
This is potentially the most helpful, but unfortunately can only be done if you have an old version of XenForo to compare to. However, if you use GitHub or have a staging server, then you’ll have an old version of the templates handy to compare. Obviously, comparing the old version of the XenForo template to the new version will tell you what has been added by XenForo specifically.
- Compare old third party theme to the new one
If you use one of our themes such as UI.X or any other third party theme, then you’ll need to update this as well before you can update your child theme, which means more code changes. Luckily, we can easily figure out what changes were made specifically in our third party theme by comparing an old version of the template to the new version. And where do we get the old version? From the duplicate theme we made before we started of course 🙂
- Compare old parent theme to your old child theme
If you want to see what changes you have made specifically, you can’t really do that during the upgrade process. At least, not in the theme you are currently upgrading. So instead we can head back over to our duplicated themes and compare what the template changes are between the old version of your parent theme (such as UI.X or any other third party theme) and the template in your old custom theme.
Moving forward in reverse
Sometimes the easiest way to move forward is to start over. If you know you have made very few changes, but a template is showing as having many unmerged changes, simply revert the template entirely and re-make your changes. I have found this the easiest method of getting very outdated templates fixed when your own customizations are pretty minimal. Again, to figure out specifically what your changes are, just compare your old custom child to the old parent theme in your duplicated themes.
That’s a Wrap
Merging templates is never a delightful activity, but hopefully if you follow these guidelines you’ll find yourself doing it much less often than before. And when you do have to do it, now you have a few extra tools in the box to help you get the job done. If you have any questions please feel free to comment below, and check back later to see if I’ve added any other useful tips to help get the job done.
Well, I suppose I’m all done here now. So, as the great Bugs Bunny so very often said, “That’s all folks!”
