Overriding templates

We usually want to have different templates based on the class we are viewing. If we are viewing a folder we would probably like to list all content of the folder, but if we are viewing an article we would like to show that specific article. To do this we use override templates.

Override templates are defined in the override.ini(.append) configuration file and placed in the override directory in the design directory. Usually this will be done specific for each site access and the override file for the site access should then be used. Overrides can be set to be activated based on things like the current node, object, class or section.

The override template settings can also be defined in the admin interface (Setup -> Templates), we will however use the configuration file in this documentation.

override.ini

The override.ini(.append) file contains one block for each override. A block contains information about which template to override, filename, placement and how to override. Each block starts with an uniqe block identifier (e.g. [musicfolder]), which could be choosen by the user.

Example:

[musicfolder]

Source=node/view/full.tpl

MatchFile=musicfolder.tpl

Subdir=templates

Match[class]=1

Match[section]=4

 

[welcomearticle]

Source=node/view/full.tpl

MatchFile=welcomearticle.tpl

Subdir=templates

Match[node]=42

 

[NewsTree]

Source=node/view/full.tpl

MatchFile=news_article.tpl

Subdir=templates

Match[class]=2

Match[url_alias]=news

This configuration creates three override cases, all will override node/view/full.tpl based on different settings. The first override template is named musicfolder.tpl and is located in override/templates/. This template will be used if someone is viewing an object with class ID 1 in section 4. The next override is named welcomearticle.tpl and will only be used when someone is viewing the node with ID 42.
The last override overrides the full view of class 2 in all nodes under the node having "news" in its url alias.

Notice: In order to use your new override configuration ini file(s), please do not forget to clear override cache files under var/cache/override, otherwise you will only get the outdated version of the template file(s). Some useful clues can be found here.

All ways of matching can be combined to only override the nodes you want.

If no overrides are found for the current node the standard file (node/view/full.tpl in this example) will be used. If this file is missing as well then the system will use the templates in the standard design.

Subdirs

At the time of writing, subdirs within the subdir do not work, they are ignored, so

#will work

Subdir=templates

works, but specifying a nested subdir will not work as in the follwing example

#will not work

Subdir=templates/catalogs

You can specify the subdir with the MatchFile instead:

[medium_image_catalog]

Source=node/view/medium_class_4.tpl

MatchFile=catalogs/medium_image_catalog.tpl

Subdir=templates

Match[class]=4

Match[section]=9

Match[node]=67543322

Using the same template file for several classes

If you need to use the same template file for several of your classes the new template system now makes this easy. Previous to 3.1 you had to either make copies of your file or use symbolic links.

With 3.1 the following example code allow classes 20 and 21 to display using the template file 'full_article.tpl'

[full_article]

Source=node/view/full.tpl

MatchFile=node/full_article.tpl

Subdir=templates

Match[class]=20

 

[full_news_article]

Source=node/view/full.tpl

MatchFile=node/full_article.tpl

Subdir=templates

Match[class]=21

Viewing your full.tpl from the templateview function within the admin will confirm that full.tpl has been overridden in the way you expect.

Order within override.ini(.append)

The order within overide.ini(.append) is important for matching the override templates. The file is read sequentially from top to down, first match will be taken. In general the more specifiy template overrides should be placed above the less specific ones. If you like to override one class in general, but you want to override it within one section with a different template, place the more specific match (for the section+class) above the less specific (only class).

For Example:

[folder_full_section_12]

Source=node/view/full.tpl

MatchFile=folder_full_section_12.tpl

Subdir=templates

Match[class]=1

Match[section]=12

 

[folder_full]

Source=node/view/full.tpl

MatchFile=folder_full.tpl

Subdir=templates

Match[class]=1

If both rules are swaped, the [folder_full] is used for all folders and [folder_full_section_12] will never match.