ibexa

Path

ez publish / technical manual / 4.4 / 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 page layout 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 page layout 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 page layout. The following illustration shows how the module/view result (generated by different modules/views - depending on the request) is included in the page layout:

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/09/2010 11:31 am)

Geir Arne Waaler (28/09/2010 9:31 am)

Balazs Halasy, Svitlana Shatokhina, Geir Arne Waaler


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.
      • Re: Re: how to specify content type of template?

        By default view templates use the standard html content-type.
        To set a different one, the easiest ways is to take advantage of the "set" view of the "layout" module
  • Gibberish and Gobbledegook

    People should be forewarned at an early age that something tragic happens to people if they become computer programmers. They lose the ability of simple expression.

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

    What on earth is this mumbo-jumbo?
    • Re: Gibberish and Gobbledegook

      Well, i don't know ez publish, but i think that this concept is also manage by drupal CMS, the general idea is that u have a php var called "$node", with all the node information (Title, content and so on), the information in the "$node" change from one view to another (i.e. if you are calling an admin view, it maybe contents some private information as the author's email or something like that, in this case $node will contain a $node->email attribute).

      So if you want to display the title in some part of the template, you just need to use something like "$node->title"

      Please correct me if i'm wrong... is my first day in ez content and my English sucks a little :p
  • Connection between page and its template

    How to I find out which template a page is using? Our site is managed by a design company and they create templates for me. When I need changes I have to request them. How can I determine which template is being used for specific pages?
    • Re: Connection between page and its template

      you can enable some debugging in your
      siteaccess/xxx/site.ini.append.php .

      [TemplateSettings]
      Debug=enabled
      ShowUsedTemplates=enabled

      Obviously not recommended on livepages
    • Re: Connection between page and its template

      Hi Dianne,

      jsut as rainer said, but you also can add the DebugByIP directive so that the debug will be visible only to your defined IP set.

      Ciao
  • The graphics on this page are broken

    The graphics on this page are broken.