ibexa

Path

ez publish / technical manual / 3.10 / templates / template basics


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

Template basics

This section explains the concepts behind templates and the template system. eZ publish uses templates as the fundamental unit of site design. A template is basically a custom HTML file that describes how some particular type of content should be visualized. A template file always ends with a ".tpl" extension. Actual HTML code in the built-in/default templates follow the XHTML 1.0 Transitional specification. In addition to standard HTML syntax, a template consists of eZ publish specific code. The eZ publish specific code makes it possible to extract information from the system and to solve common programmatic issues like for example conditional branching, looping, etc. All eZ publish specific code must be placed inside a set of curly brackets, "{" and "}". The following example shows a part of a template that prints out the current time:

...
<h1>Time machine</h1>
<p>
    The current time is: {currentdate()|l10n( time )}
</p>
...

The example above demonstrates how standard HTML is mixed with eZ publish specific code. It shows the usage of the "currentdate" and the "l10n" template operators. Since "currentdate" returns a UNIX timestamp, it must be formatted using the "l10n" localization operator (or else the output would not make any sense to humans). This is done by piping the output from the "currentdate" operator into the "l10n" operator, which will output the requested information according to the current locale settings. The "time" parameter tells the operator to output only the time (it could have been "date", "shortdate", "datetime" and so on).

Template generation

The template system is component based. In other words, an actual HTML page is usually made up of several templates. At the minimum, eZ publish always renders the main template, which is called pagelayout. The pagelayout contains the HTML, HEAD and BODY tags; it dictates the overall look of a site. Among other things, it describes the visual structure (main layout, logo, main menu, footer, etc.) that will be presented for each HTML page that the system generates.

Every incoming request tells eZ publish to run a specific module and to execute one of the module's views. When finished, the requested module/view combination will generate a result. The result can be accessed through the $module_result array which is available in the pagelayout template. The following illustration shows a simplified 3-step explanation of how eZ publish responds to an HTTP request.

Client -server cycle.

Client - server cycle.

Every view generates a chunk of HTML code by making use of a template. Templates that are used by views are often referred to as view templates. Whenever a view has finished running, it will issue an internal template request. The requested template will be interpreted, processed and thus converted to HTML. After processing, the system will put the resulting HTML in the module's result array. The module/view's result can be accessed through the ".content" extension: {$module_result.content}. By printing out the contents of this variable, it is possible to include the HTML code that was generated by the view in the pagelayout. The following illustration shows how the module/view result (generated by different modules/views - depending on the request) is included in the pagelayout:

The module result as a part of the pagelayout.

The module result as a part of the pagelayout.

View templates

A template used by a view can either be a node template or a system template. A node template will only be used when a node is being viewed, for example when a system URL containing "/content/view" or the virtual URL of a node is requested. A system template typically provides an HTML interface to a specific eZ publish feature. For example, the template used by the "search" view of the "content" module provides an interface to the built-in search engine.

The difference between the template types mentioned above is the available variables and the combination of override rules that can be used. A node template gives access to a variable ($node) which contains information about the actual node that is being viewed. Depending on the view that was called, a system template typically gives access to several variables. A template override rule makes it possible to display custom templates in specific cases. The override rules for node templates are much more flexible than the override rules for system templates. For example, it is possible to set up complex rule combinations that depend on the type of the node being viewed, the depth of the node in the tree, the section which the node's object is assigned to and so on. Please refer to the "The template override system" section for a detailed description of the template override mechanism.

Balazs Halasy (14/02/2005 9:12 am)

Svitlana Shatokhina (10/11/2006 8:41 am)

Balazs Halasy, Svitlana Shatokhina


Comments

  • how to specify content type of template?

    Is anywhere described, how to specify content type of template?
    • Re: how to specify content type of template?

      Nope.