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.

 

[CyberAP]

If you tick the checkbox within the template of the style you don't want a modification to work in.... you technically can

View attachment 52045

If you go to http://xenadmins.com and compare the online users sidebar module on the custom style to the default xenforo style, you'll see the TM edit works in the custom style but is switched off for the default.

Thanks, I know, but that's not convenient when you have about 20 TMs.

 

[Lisa]

Thanks, I know, but that's not convenient when you have about 20 TMs.

I agree it can be a bit of a pain, I just wasn't sure if you were aware of that since it didn't actually work at one point I don't think styles are the focus for the TM, unfortunately.

 

[Chris D]

The whole mentality of "TMS is essential because I can't edit templates" is now void.

It's pretty safe to make template edits directly, now. Even editing CSS can now be done directly instead of using EXTRA.css.

The new template diff merge system is awesome. So. Use template edits.

Where you can't use template edits, of course is for add ons. Which is why the TM system is very important still.

 

[Jeremy]

Plus, Mike has stated that this system is meant for add-on and not style development.

 

[Despair]

The whole mentality of "TMS is essential because I can't edit templates" is now void.

It's pretty safe to make template edits directly, now. Even editing CSS can now be done directly instead of using EXTRA.css.

The new template diff merge system is awesome. So. Use template edits.

I agree, I started doing this in beta 2 or 3 and haven't had any issues so far. It's also kind of fun merging the templates on each update for some reason... Maybe that's just me.

 

[Lisa]

I agree, I started doing this in beta 2 or 3 and haven't had any issues so far. It's also kind of fun merging the templates on each update for some reason... Maybe that's just me.

No, not just you

 

[Jaxel]

This new system occurs before compilation, if an edit needs to occur in only certain instances, you will need to use conditionals. Also, the template name should be inconsequential, are you using the same callback for more than one edit?

Yes. Often the conditionals have to be done in the callback, not the template itself. So not having ANY information in the callback, makes it impossible to do some conditionals. The way I'm seeing it now, this new system can only be used for the most basic of instances. It should most definitely not be a replacement for the current hook system, but only a supplement.

If the hook system gets completely removed, many modifications will no longer function.

 

[Jeremy]

The hook system will remain for at least 1.2; but it has officially been deprecated.

 

[xf_phantom]

Couldn't you use params?

<xen:callback class="XP_Test" method="getHtml" params="{xen:array 'template=template_x'}">content</xen:callback>

class XP_Test{

public static function getHtml($content, $params, \XenForo_Template_Abstract $template)
{if (isset($params['template'] && $params['template'] == 'template_x'){

}
}

 

[Chris D]

There's also template_post_render. Not ideal for all uses, but certainly most it should be fine.

 

[gldtn]

Just found out you can't apply TMs for specific style(s). That's disappointing.

I agree, I guess for now we still have to rely on TMS by @guiltar hopefully he will release an update @ RM soon :/ This is all I'm waiting for to update my themes

 

[Paul B]

TM is no longer required with the new template merging functionality: http://xenforo.com/community/threads/template-merging-and-history.48846/

 

[gldtn]

Oh, I see.. this makes since to edit the template directly and with each release we can just review & merge the changes

Thanks Brogan!

 

[Chris D]

This is what I meant yesterday.

There's been a HYS about it, but no one yet seems to appreciate that the 3 way merging functionality effectively means a new mentality where direct template edits are now fine to use.

 

[CTXMedia]

This is what I meant yesterday.

There's been a HYS about it, but no one yet seems to appreciate that the 3 way merging functionality effectively means a new mentality where direct template edits are now fine to use.

Personally, my reluctance to edit templates directly is based on past experience (with both IPB and XF) of having my template changes trashed at upgrade time.

Does the new TMC stop this overwriting behaviour and offer you the opportunity to review the changes before they are applied?

What about new template code (as XF development moves forward) - are these additions/changes merged with your personal changes so your own modifications are retained?

My understanding of the TMS add-on is that your changes are overlaid (as opposed to direct changes) and this makes it easier at upgrade time because the default templates are never actually changed. Does TMC do the same thing but at a direct (template edit) level?

 

[MattW]

Personally, my reluctance to edit templates directly is based on past experience (with both IPB and XF) of having my template changes trashed at upgrade time.

Does the new TMC stop this overwriting behaviour and offer you the opportunity to review the changes before they are applied?

What about new template code (as XF development moves forward) - are these additions/changes merged with your personal changes so your own modifications are retained?

My understanding of the TMS add-on is that your changes are overlaid (as opposed to direct changes) and this makes it easier at upgrade time because the default templates are never actually changed. Does TMC do the same thing but at a direct (template edit) level?

I've always been the same, coming from phpBB. All add-ons edit the core files directly, so upgrading was a nightmare, even with the auto-update tool then eventually released. You could review any conflicts, but I was never certain what was actually going to take, and what was going to break.

I've just moved a few of my own basic template modifications into the direct template edits (now I know how to search for them ).

For example, I change the RSS icon in the foot for a blue one. I was doing this with a TM, and now doing it via a template edit;

As per the HYS thread, I'm going to presume if this was ever to change during an XF upgrade, it would detect this, and give me the option to merge, edit or resolve based on the values from the master style.

 

[Chris D]

I'm hoping this guide explains the changes to XenForo 1.2 templates more clearly:

http://xenforo.com/community/resources/a-guide-to-xenforo-1-2-and-templates.2115/

@MattW is spot on. Forget the TM system. Forget guiltar's TMS. Directly edit the template. Compare and merge later.

 

[CTXMedia]

Thanks Chris - so forget this HYS (TM) and no need for the TMS add-on - just edit the templates directly and let XF manage the changes from here on out?

Sounds good - but I'll still probably try it on one of my smaller forum first - just to get the hang of it.

Cheers,
Shaun

 

[smartpixels]

Can someone please put up a tutorial on how to use TM for addons properly.

 

[Paul B]

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).