Template system -- Le système de templates

Date de publication: le samedi 20 août 2011 à 09h24
Dernière modification: par Pascal BOYER le samedi 3 septembre 2011 à 14h59

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/.
Parce que la commande PHP echo du script list.php ne répond pas à nos besoins, nous utiliserons notre propre template. Nous plaçons donc fichier list.tpl dans le répertoire 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).
Pour qu'eZ Publish trouve ce template, nous devons déclarer jacextension en tant qu'extension de design. Pour ce faire, nous créons le fichier de configuration design.ini.append.php dans le répertoire jacextension/settings/ (voir Script 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
Script 7: Déclarer jacextension en tant qu'extension de design

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, first we have to initialize the template object:
Nous déclarons, dans le fichier list.php, une variable $dataArray (tableau contenant des chaînes de caractères) dont les valeurs sont celles que nous utiliserons par la suite dans le template list.tpl. Pour utiliser ce template, nous devons tout d'abord initialiser l'objet template:

$tpl = eZTemplate::factory(); // Notation from eZP 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:
Nous plaçons ensuite le paramètre View Array ($viewParameters) et Array avec les fichiers d'exemple ($dataArray) en tant que variables de template {$view_parameters}, telle que {$data_array}, grâce à l'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'].
Nous exécutons à présent un find / replace dans le template list.tpl sur les variables définies (dans notre exemple, uniquement $view_parameters et $dataArray) et sauvons le résultat dans la variable $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).
Le template principal pagelayout.tpl d'eZ Publish affiche, par défaut, le résultat HTML grâce à la variable {$module_result.content}. Nous plaçons enfin Modul1/list dans le chemin/path de navigation (les «miettes de pain» ou encore «fil d'Ariane») affiché par le navigateur. Pour ce faire, et dans notre exemple, nous cliquons sur la première partie du chemin qui renvoie vers modul1/list (voir Script 8).

<?php
 
// Example array with strings / Exemple de tableau avec chaînes de caractères
$dataArray = array( 'Axel','Volker','Dirk','Jan','Felix' );
 
...
// initialize Templateobject / Initialisation de l'objet «template»
$tpl = eZTemplate::factory();
// create view array parameter to put in the template / Création du paramètre «view» (au format tableau) pour l'insérer dans le template
$viewParameters = array(  'param_one' => $valueParamOne,
                          'param_two' => $valueParamTwo,
                          'unordered_param3' => $valueParam3,
                          'unordered_param4' => $valueParam4 );
// transport the View parameter Array to the template / On envoie le tableau (qui est le paramètre «view») vers le template
$tpl->setVariable( 'view_parameters', $viewParameters );
 
// create example Array in the template => {$data_array} / Création d'un tableau d'exemple dans le template => {$data_array} 
$tpl->setVariable( 'data_array', $dataArray );
// ...
 
// use find/replace (parsing) in the template and save the result for $module_result.content / Utilisation de «find/replace» (parsing) dans le template et sauvegarde du résultat dans la variable $module_result.content
$Result['content'] = $tpl->fetch( 'design:modul1/list.tpl' );
//...
 
?>

Listing 8. modul1/list.php – extending Listing 3
Script 8. modul1/list.php - Script 3 étendu

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).
Nous avons maintenant accès, dans le template list.tpl et via {$view_parameters} et {$data_array}, aux variables définies et affichons les paramètres de vue transmis grâce à la syntaxe {$view_parameters|attribute(show)}. Enfin, l'opérateur de template is_set($data_array) nous permet de déterminer l'existence ou non de la variable $data_array et d'envoyer une liste des données ou un message par défaut (voir Script 9):

{* list.tpl – Template for Modulview .../modul1/list/ParamOne/ParamTwo 
Check if the variable $data_array exists / Contrôle l'existence de la variable $data_array
- yes: show data as list / - oui : affiche la liste des données
- no: show message   / - non : affiche un message
*}
 
{*Show Array $view_parameters: / Affiche le contenu du tableau $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
Script 9. Le template de 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.
Si nous tâchons à présent d'ouvrir notre vue avec l'URI http://localhost/ez/index.php/plain_site/modul1/list/table/5, rien ne devrait s'afficher. La vue ne s'affiche que dans la route Modul1/list. Pourquoi ? Nous ne le savons pas encore.

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).
Pour découvrir l'origine de cette erreur, nous activons eZ Debug en incluant les templates actuellement utilisés. Nous désactivons la compilation et la mise en cache des templates afin de s'assurer que toutes les modifications apportées à ces derniers seront affichées. Pour ce faire, nous modifions le fichier de surcharge globale <ezroot>/settings/override/site.ini.append.php avec les entrées suivantes (voir Script 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
Script 10: Activation, dans le fichier de surcharge globale, du mode Debug avec affichage des templates utilisés : 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"'.
Nous rouvrons donc http://localhost/ez/index.php/plain_site/modul1/list/table/5 qui génère, dans l'espace de débogage, un message d'erreur: «No template could be loaded for "modul1/list.tpl" using resource "design"». (Aucun template ne peut être chargé pour le module "modul1/list.tpl" en utilisant la ressource "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”.
Il semble que le fichier list.tpl ne soit pas trouvé. Il est dans ce cas utile de vider les caches d'eZ Publish puisque ce dernier met en cache la liste des templates existants. Nous chargeons donc la page http://localhost/ez/index.php/plain_site_admin/setup/cache et cliquons sur le lien "empty all caches" (vider tous les caches). Le template liste.tpl doit normalement maintenant apparaître et afficher la liste des données du tableau, nos paramètres de vues et notre exemple de liste de données. Le template doit également apparaître sous la forme modul/list.tpl dans l'espace de déboguage sous la ligne “Templates used to render the page” (Templates utilisés pour afficher le 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.
Dans notre exemple, les paramètres de vue ont les valeurs suivantes: $view_parameters.param_one='table' et $view_parameters.param_two='5'. Ces valeurs peuvent être facilement utilisées pour réaliser des actions dans le script PHP list.php ou dans le template list.tpl: pour afficher, par exemple, le ID ou pour rechercher des informations supplémentaires sur le ID donné.

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.
Astuce: la variable de template $view_parameters est également disponible dans le module content d'eZ et, par conséquent, dans la plupart des templates comme node/view/full.tpl par exemple.

Commentaires