The template override system

The template override system makes it possible to use other templates than the default ones (specified in the code for the different views and templates). This mechanism allows the creation of template overrides for virtually any template that is used by eZ Publish (including templates that are requested by the "include" template function using the "design:" prefix). In particular, template overrides are typically useful for displaying different types of nodes in different ways.

An override for a view template is usually activated by a set of conditions. If the conditions match, the alternate template will be used. Different views provide different conditions, some views do not provide any conditions at all. Please refer to the "Template override conditions" section of the "Reference" chapter for a complete overview of the available match rules. The most flexible set of conditions are provided by the "view" view of the "content" module (used when a node is displayed). The following illustration shows how the override mechanism plugs into the rest of the system.

The override system.

The template overrides must be defined in the "override.ini.append.php" file of a siteaccess. This file consists of override blocks. A block is a named set of rules that tells eZ Publish to use an alternate template in a specific situation. For each block, the following information must be specified:

• A unique name for the override.
• The template that should be overridden.
• The template that should be used instead of the one being overridden.
• The name of the directory in which the override template resides (usually "templates").
• A set of conditions/rules that control when the override should be activated.

Please note that the rules/conditions are optional. If no rules are specified, the override will always be active. The following illustration shows a typical example of a template override with additional explanations.

Template override example.

The example above defines an override called "special_folders". This override will be used when the system is requested to display a node using the full view mode. The override will only be activated if the object referenced by the node is an instance of the folder class and if it belongs to section number 34. When the override is activated, the system will attempt to use the alternate template ("/override/templates/special_folder.tpl", located in the main design). If eZ Publish is unable to find the alternate template, it will look for it in the additional designs and the standard design. Please refer to the documentation page of the "Automatic fallback system" for more information about this feature.

Multiple / conflicting overrides

The priorities of the overrides are determined by their positions in the file. If there are several overrides with similar/equal rules, eZ Publish will use the first override that matches and thus the rest of the overrides will be omitted. Because of this, overrides that are for example activated on a node ID or an object ID basis should always be placed first; otherwise they might never be triggered because of the presence of a more generic override with a higher priority.