XF 1.2 Template Modifications and Comparison

Anyone who has developed add-ons for XenForo 1.1 knows that template hooks are a pain. They're a pain for us too, to say the least. Plenty of people have installed the Template Modification System add-on. We've been planning a TMS-like system for some time, before the XenForo add-on was ever actually released.

XenForo 1.2 will deprecate the template hook system and introduce it's own template modification system to make it easier for add-on developers to change templates. Note that I'm primarily focused on add-on developers here. It is possible to create your own custom template modifications if you're not an add-on developer, but unless you have multiple styles, I'd recommend just making the changes to the templates directly.

Let's look at what a template modification is:

ss-2013-04-12_11-35-58.png


It's simply a "find this" and "replace with that" style replacement. You can do this to any template. If your find matches multiple times in a single template, it will replace each occurrence.

Applying a template modification does not actually modify the template, so it will not show up as customized and it will be automatically reapplied (if possible) when upgrading.

For those of you that want technical details, the modifications are applied before a template is parsed. If the modifications cause a template compilation error, they are automatically disabled.

Here's what the template modification overview looks like:

ss-2013-04-12_11-41-07.png


All of the template modifications will be listed here, grouped by add-on and ordered by template. The checkbox enables/disables the modification. Note that if the modification is part of an add-on (and you're not in debug mode), you will not be able to edit the modification here but you can enable/disable it. More about this when editing a template.

The 3 numbers indicate the number of times the modification matched (green), the number of times the modification failed to match (grey) and the number of times the modification caused an error (red).

Editing a Template
There are a few new bits when editing a template as well.

ss-2013-04-12_11-43-10.png


There are 3 new things here:
  • The "prevent" checkbox. If selected, modifications will be never be applied to this template. This can be used to quickly check a template without modifications or to adjust the modifications manually.
  • The "view template modifications" link. I'll discuss this below.
  • The "view custom changes" link. This will simply display a comparison of the parent version of the template (probably the master version) and the current version so you can identify the differences.
When you select view template modifications, you'll see an overlay like this:
ss-2013-04-12_11-43-25.png

This shows you a comparison of how the template modifications will be applied to this template.
If you choose to manually apply modifications, the template modifications will be "materialized" into the template - they will actually be written into the template and automatic application of modifications will be disabled in this template. You can then manually edit the modifications if you wish. (Obviously if you upgrade an add-on and they've changed their modifications or you install a new add-on that changes this template, you won't be getting those new modifications so this should be used with care.)

Admin and Email Templates
These aren't left out. Add-on developers will have access to very similar systems that allow the admin and email templates to be manipulated in the same way.
We look forward to more dynamic add-ons with XenForo 1.2. :)
 
Last edited by a moderator:

smartpixels

Active member
There's not really much to say.

Just create the template modification and assign it to the add-on - you need to be in debug mode in order to do so (and in the next release the ability to create a TM is available in debug mode only anyway).

View attachment 52553

Thank you

But I was looking for a guide on when to TM and when not to use TM. Something along the lines and the performance benefits.
 

Chris D

XenForo developer
Staff member
There's no performance loss or gain either way. The template modifications are applied at save time, not run time, so there's zero performance hit.

When to use TM? Always if you're releasing the code as an add-on.

If you're making edits to your own styles and your own site, just edit the templates directly.
 

Jon W

Well-known member
When to use TM? Always if you're releasing the code as an add-on.
It's not always possible. Sometimes changing a template post-render is the only way to get the effect you want. For example, there are some template hooks (hooks within hooks within hooks) and other code that it would be very difficult to write a pattern for.
 

Jon W

Well-known member
When to use TM? Only if you're releasing the code as an add-on.

If you're making edits to your own styles and your own site, always just edit the templates directly.
 

Brogan

XenForo moderator
Staff member
Just to make things clear: the template modification system is being moved to debug only in the next release (consistent with other similar features). It is primarily designed for add-on developers or for advanced usage (as it generally requires detailed knowledge of technical things or some inner workings of XF). For all "normal" usage, templates should be edited directly and updated with merging. This eliminates things like learning regular expressions or doing fragile exact match replacements. 3-way merging should be much more accurate. If you use modifications, you still need to be very methodical to ensure that your changes are still being applied the correct number of times and that the changes are still valid/correct.

If you prefer to use template modifications, obviously that's your prerogative but it's not the recommended/encouraged way.
 

Chris D

XenForo developer
Staff member
You can do what you like with the TM system. If you wish to modify your own site templates using the TM system, feel free. It's not the designed use of it. And you can't easily modify specific styles with the TM system.

The designed use of the TM system is for add-on developers to easily distribute changes to the default templates.

Since XenForo 1.2, there is a wonderful 3 way merge system, so it's no longer advised against to edit templates directly.

The bonuses of editing templates directly is that you can apply different edits to different styles. That's something you can't do with the TM system.

There isn't a reason you shouldn't use the TM system for the day-to-day edits you want to do if it works for you. But at the same time, there's absolutely no reason why you shouldn't just directly edit the templates, either.
 

Jon W

Well-known member
I disagree.

I've not yet found anything I can't use a TM for.
I can't find my hook example, but one that I found much more efficient to do post render was to check whether the moderator bar was being displayed and, if not, to display it. I would love to do this as a template modification, but I can see too many possible template edits that could be made that would just break this, while just checking post render to see if the moderator bar is there is really easy.

I would be more than happy for you to prove me wrong.
 

masterchief

Well-known member
I would prefer ability to designate template modification apply to specific style, where any template modification in the master style would effect all styles.
 

Jeremy

in memoriam 1991-2020
I can't find my hook example, but one that I found much more efficient to do post render was to check whether the moderator bar was being displayed and, if not, to display it. I would love to do this as a template modification, but I can see too many possible template edits that could be made that would just break this, while just checking post render to see if the moderator bar is there is really easy.

I would be more than happy for you to prove me wrong.
You can remove the xen:content check and the isStaff check.
 

Jon W

Well-known member
You can remove the xen:content check and the isStaff check.
What if another similar add-on then wanted to do the same thing? Bearing in mind that I would want to add conditions of my own (in this case a check for the login as user permission). It makes it way more complicated compared to a simple check to see if the moderator bar is rendered. 100+ add-ons could run that same check without conflict.
 
bdXjDcg.png

Am I missing something? This is what happens after I click "Template Modifications" on the Appearance tab, I uninstalled TMS before trying.

Edit: Turned on debug and got this. No idea what to do to fix it.
tei4wab.png
 
Last edited:
Top