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:

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:

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.

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:

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.

 

[Paul B]

Will there be some sort of import function for TMS edits or do we have to apply all edits manually?

It would be more appropriate for the add-on developer to develop an exporter.

 

[CTXMedia]

Wanders in - looks up - has a quick read - decides this one is for the devs - <shuffles off>

 

[Luxus]

It would be more appropriate for the add-on developer to develop an exporter.

That's like saying it would be more appropriate for xenforo to make an exporter for vB5. (Well, not really, but you get my point )

 

[cclaerhout]

A fatal error will kill the necessary reparse and would potentially be unrecoverable (I suppose I could add a config.php option to disable modifications for that).

You lost me here I will wait the next version of XenForo to see how addons can be updated. I was just using callbacks because it was easier to make/modify several modifications.

Speaking of addons compatibility, it would be another reason to keep template hook listeners. Yes, I'm stubborn I know. But code used inside hook listeners is not cached as it will be in the TMC. So it allows to do some modifications on live. Yes, it is like the post render template listener then, but it's easier to target a content in a hook than in a template.

 

[Paul B]

That's like saying it would be more appropriate for xenforo to make an exporter for vB5. (Well, not really, but you get my point )

It's unrealistic to expect XenForo to create an importer for a third party add-on which only a small percentage of license holders use.
It's time which could be better spent elsewhere.

 

[Mike]

I never mentioned the hooks being removed (in 1.2) - just that they're deprecated. There aren't any plans to add new ones and they may be removed in the future.

 

[Teapot]

This is a fabulous feature - getting template modifications into core is something I've wanted for ages. Thanks Kier and Mike!

 

[cclaerhout]

I never mentioned the hooks being removed (in 1.2) - just that they're deprecated. There aren't any plans to add new ones and they may be removed in the future.

I guess I've reacted to quickly when I've read the "depreciate" word. My bad ^^

 

[Shelley]

Keeps getting better and better.

 

[Hoffi]

Great!
Less Code and more options for the addons.

 

[DRE]

I'm in complete shock here. Someone mentioned that Xenforo should add this and I wanted to laugh at him but wow y'all actually did.

This is really cool.

 

[Cupara]

This is great, I'm anxious for this new feature. Definitely will require me to redo some mods but nothing major.

 

[Kim]

This sounds amazing, will have to read and absorb a few times before it makes sense though

 

[xf_phantom]

thx, thx thx

And 1 small Suggestion for very lazy people:
Show the template code of the template in the form too, so we don't need to open another browserwindow to see the template code

 

[euantor]

Looks like a great feature Mike, will be very welcome as with the rest of 1.2's improvements!

 

[guiltar]

Good news! But don't forget callbacks. They are needed in complicated cases.
For example, you need to insert final thread_list template and modify it for your addon by other mods.

 

[AlexT]

WOW! This is a nice improvement over 1.1!

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.

So the search & replaces take place before templates are compiled and than stored and used from the xf_template_compiled database table? In other words, no performance hit?

 

[Luxus]

So the search & replaces take place before templates are compiled and than stored and used from the xf_template_compiled database table? In other words, no performance hit?

Templates aren't parsed on-the-fly. So there should not be differences in performance. In fact, performance should be better without hooks.

 

[Jeremy]

Mike,

This looks fantastic! One question, if you need to insert data and not make your changes dynamic, how can a developer go about doing that? Do we have to extend controllers, and modify the view params? Or is there an easier way, because that could create lots of unnecessary code.

For example, my latest add-on adds to a wrapper template using a hook. How can i go about accomplishing that in this new system?

 

[shenmuee]

Good news! But don't forget callbacks. They are needed in complicated cases.
For example, you need to insert final thread_list template and modify it for your addon by other mods.

+1 thanks ^^