• This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn more.
A guide to XenForo 1.2 and templates

A guide to XenForo 1.2 and templates

Chris D

XenForo developer
Staff member
#1
Chris Deeming submitted a new resource:

A guide to XenForo 1.2 and templates - The Times They Are a-Changin'. Guide to Templates in XenForo 1.2.

Introduction

With XenForo 1.2 needs to come a new mentality when dealing with templates. Lots of things have changed in this regard. And it's important for us as forum admins and developers that we change with the times, rather than getting stuck in the past.

Template Modifications (The TM System)

I can't tell you what you should or shouldn't refer to various features as. It's not my place. But please, don't call it TMC!
The...
Read more about this resource...
 

Luxus

Well-known member
#2
Template Modifications have an advantage over direct template edits that people may not want to forfeit that easily. Enabling/Disabling template edits by click. With Template Modifications you can also track and document your changes more easily.
 

Chris D

XenForo developer
Staff member
#3
There's already a facility to track and monitor your changes using the template history and comparison for each template.

Although not quite as simple as a single click, it's not exactly much more work to go into a template and comment out the code for testing and debug purposes. Or copy and paste the original code from the template comparison:

upload_2013-7-26_12-35-9.png
 

RoldanLT

Well-known member
#5
Template Modifications have an advantage over direct template edits that people may not want to forfeit that easily. Enabling/Disabling template edits by click. With Template Modifications you can also track and document your changes more easily.
So true!
Agree (y)
 

JulianD

Well-known member
#6
I know Mike said on the forums that template hooks are being deprecated. I would like to know what is the best approach to make dynamic template changes. I have an addon that manages all my advertising on my forum. It consists of a Listener that allows me to use template hooks. Then, based on different variables, I decide which ads to display to the current user.

What is the best approach to something like this?

BTW: Great resource Chris. Thank you for your great efforts!
 

Luxus

Well-known member
#7
Here is an example of doing a template edit directly vs. via TMs:

Lets say you want to add a notice to all xenforo pages above the h1 title.

Direct Template Edit:

- Go to AppearanceTemplates
- Open the PAGE_CONTAINER template
- Scroll down until you find "<!-- h1 title, description -->" and copy&paste the following code above it so that it will look like this:

Code:
<xen:comment>This is a simple hello world notice above the title of every page</xen:comment>
<div class="notice" style="color:red; border: 1px solid red; border-radius: 5px; background-color:yellow;padding:5px;text-align:center">Hello World</div>
<!-- h1 title, description -->
- Save

Result:

pic.png


Now we are doing the same but with the Template Modifications method:

Template Modification:

- Go to AppearanceTemplate Modifications
- Click Create Template Modification
- Enter the following values in the specified fields:

Template: PAGE_CONTAINER
Modification Key: pc1
Description: This is a simple hello world notice above the title of every page
Search Type: Simple Replacement
Find: <!-- h1 title, description -->
Replace:
Code:
<div class="notice" style="color:red; border: 1px solid red; border-radius: 5px; background-color:yellow;padding:5px;text-align:center">Hello World</div>
<!-- h1 title, description -->
- Click Save Template Modification

The result is the same. The difference is how you can manage this template edit. With the TM method, if you want to remove this notice, you need just to uncheck the checkbox of the appropriate TM:

pic2.png

And in case you want to enable it again, all you need to do is to check the checkbox. Also you can see instantly the name of the template a modification is applied to and what the modification actually does. Easy and convenient.


With the direct template edit method you actually need to search for the template that contains your edit because unlike the TM method your edits aren't listed. But you don't know what edit you made because it has been some time since you did it so you need to open a template and find the edit you are looking for via the View Custom Changes function. And once you found it, you need to remove your edits directly from the template if you wish to remove the notice we added above the h1 title of every xenforo page. And in case you want to add it back, you need to paste the code again directly in the template.

Compared to the TM features, direct template edits are still a pain, really. And even these TM features are limited for style developers as you pointed out in your guide.
 

Brogan

XenForo moderator
Staff member
#9
Template Modifications is a new function in 1.2 which injects modifications into templates without changing the original.

Editing templates directly is a manual process and changes the original template.
 

psTubble27

Well-known member
#10
I can see that being a source of some confusion. Chris even had to devote a paragraph trying to distinguish between the two.

Here is a sample sentence: "In order to modify templates, don't use template modifications, but rather modify templates".
 

Brogan

XenForo moderator
Staff member
#11
Would you prefer the Template Modifications system was called something different which doesn't reflect what it does?

That's exactly what it does so the name is logical.
 

psTubble27

Well-known member
#12
Maybe we can can use the term "Template Mods". Same thing, but people already associate "mods" with a specific bunch of code that alters an original. If you have a new user coming who is asking about editing the sidebar template (say), you tell him:
1) create a Template Mod if you want,
2) or modify the template directly.

Just a suggestion. Anyway I didn't mean to highjack Chris' thread.
 

Brogan

XenForo moderator
Staff member
#13
Actually I would just say edit the template.

Template modifications shouldn't be used for simple edits but if I was going to distinguish between the two it would be:

1. Create a Template Modification.
2. Edit the template.
 

Luxus

Well-known member
#14
Would you prefer the Template Modifications system was called something different which doesn't reflect what it does?

That's exactly what it does so the name is logical.
Perhaps an alternate name could be Template Patches. You write code and the system patches this code to the original templates during the compiling process. You can remove patches anytime by disabling them via checkbox.
 

Chris D

XenForo developer
Staff member
#15
I can see that being a source of some confusion. Chris even had to devote a paragraph trying to distinguish between the two.
Of course I devoted a paragraph explaining them. This is a guide about template features in XenForo 1.2. I can't not describe the functions separately because they are two distinct things.
 

Kintaro

Well-known member
#16
Template modifications shouldn't be used for simple edits.
Can I ask you why? Can create incompatibility with addons?
Have template modifications listed (like in TM and TMS) and have the possibility to activate/deactivated them with a click is huge!
 

Chris D

XenForo developer
Staff member
#18
If Template Modifications work for you, great. Knock yourself out.

But the point of this guide was to explain the options available to people. And to ensure people have an understanding of how direct template edits are no longer a thing to avoid.

Maybe that didn't come across in the guide.

Primarily the TM system is a development tool. If you have specific things that you find easier to achieve in the TM system, no one is going to stop you :)

On the flip side, the main reason people used any sort of TM style system in the first place was because of a (understandable) reluctance to make direct template edits.

The reason for that reluctance was because of an inability to easily compare the changes between an upgraded template and a directly edited template. The only choice was to revert and manually reapply.

That reluctance and reasoning is now entirely void. Direct template edits should no longer by default be avoided. If you can do them, do them.

At the same time, if you prefer to use the TM system -- no one is going to stop you.

It's all about options. There's now many more.
 

Code Monkey

Well-known member
#19
With a template modification system I only have to go find and fix what breaks on updates. With template merge I have to go through all the templates and make choices on every update. The latter seems to be much more work and I also can't just turn an edit off if I wish to.

So while I may yet embrace this NEW thinking I am not sold on it yet. More work = Bad
 

Despair

Active member
#20
With template merge I have to go through all the templates and make choices on every update.
In most cases it's actually just clicking one button, "Automatically merge all templates" or something similar. Only if a conflict is found would you need to manually make a choice. I've gone through at least 4-5 releases and didn't even run into a conflict yet.