Template system

Because the echo command in the PHP script "list.php" does not meet our needs, we want to use our own template. Therefore we put the file "list.tpl" into the folder jacextension/design/standard/templates/modul1/.

For eZ Publish to find the template, we have to declare "jacextension" as a design extension. To do this we create the configuration file "design.ini.append.php" in the folder jacextension/settings/ (see Listing 7).

<?php /* #?ini charset="utf-8"?
# transmit to eZ, to search for designs in jacextension
[ExtensionSettings]
DesignExtensions[]=jacextension
*/ ?>

Listing 7. Declare jacextension as a design extension

In "list.php" we declare a variable $dataArray (array with strings). The values of this array we want to use later in the "list.tpl" template. To use the "list.tpl" template, we have to initialize the template object:

$tpl = eZTemplate::factory(); //

Notation from eZ Publish 4.3. Before this version, use templateInit() function

Then we put the parameter View Array ($viewParameters) and the Array with the example files ($dataArray) as template variables {$view_parameters}, like {$data_array}, with the instruction:

$tpl->setVariable( 'view_parameters', $viewParameters );
$tpl->setVariable( 'data_array', $dataArray );

Next we do a find / replace for the template "list.tpl" with the defined variables (in our example only $view_parameters and $dataArray) and save the result in $Result['content'].

By default the main "pagelayout.tpl" template of eZ Publish shows the result with the variable {$module_result.content}. Finally we put Modul1/list in the navigation path (the "breadcrumbs") that are displayed in the browser. In our example this is done by clicking in the first part of the route, which links to modul1/list (see listing 8).

<?php
 
// Example array with strings
$dataArray = array( 'Axel','Volker','Dirk','Jan','Felix' );
 
...
// initialize Templateobject
$tpl = eZTemplate::factory();
// create view array parameter to put in the template
$viewParameters = array( 'param_one' => $valueParamOne,
                           'param_two' => $valueParamTwo,
                           'unordered_param3' => $valueParam3,
                           'unordered_param4' => $valueParam4 );
// transport the View parameter Array to the template
$tpl->setVariable( 'view_parameters', $viewParameters );
 
// create example Array in the template => {$data_array}
$tpl->setVariable( 'data_array', $dataArray );
// ...
// use find/replace (parsing) in the template and save the result for $module_result.content
$Result['content'] = $tpl->fetch( 'design:modul1/list.tpl' );
//...
?>

Listing 8. modul1/list.php – extending Listing 3

Now we have access to the defined variables in the template "list.tpl" with {$view_parameters} and {$data_array}. We show the transmitted view parameters with {$view_parameters|attribute(show)}. Next we use the template operator is_set($data_array) to see if the variable $data_array exists and send a list with the data or a default message (see listing 9).

{* list.tpl – Template for Modulview .../modul1/list/ParamOne/ParamTwo
Check if the variable $data_array exists
- yes: show data as list
- no: show message
*}
 
{*Show Array $view_parameters: *}
{$view_parameters|attribute('show')}<br />
 
<h1>Template: modul1/list.tpl</h1>
 
{if is_set($data_array)}
    <ul>
    {foreach $data_array as $index => $item}
        <li>{$index}: {$item}</li>
    {/foreach}
    </ul>
{else}
    <p>Attention: no existing data!!</p>
{/if}

Listing 9. eZ Template design modul1/list.tpl (e.g. extension/jacextension/design/<your_design>templates/modul1/list.tpl

If we now open our view with http://localhost/ez/index.php/plain_site/modul1/list/table/5, nothing much will happen. It only appears in the route Modul1/list. Why? We don't know yet.

To investigate the error, we activate eZ Debug, including the templates currently in use. We deactivate compiling and caching of templates to be sure that all changes in the templates will be shown. To do this we extend the global <ezroot>/settings/override/site.ini.append.php with the following entries (see listing 10).

<?php /* #?ini charset="utf-8"?
 
[DebugSettings]
Debug=inline
DebugOutput=enabled
DebugRedirection=disabled
 
[TemplateSettings]
ShowXHTMLCode=disabled
ShowUsedTemplates=enabled
TemplateCompile=disabled
TemplateCache=disabled
# Optional, will save you from most cache clearings during development
# as modified time on tempaltes are always checked during execution
DevelopmentMode=enabled
*/?>

Listing 10. Activate Debug view with template list over global configuration file: 
ezroot/settings/override/site.ini.append.php

We now open http://localhost/ez/index.php/plain_site/modul1/list/table/5 again. It generates an error message in the Debug view: 'No template could be loaded for "modul1/list.tpl" using resource "design"'.

It seems that the file "list.tpl" was not found. In this case it is useful to clear the cache of eZ Publish, as eZ has cached the list of the existing templates. So we load the URL http://localhost/ez/index.php/plain_site_admin/setup/cache and we click on “empty all caches”. Now the template list.tpl should appear with the table list, our view parameters and our example datalist. As well it should appear as modul/list.tpl in the Debug view “Templates used to render the page”.

In our example the viewparameters has the following values: $view_parameters.param_one='table' and $view_parameters.param_two='5'. The values of the viewparameters can be easily used to perform actions in PHP script list.php or in the template list.tpl, for example to display the ID or fetch some extended information to the given ID.

Hint: the template variable $view_parameters is also available in the kernel module content of eZ and therefore in most templates, such as node/view/full.tpl.