ibexa

Path

ez publish / technical manual / 3.10 / templates / the template override system

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

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

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.

Balazs Halasy (16/02/2005 10:53 am)

Julia Shymova (13/05/2008 2:01 pm)

Balazs Halasy, Julia Shymova

Comments

  • Please make it easier to understand

    Thursday 05 January 2006 3:07:31 pm

    Adam

    Hello,
    I want to learn how to override a template...
    Great, I've created the new folder...created a duplicate of pagelayout.tpl....

    I can see this line saying...
    "The template overrides must be defined in the "override.ini.append.php" file of a siteaccess".

    Why can't i find anything that tells me where to create override.ini.append.php.
    It also doesn't explain if these .ini files are needed per template or if you have one file that handles the whole lot. It also doesn't tell me if this can be done via admin, rather than manually.
    It also doesn't tell me how to create overrides via the admin area as I see a "New Override" option.

    I'm really confused...
    It's like you're telling me steps 3 and 4 with the assumtion that I know 1 and 2 like yourself....


    Hope you can help,
    Thanks

    • Re: Please make it easier to understand

      Tuesday 17 January 2006 9:26:56 pm

      Marc Boon

      "The template overrides must be defined in the "override.ini.append.php" file of a siteaccess".

      This means that the file should be created in the /siteaccess/your_site/ folder, next to the site.ini.append.php file, which resides in the same folder.
      So, for every site access, you have one override.ini.append.php file.

      The templates that you create to override the standard templates, are placed in the /design/your_design/override/templates folder (create it if nescessary).

      Custom pagelayout templates however, can just be placed in the design/your_design/templates folder. There is no need to create a override.ini.append.php for those. If templates exist in the /design/your_design/templates folder, they will always be used instead of the /design/standard/templates folder.
      See also: <url>http://ez.no/doc/ez_publish/techn...igns/design_combinations</url>

      The special thing with override templates is that they can *conditionally* override default templates, only if cetain conditions are met, like node id or object class, using the Match specifier.

      • Re: Re: Please make it easier to understand

        Sunday 12 March 2006 8:42:34 pm

        Pike

        "The template overrides must be defined in the "override.ini.append.php" file of a siteaccess".

        This means that the file should be created in
        [ezpublishdir]/settings/siteaccess/[yoursitedir]/override.ini.append.php

  • How to customize the template

    Friday 23 June 2006 6:02:53 am

    Ajay Tyagi

    Hi all,
    could you please tell me, How can i override the various .tpl sothat i can add more images and menus in head part, and like that in various .tpl like footer.tpl .
    if i have a web page then how can i make the templates from that page????

  • Possible override combinations

    Monday 26 February 2007 5:37:48 pm

    Heiner

    Match[object] Matches the object ID
Match[node] Matches the node ID
Match[parent_node] Matches on the parent node ID
Match[class] Matches on the class ID
Match[class_identifier] Matches on the class identifier ( added in 3.4 )
Match[attribute_identifier] Matches on the class attribute identifier ( added in 3.4 )
Match[view_offset] Matches on the current offset in a list
Match[section] Matches the section ID
Match[classification] Matches the classification for eZXMLText tags
Match[depth] Matches on the depth of the current node

    I dont know, if all of them are still working ....

  • A small note

    Monday 17 December 2007 4:33:08 pm

    Gaetano

    If you are creating nested subdirs of the "override" dir, you will need to have your override block set up like this:

    [line_myarticle]
    Source=node/view/line.tpl
    MatchFile=node/view/line/myarticle.tpl
    Subdir=templates
    Match[class_identifier]=article

    ie. Subdir cannot specify a directory hierarchy, while MatchFile can.

    To keep mental sanity when you have a ton of overrides, using a scheme that replicates inside override the same dir tree as inside templates might be a good idea.