Navigation

All templates are located in the templates directory of modules.
Templates are referred to by their full filename. When a template is inside a directory then the full path of the template must be given.

For example, say we have two templates:

mod_example/templates/foobar.tpl

mod_example/templates/email/email_base.tpl

The above are referred to as foobar.tpl and email/email_base.tpl.
Just email_base.tpl will not find the email template.

All templates of all modules are grouped together, regardless in which module they are defined and the module name is never given as part of the template name.

Similar named templates can be defined in multiple modules.
Which template is selected depends on the priority of the module.

The module priority is a number defined in the module’s code and is usually a number between 1 and 1000.
A lower number gives a higher priority.
Templates in a module with higher priority hide templates in a module with lower priority.

When two modules have the same priority then the modules are sorted by their name.
That means that, given the same priority number, mod_aloha has higher priority than mod_hello.

This mechanism allows any module (or site) to replace every single template in the system with its own version.

Note

Including all similar named templates

The tag {%allinclude"foobar.tpl"%} will include all templates named foobar.tpl.

Where the tag {%include"foobar.tpl"%} only includes the highest priority foobar.tpl.

The user agent class and the module priority are two dimensions of the template selection process.

The module priority is more important than the user agent class.

A mismatch in user agent class (eg. a desktop template when looking for a phone version) will never be selected.
A sub-optimal version (eg. a generic or text version instead of phone version) will be selected if that sub-optimal version resides in a module with higher priority than the module with the better matching version.

The all include tag will select the best version from all modules. Again skipping any user agent mismatches.

Note

Building templates and mobile first.

The lookup strategy for templates conforms to a mobile first strategy.
When adding a page or building a site, the idea is to start with the simplest, text only, version of the site.
The text only version is then placed in the templates/text directory.
Next will be adding more features, markup and interaction for the phone version.
Only then moving up to the big screen for tablet (touch) or desktop (mouse).

Note

Seeing which template is selected.

The mod_development implements a screen where it is possible to see in real time which templates are included and
compiled. The full path of all templates can be seen, giving insight in the template selection process.