Date de publication: le lundi 23 avril 2007 à 16h35
Dernière modification: par Pascal BOYER le mercredi 26 octobre 2011 à 22h43
« Article précédent: eZ publish: le template pagelayout.tpl
» Article suivant: Classes d'objet

Objectifs

Dans cet article, nous allons détailler la mise en œuvre d'une surcharge de template dont la documentation traduite se trouve ici .

La surcharge de template est une des fonctionnalités clef de eZ Publish et sa maîtrise est absolument indispensable tant elle participe à faire de ce système de gestion de contenu un outil puissant et modulable à souhait.

Le système de surcharge à pour vocation de permettre différents affichage d'un même contenu.

Affichage par défaut d'une classe d'objet

Lorsque l'on instancie un objet à partir d'une classe que l'on vient de créer, cet objet, bien qu'affiché automatiquement sur le site public, ne l'est pas d'une manière convenable. En effet, le système se contente d'afficher en gras le nom de chaque attribut de l'objet suivit du contenu, s'il existe, de ces attributs.

La capture d'écran ci-dessous illustre un tel affichage:

Intérêt d'une surcharge

Le besoin de faire une surcharge s'explique d'une part, comme on vient de le voir, par un affichage par défaut qui ne répond vraisemblablement pas à notre attente, et d'autre part, corollaire du premier point, par notre volonté de définir exactement (en tous points) cet affichage.

Autre point à ne pas négliger: les templates de surcharge ne sont pas écrasés lors de la mise à jour de eZ Publish préservant ainsi le fonctionnement de notre site tout au long de l'évolution de notre système.

Créer une surcharge, c'est:

1.  créer un template personnalisé dont le but sera de définir très précisément l'affichage de tous les éléments de contenu d'un type d'objet,
2.  définir les règles de surcharge, c'est à dire les circonstances dans lesquelles le template de surcharge sera utilisé par le système.

Le premier point ci-dessus signifie que le template de surcharge va permettre d'indiquer au système, non seulement quels sont les attributs d'un objet dont on souhaite afficher les contenus mais également la manière dont on souhaite les afficher.

Le template par défaut

La première chose à faire est de déterminer le template que le système utilise par défaut pour afficher les objets d'une nouvelle classe. Et pour cela, comme d'habitude, nous utiliserons l'outil de débugage disponible dans l'interface d'administration. Les 2 options surlignées en rouge doivent être appliquées au siteaccess public:

Après avoir validé ces options avec le bouton Set il faut vider tous les caches avec l'aide du bouton Vider.

Si l'on affiche ensuite sur le site public un objet d'une nouvelle classe, le système nous indique alors que le template utilisé pour afficher cet objet est:

design/standard/templates/node/view/full.tpl

C'est donc de ce template qu'il va falloir créer une surcharge.

Emplacement des surcharges

Les templates de surcharge sont impérativement placés dans un sous-répertoire du répertoire override du design courant. Par exemple, pour le siteaccess luxpopuli, ce sera dans un sous-répertoire de:

design/plain_site/override/

Pour s'en tenir à la façon de faire traditionnelle, nous pouvons même considérer (et dire) que les templates de surcharge sont placés dans:

design/plain_site/override/templates/

Au-delà du sous-répertoire templates/, l'emplacement des templates de surcharge est totalement libre et la fin du chemin menant à la surcharge est à la libre appréciation de chacun.

Si les nouveaux objets sont des articles, nous pouvons par exemple les placés dans:

design/plain_site/override/templates/full/articles/

Créer une surcharge

Considérons que nous venons de créer la nouvelle classe suivante:

Ce sont donc les contenus des attributs des articles instanciés par cette classe d'objet que nous souhaitons afficher grâce à une surcharge.

Par la suite, nous supposons avoir instancié (créé) un article Propriétés physiques de l'eau pure:

...et nous appellerons le template de surcharge pleine_vue.tpl. Le nom de la surcharge est également entièrement libre.

Nous devons donc créer le template suivant:

design/plain_site/override/templates/full/articles/pleine_vue.tpl

Lorsqu'un template de vue est utilisé par le système, nous savons, pour avoir lu la documentation, que nous disposons d'une et une seule variable: $node

Cette variable contient beaucoup d'informations sur le nœud (l'article, le dossier, l'image, etc...) traité par le template. L'article dédié au template pagelayout.tpl indique comment visualiser la liste exhaustive des informations contenues dans une variable et comment afficher ces informations.

Nous pouvons donc afficher le contenu de la variable $node en écrivant, comme première ligne du template de surcharge:

{$node|attribute(show)}

La règle de surcharge

Pour que le template de surcharge soit pris en compte par le système, encore faut-il que ce dernier ait connaissance de l'existence de celui-ci et qu'il sache dans quelles conditions il doive l'utiliser.

Pour répondre à tous ces impératifs, nous disposons du fichier de configuration de surcharge override.ini.append.php situé dans le siteaccess public du site.

Voici, à travers un exemple précis, la syntaxe générale d'une surcharge:

[article_full_1]
Source=node/view/full.tpl
MatchFile=full/articles/pleine_vue.tpl
Subdir=templates
Match[class_identifier]=article_de_test

•  Ligne 1: le nom de la règle de surcharge. Ce nom doit impérativement être unique. Si plusieurs règles du template override.ini.append.php portent le même nom, les résultats obtenus seront faux ou incohérents.

•  Ligne 2: le chemin relatif et le nom du template utilisé par défaut, c'est à dire du template que l'on souhaite surcharger. Le chemin est relatif au sous-répertoire design/plain_site/templates/
   Si le nom du design n'est pas explicitement indiqué dans le chemin c'est en raison du fait que eZ Publish utilise le système de repli automatique.

