Date de publication: le mercredi 2 mai 2007 à 20h10
Dernière modification: par Pascal BOYER le mercredi 8 août 2007 à 23h05
« Article précédent: eZ publish: les designs
» Article suivant: eZ publish: le fichier site.ini.append.php

Les templates sont la clef de voute du système eZ publish. Vous devez prendre le temps de lire la doc (relativement courte) qui leur est consacrée.

Voici les points essentiels:

• Les templates sont des fichiers dont l'extension est .tpl

• Les templates sont des fichiers contenant
  • du code spécifique à eZ publish (très proche du langage PHP). Ce code est toujours placé entre accolades ( "{" et "}" )
  • du (X)HTML valide 1.0 Transitional

• Le rôle principal des templates est d'extraire les informations des objets instanciés à partir des classes d'objet et d'indiquer au système comment afficher ces informations.

• Les templates sont obligatoirement placés dans un sous-répertoire du répertoire templates/ des designs existants:
  • design/admin/templates/
  • design/base/templates/
  • design/plain_site/templates/
  • design/standard/templates/

:
Une page HTML est le résultat produit par plusieurs templates.

• Les templates sont:
  • soit des templates de noeud
  • soit des templates système

Les deux différences essentielles entre ces deux types de template sont:

• les règles de surcharge qu'ils supportent (elles sont plus flexibles pour les templates de noeud que pour les templates système)

• les variables auxquelles ils permettent d'accéder (une seule pour les templates de noeud et plusieurs pour les templates système)

Templates de noeud

Les templates de noeud sont systématiquement utilisés lorsque le système doit afficher le contenu d'un objet (un article, une galerie d'images, une news, un post, etc...). Ces templates correspondent à des modes de vue: full, line, etc... et sont situés dans le sous-répertoire /node/view/ du répertoire templates/ des deux designs suivants:

• design/admin/templates/node/view/
• design/standard/templates/node/view/

Le système sait quel mode de vue il doit utiliser car cela est indiqué dans l'URI de l'objet à afficher.

:
Les templates de noeud ne donnent accès qu'à une seule variable: $node

Cette variable est en fait un tableau contenant beaucoup d'informations sur le noeud considéré, c'est à dire le noeud traité en vue de l'affichage de son contenu. Une syntaxe particulière (mais simple) du langage propre à eZ publish permet d'extraire exactement l'information souhaitée pour, éventuellement, l'afficher sur une page du site.

Par exemple, le code ci-dessous:

{$node.object.current.creator.name}

permet d'extraire et d'afficher le nom de la personne qui a créé l'objet courant.

Quant à celui-ci:

{$node.object.published|datetime('custom', '%l %j %F %Y à %Hh%i' )}

il permet d'extraire l'heure et la date de première publication de l'objet courant.

Templates système

Les templates système sont utilisés chaque fois que ce n'est pas un template de noeud qui est utilisé. Donc, chaque fois que le système doit afficher autre chose que le contenu d'un noeud.

Que peut bien afficher le système qui ne soit le contenu d'un noeud ?

Et bien, par exemple, la page pour se loguer à l'interface d'administration, la page de rédaction d'un post, ou d'un mail, la page du système de recherche avancée, la page de création d'un compte, etc...

:
Les templates système fournissent des interfaces HTML à des fonctionnalités du système eZ publish

Surcharge de templates

:
De la même manière que nous ne devons pas modifier les fichiers de configuration par défaut, nous ne devons pas non plus modifier les templates par défaut qui seront, eux aussi, remplacés/écrasés lorsque nous mettrons à jour notre système avec une version plus récente de eZ publish.
D'ailleurs, tous les templates par défaut commencent par cette ligne:

1 {* DO NOT EDIT THIS FILE! Use an override template instead. *}

Traduction: N'EDITEZ PAS CE FICHIER! Utilisez une surcharge à la place.

:
Le système de surcharge de templates a pour but de nous permettre de créer des templates personnalisés que le système utilisera en lieu et place des templates par défaut.
Les templates personnalisés sont appelés templates de surcharge

• La plupart du temps, ce sont des templates de noeud personnalisés que nous créons et dans une moindre mesure des templates système personnalisés.

• Pour qu'un template de surcharge soit utilisé il faut en informer le système. Pour cela, chaque siteaccess du système dispose d'un fichier comptabilisant les règles de surcharge qui le concernent. Ce fichier se nomme override.ini.append.php

• Si une règle de surcharge est définie dans le répertoire de surcharges générales, c'est à dire dans le fichier settings/override/ override.ini.append.php, alors cette règle sera appliquée pour tous les siteaccess.

Pour chacune des règles de surcharge il faut définir:

• un nom unique de surcharge (placé entre crochets) (ligne 3)
• le chemin menant au template source devant être surchargé (ligne 4)
• le chemin menant au template de surcharge (ligne 5)
• l'emplacement du template de surcharge (ligne 6)
• la règle de surcharge, c'est à dire la condition devant être satisfaite pour que la surcharge s'applique. (ligne 7)

