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.

 

[Mike]

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?

I'm not sure what you're doing exactly. You can PM me the details and I'll see how I'd do it, though I have some other template thoughts.

 

[jmurrayhead]

I can't even put into words the amount of awesome this is. Looking forward to it!

 

[Adam Howard]

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.

I suggested it a few times (as did others)

Although I'm sure KAM had it planned in the early XenForo beta stages.

I'm looking forward to this, but am a little concerned that this will not do everything that TMS does. And so there is a small concern that I'll be having both installed. As I do have 2 designa (style) that uses TMS heavily (the responsive design is one). And if you can't use XenForo's TMS to make styles.... That's a little concerning.

Another key point is one of the first things I do when updating or upgrading is export my style with all it's templates (including TMS additions)

 

[Adam Howard]

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.

 

[Jeremy]

Mike has confirmed in my PC to him that we can still use the whole template syntax and stuff.

 

[DRE]

So basically, move all my custom TMS modifications over to the new Xenforo TMS.

But there are some things the TMS does that Xenforo doesn't so I'll still need to leave it installed.

Those things mainly being "supporting other addon's TMS modifications".

TMS isn't going away any time soon then.

 

[Luxus]

I wonder if TMS and XenForo's version conflict with each other.

 

[duderuud]

A lot of changes in 1.2, even more will come probably.

Is it wise to hold off a migration to XF untill 1.2 is out? Seems to me a lot of work has to be done again if you upgrade from 1.1 to 1.2.
(We would have a lot of custom add-ons)

 

[Vicki]

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.

I haven't used the existing add-on TMS, only heard about it and thought I might give it a try in a few weeks... Now TM is going to the core, and that's great news!

I have a few questions- which might be very silly- regarding this new feature, please bear with me and forgive my english too:

1. If I modify a template and let it automatically apply the changes, where did the changes go? Can I know the name of the file(s) containing the changes or the file containing the complete new version of this template?

2. What does "Manually Apply Modifications" mean exactly? If you do the manual apply, does it mean it will overwrite the originally template file, and you have no way to revert to the original?

3. When editing a template and if you've saved multiple times, if you click the "Revert Template..." button, which version of template it will bring to you - the very last saved version or the original version from the install?

4. If I did some modifications to the templates via this TM on our testing site, and when it is time to apply these exact same changes to our production site, how should I go about it?


Many thanks!

 

[lazy llama]

It would be really nice if we could use this on a style-by-style basis as we can with TMS.

Prior to the 1.1.4 upgrade I went through our "No Avatars" style and converted it all over to use TMS, which saves me having to check 16 templates every time there's an upgrade.

 

[Adam Howard]

I wonder if TMS and XenForo's version conflict with each other.

XenForo is not optimized in 1 area... Rebuilding template cache. It restricts you from having to many styles or to many templates. Even on a powerful setup, this can be a problem.

http://xenforo.com/community/threads/skin-build-memory-leak.30556/

The current TMS (link) helps resolved that "bottleneck" (doesn't cure it). But it too can be a little resource heavy on rebuilding.

I imagine (guess) having them both installed may cause an issue (this is only a theory based on what I know at current).

Of course I'm hoping that the new TMS (made by Xenforo), helps attack that "memory leak"

 

[Jon W]

The current TMS (link) helps resolved that "bottleneck" (doesn't cure it). But it too can be a little resource heavy on rebuilding.

In my experience, having TMS installed causes the rebuilding of template cache to take much longer. In what way does it make it better?

 

[Chris D]

XenForo is not optimized in 1 area... Rebuilding template cache.

This makes XenForo much more optimized in another area.

XenForo dedicates more resources and time to rebuilding the templates and other caches so it is much more optimised at run time. That's the trade off. And, if that means I get a few minutes to make a cup of coffee on the are occasion my caches will rebuild on a live site, then all the better than my users having to make a cup of coffee every time a page loads.

 

[nrep]

Perhaps a silly question, but does this mean that if I customise a style, there's a chance that an add-on many not work (because of a small customisation) if hooks are no longer used?

FWIW, I currently use TMS and it's excellent - so looking forward to this change.

 

[Adam Howard]

In my experience, having TMS installed causes the rebuilding of template cache to take much longer. In what way does it make it better?

You're not wrong. It does take longer to complete with TMS. But the key point is that it does complete (without running out of resources)

On vBulletin I had 30 (?) styles
phpbb I had 15
IPB which in my opinion uses more resource (overall) I had 20
SMF I had 8

Only XenForo seems to be restrictive in this department. It's the only "flaw" (bug) I can actually wave a stick at. In almost every other field, XenForo is top of it's game.

XenForo I currently have 3

Install X amount of styles (say 10 for example) and have 9 of those as child styles, then edit a few templates in the parent style (lets assume bug fix for php, which wasn't so long ago). See if XenForo can complete it without TMS or running out of resources to do it.

 

[Adam Howard]

This makes XenForo much more optimized in another area.

XenForo dedicates more resources and time to rebuilding the templates and other caches so it is much more optimised at run time. That's the trade off. And, if that means I get a few minutes to make a cup of coffee on the are occasion my caches will rebuild on a live site, then all the better than my users having to make a cup of coffee every time a page loads.

Time isn't the concern.... I'm not worried about how long it takes to complete.

The concern is how much resources does it take to complete (and does it complete)

 

[Luxus]

Perhaps a silly question, but does this mean that if I customise a style, there's a chance that an add-on many not work (because of a small customisation) if hooks are no longer used?

Yes and no. If you update an add-on and if its templates have been updated as well, then there is a chance that you need to update your personal edits for certain features to function (for example, after a Bookmarks update I couldn't bookmark any items anymore because the bookmark link has been updated and my edits have overwritten this). There is more of a chance for this to happen if you abuse regular expression edits. Of course this is only the case if you have modified the templates of an add-on. So if you leave templates of add-ons alone, you won't have problems with upgrading them.

 

[Arty]

Great feature, however

No. You can release a separate add-on if you want, but this is mostly targetted at add-ons.

That's unfortunate. It would be awesome to be able to add per-style modifications instead of editing style's templates. That would make maintaining styles much easier.

 

[Mike]

I'll just leave this here...

 

[AlexT]

Here I am starting to drool...