•  Ligne 3: le chemin relatif et le nom du template de surcharge. Le chemin est relatif au sous-répertoire design/plain_site/override/
   Si le nom du design n'est pas explicitement indiqué dans le chemin c'est en raison du fait que eZ Publish utilise le système de repli automatique.

•  Ligne 4: le nom du sous-répertoire de design/"design_courant"/override/ dans lequel le système doit rechercher le template de surcharge. Comme nous l'avons vu précédemment, il est coutume d'utiliser le sous-répertoire design/plain_site/override/templates/

•  Ligne 5: c'est la condition (ou le critère) devant être remplie pour que le système applique la règle de surcharge. En fonction de l'emplacement du template original, nous disposons de critères différents. Ces critères  sont définis par la documentation officielle de eZ Publish. dans l'article Template override conditions .

Après avoir écrit cette règle de surcharge au début du fichier de configuration override.ini.append.php de notre siteaccess public, nous devons vider tous les caches.
 Si nous affichons ensuite sur le site public un article instancié avec notre classe article_de_test alors nous devons voir le tableau présentant le contenu de la variable $node.

Titre de l'article

Le titre de l'article peut être obtenu de deux manières. Soit avec la syntaxe:

{$node.name}

ou bien avec:

{$node.data_map.titre_article.content}

Une fois la ligne inscrite dans le template de surcharge, recharger la page de l'article sur le site public affichera le titre de l'article.

On peut bien sûr ajouter du code XHTML:

<h1>{$node.data_map.titre_article.content}</h1>

L'auteur de l'article

Il peut être extrait directement du contenu de l'attribut Auteur de l'article:

{attribute_view_gui attribute=$node.data_map.auteur}

...ce qui affichera:

Jean LAFLEUR <eaupure@source.net>

Comment faire pour n'afficher que le nom de l'auteur ou que son adresse e-mail?

L'outil de débugage, associé à la syntaxe {attribute_view_gui attribute=$node.data_map.auteur}, nous permet de savoir, en l'affichant sur le site public, que la fonction de template attribute_view_gui utilise le template:

design/standard/templates/content/datatype/view/ezauthor.tpl

Le même outil de débugage, associé à la syntaxe {$node.object.data_map.auteur.content}, nous permet d'arriver à la même conclusion, mais de façon moins explicite. En effet, cette fois-ci, l'affiche produit est:

Object(ezauthor)

Le contenu du template ezauthor.tpl nous apprend comment il faut extraire les données d'un attribut basé sur le datatype author ( Auteur).

Par ailleurs, la documentation de l'objet ezauthor nous apprend que le datatype author fournit, entre autres, un tableau (array) author_list dont les trois valeurs sont id, name et email. Et c'est justement la syntaxe d'extraction des valeurs de ce tableau que nous propose le template ezauthor.tpl

En reprenant le contenu de ce template, on peut écrire par exemple:

{section var=Authors loop=$node.object.data_map.auteur.content.author_list}
Le nom de l'auteur de cet article est: {$Authors.item.name}<br />
Vous pouvez contacter l'auteur à l'adresse e-mail suivante: {$Authors.item.email|wash( email )}
{/section}

afin d'obtenir l'affichage:

Le nom de l'auteur de cet article est: Jean LAFLEUR
 Vous pouvez contacter l'auteur à l'adresse e-mail suivante: eaupure@source.net

Comme la syntaxe basée sur section est obsolète, nous allons écrire la même boucle avec la structure de contrôle foreach :

{foreach  $node.object.data_map.auteur.content.author_list as $Author}
Le nom de l'auteur de cet article est: {$Author.name}<br />
Vous pouvez contacter l'auteur à l'adresse e-mail suivante: {$Author.email|wash( email )}
{/foreach}

Le corps de l'article

Pour afficher le coprs de l'article, nous pouvons écrire:

{attribute_view_gui attribute=$node.data_map.corps_article}

Si l'outil de débugage est actif, nous apprenons que le template utilisé pour afficher le contenu d'un attribut basé sur le datatype Bloc XML est:

design/standard/templates/content/datatype/view/ezxmltext.tpl

L'emploi de la syntaxe:

{$node.object.data_map.corps_article.content}

renvoie quant à elle cette information:

Object(ezxmltext)

Que se soit le contenu du template ezxmltext.tpl ou la lecture de la documentation de l'objet ezxmltext , on en déduit qu'une autre syntaxe possible est:

{$node.object.data_map.corps_article.content.output.output_text}

Et si l'on souhaite afficher le contenu au format XML, on peut utiliser la syntaxe:

{$node.object.data_map.corps_article.content.xml_data}

Conclusion

Le template de surcharge final ressemblera à quelque chose comme ça:

<h1>{$node.data_map.titre_article.content}</h1>
 
{foreach  $node.object.data_map.auteur.content.author_list as $Author}
Lauteur de cet article est: {$Author.name}<br />
Vous pouvez le contacter à l'adresse e-mail suivante: {$Author.email|wash( email )}
{/foreach}
 
<br />
<br />
 
 
{$node.object.data_map.corps_article.content.output.output_text}

Nous pouvons bien sûr ajouter du code XHTML, des classes CSS, etc... en fonction de nos besoins.

A travers l'exemple de cet article, nous sommes maintenant en mesure de faire à peu près n'importe quelle surcharge et avons tous les éléments en main pour aller chercher l'information nécessaire à la résolution de cas plus complexes que celui-ci.

Commentaires