Voici à quoi ressemble la première règle de surcharge définie, par défaut, pour le siteaccess public:

3 [full_folder]
4 Source=node/view/full.tpl
5 MatchFile=full/folder.tpl
6 Subdir=templates
7 Match[class_identifier]=folder

• Ligne 4: le chemin indiqué est toujours un chemin relatif au chemin suivant: design/design_courant/templates/. Comme nous l'avons vu plus haut, seul le design standard contient, par défaut, un répertoire /templates/node/view/

• Ligne 5: le chemin indiqué est toujours un chemin relatif au chemin suivant: design/design_courant/override/répertoire_indiqué_par_ligne_6/. Donc dans l'exemple ci-dessus, eZ publish va rechercher le template de surcharge suivant:

design/plain_site/override/templates/full/folder.tpl

• Ligne 6: le répertoire indiqué doit toujours être un sous-répertoire de design/design_courant/override/.

• il est possible d'indiquer plusieurs conditions de surcharge. Pour connaître les conditions que nous pouvons définir, nous devons impérativement respecter les indications de ce document: template override conditions

Ordre de recherche des templates

Il n'est pas toujours nécessaire de recourir aux règles de surcharge pour surcharger un template par défaut. Il peut être suffisant de faire une copie du template par défaut dans le répertoire idoine du design courant.

Par exemple, si le template utilisé par défaut est:

design/standard/templates/content/datatype/view/ezxmltags/literal.tpl

il vous suffit de faire une copie de ce template dans le design courant en reprenant le même chemin:

design/plain_site/templates/content/datatype/view/ezxmltags/literal.tpl

pour que le système utilise automatiquement cette copie de template (on ne parle pas ici de surcharge de template. Il s'agit d'une simple copie de template).

pagelayout.tpl

Le template le plus important est le template pagelayout.tpl dont le contenu est le strict minimum qu'affiche eZ publish.

Afficher les templates utilisés

Particulièrement lorsqu'on débute avec eZ publish, on se sent un peu perdu au milieu de tous ces fichiers de configuration, de templates, etc.. et on ne sait plus vraiment où et quoi regarder.

Heureusement, les développeurs de eZ publish ont mis au point un outil de débugage qui s'avère extrêmement utile et puissant et qu'il est urgent de découvrir.

De cet outil, n'est présentée ici que la fonction qui permet d'afficher sur le site public, en plus du contenu des pages, l'ensemble de tous les templates utilisés, templates par défaut comme templates de surcharge. Nous serons donc en mesure de savoir très précisément quel template chaque partie de notre site utilise et dans quel répertoire il se situe exactement !

Cet outil, situé à droite de l'interface d'administration, ressemble à ceci:

Fig. 1: Les deux options à cocher pour afficher les templates utilisés par le siteaccess luxpopuli

Pour utiliser cet outil nous devons toujours commencer par sélectionner, dans le menu déroulant, le siteaccess. Ce qui aura pour effet de recharger l'affichage du menu et de présenter les options qui sont actuellement affectées au siteaccess sélectionné.

Ensuite, nous cochons les deux options suivantes:

• Template debug: active l'affichage des templates utilisés dans le code source des pages HTML produites.
• Inline template debug: active l'affichage des templates utilisés directement sur les pages HTML produites. Cette option ne peut fonctionner seule et nécessite que la première soit aussi activée

...puis nous validons en cliquant sur Set.

Chaque fois que nous utilisons cet outil et cliquons sur le bouton Set, le système écrit dans le fichier de surcharge site.ini.append.php du siteaccess sélectionné les valeurs des options.

Lorsqu'aucune option n'est cochée, le fichier site.ini.append.php contient la rubrique suivante:

[TemplateSettings]Debug=disabled
 ShowXHTMLCode=disabled
 ShowUsedTemplates=disabled

L'option Template debug, lorsqu'elle est cochée, entraine la modification suivante de la section [TemplateSettings]:

[TemplateSettings]
 Debug=enabled
 ShowXHTMLCode=disabled
 ShowUsedTemplates=disabled

Lorsque les deux options sont cochées, la section est ainsi modifiée:

[TemplateSettings]
 Debug=enabled
 ShowXHTMLCode=enabled
 ShowUsedTemplates=disabled

L'ensemble des paramètres disponibles de la section [TemplateSettings] sont largement commentés dans le fichier de configuration site.ini.

Il faut savoir que si nous cochons les deux options, tout visiteur de passage sur notre site sera en mesure de voir l'affichage de chacune des lignes indiquant le chemin complet des templates utilisés. Pour éviter cela, il est possible de spécifier une ou plusieurs adresses IP de machines qui seules pourront afficher les informations produites par l'outil de debugage.

Pour cela, ajoutons la ligne suivante à la section [DebugSetting] du fichier de surcharge site.ini.append.php:

[DebugSettings]
DebugIPList[]=182.135.7.33

Pour plus d'informations se reporter à la lecture des commentaires du fichier site.ini.

Commentaires