Basic template tasks

This section sheds light on some common issues related to template development.

Template inclusion

A template file can be included using the "include" function. Since this function makes it possible to include any file from any location within the eZ Publish directory, it must be told that it should look for the file within the design directory. This can be done by prefixing the path/filename with "design:". The following example demonstrates how the include function can be used to include a template file called "footer.tpl", which is located in the templates directory of a design.

{include uri='design:footer.tpl'}

If the requested file is not found within the main design of the siteaccess, the system will search for it in the additional designs and the standard design. Please refer to the documentation of the automatic fallback system for more information about this feature.

Output washing

Variables that may contain bogus strings should always be washed using the "wash" operator. This operator makes sure that the output does not contain any elements that may mess up the HTML generated by eZ publish. The following example demonstrates how the wash operator works.

{def $bogus_string='hello < world'}
{$bogus_string|wash()}

The following output will be produced:

E-mail address obfuscation

In addition to securing proper output, the wash operator can also be used to obfuscate E-mail addresses on a web page. An obfuscated E-mail address has a less chance of getting picked up by a robot searching for E-mail addresses to put on a spammer's list. The following example demonstrates how the wash operator can be used with an E-mail address.

{def $email_address='allman@example.com'}
{$email_address|wash( 'email' )}

The following output will be produced:

String concatenation

The "concat" operator makes it possible to glue several strings together in order to produce a single string. The following example demonstrates how this operator works.

{def $my_string='sausage'}
{concat( 'Liver ', $my_string, ' sandwitch' )}

The following output will be produced:

Custom view parameters

The URL of a node view request may contain custom parameters. The custom view parameters must be specified at the very end of the URL using a special notation. For each parameter, a name and a value must be specified. The name must be encapsulated by parenthesis. Each element must be separated by slashes. The following example demonstrates how custom parameters can be used (in addition to the view parameters) in a system URL that requests a node.

http://www.example.com/content/view/full/13/(color)/green/(amount)/34

The same parameters can be appended to the virtual URL of the node:

http://www.example.com/company/about_us/(color)/green/(amount)/34

When custom view parameters are used, the system will create an associative array using the name of the provided parameters as the keys. All parameter values will be treated as strings. The array will be represented by the $view_parameters variable in the template. The parameters given in the examples above will produce an associative array with the following contents:

The following example demonstrates how the custom view parameters can be accessed in the template that is used to display the node.

The color is: {$view_parameters.color} <br />
The amount is: {$view_parameters.amount} <br />

The following output will be produced:

Custom view parameters in "edit.tpl" templates

In eZ Publish versions prior to 3.9, you cannot pass custom view parameters to the "edit" view of the "content" module. From 3.9, it is possible and thus you can use custom view parameters in the "edit.tpl" templates. The following example demonstrates a typical system URL in this case:

http://www.example.com/content/edit/13/03/eng-GB/(color)/green/(amount)/34

This will instruct eZ Publish to use custom view parameters, specified in the link above, when editing the "eng-GB" translation of the third version of the thirteenth content object in the system.