Date de publication: le lundi 28 mars 2011 à 20h56
Dernière modification: par Pascal BOYER le mercredi 30 mars 2011 à 17h40

28/09/2010 11:31

versions 3.9, 3.10, 4.x

This section explains the concepts behind templates and the template system. eZ Publish uses templates as the fundamental unit of site design. A template is basically a custom HTML file that describes how some particular type of content should be visualized. A template file always ends with a ".tpl" extension. Actual HTML code in the built-in/default templates follow the XHTML 1.0 Transitional specification. In addition to standard HTML syntax, a template consists of eZ Publish specific code. The eZ Publish specific code makes it possible to extract information from the system and to solve common programmatic issues like for example conditional branching, looping, etc. All eZ Publish specific code must be placed inside a set of curly brackets, "{" and "}". The following example shows a part of a template that prints out the current time: 
Ce chapitre explique et les concepts sous-jacents aux templates et le système de templates lui-même. eZ Publish utilise les templates en tant qu’entités fondamentales du design d'un site. Un template est un fichier HTML personnalisé qui décrit comment doivent s'afficher les différents types de contenu. Le nom d’un template se termine toujours par l’extension .tpl. Le code HTML des templates fournis par défaut avec eZ Publish respectent les spécifications XHTML 1.0 Transitional. En plus du code HTML standard, un template contient du code spécifique à eZ Publish permettant d’extraire des informations sur le système et de résoudre des problèmes de programmation courants comme, par exemple, des branchements conditionnels, des boucles etc... Tout code spécifique à eZ Publish doit obligatoirement être écrit entre accolades "{" et "}". L’exemple ci-après est la partie du code d’un template affichant l’heure courante:

...
<h1>Time machine</h1>
<p>
     The current time is: {currentdate()|l10n( time )}
</p>
...

The example above demonstrates how standard HTML is mixed with eZ Publish specific code. It shows the usage of the "currentdate" and the "l10n" template operators. Since "currentdate" returns a UNIX timestamp, it must be formatted using the "l10n" localization operator (or else the output would not make any sense to humans). This is done by piping the output from the "currentdate" operator into the "l10n" operator, which will output the requested information according to the current locale settings. The "time" parameter tells the operator to output only the time (it could have been "date", "shortdate", "datetime" and so on). 
L’exemple ci-dessus montre comment du code HTML standard peut être combiné à du code spécifique eZ Publish. Il illustre également l'emploi des opérateurs currentdate et l10n. L’opérateur currentdate retournant une valeur temps au format timestamp UNIX, celle-ci doit être formatée par l’opérateur de localisation l10n (sans cela, cette valeur n’aurait aucun sens pour un humain). Ce formatage est réalisé en pipant (lire "paillepant" - c’est à dire "en redirigeant") la valeur retournée par l’opérateur currentdate vers l’opérateur l10n qui, lui, retournera l’heure en tenant compte des paramètres de localisation. Quant au paramètre time, il indique à l’opérateur currentdate de ne retourner que l’heure (on aurait pu prendre date ou shortdate ou datetime etc... en lieu et place de time).

Template generation / Génération de templates

The template system is component based. In other words, an actual HTML page is usually made up of several templates. At the minimum, eZ Publish always renders the main template, which is called pagelayout. The pagelayout contains the HTML, HEAD and BODY tags; it dictates the overall look of a site. Among other things, it describes the visual structure (main layout, logo, main menu, footer, etc.) that will be presented for each HTML page that the system generates. 
Le système de template est constituer de composants. Cela signifie qu’une page HTML est le résultat du traitement de plusieurs templates. A minima, eZ Publish affiche toujours le rendu produit par le template principal pagelayout.tpl dans lequel on trouve les balises HTML, HEAD et BODY. Ce template dicte par ailleurs l’ensemble de la mise en page du site. Ce fichier décrit, entre autres, la structure graphique (logo, mise en page principale, menu, pied de page etc...) de chaque page HTML générée par le système.

Every incoming request tells eZ Publish to run a specific module and to execute one of the module's views. When finished, the requested module/view combination will generate a result. The result can be accessed through the $module_result array which is available in the pagelayout template. The following illustration shows a simplified 3-step explanation of how eZ Publish responds to an HTTP request. 
Chaque requête entrante indique à eZ Publish d’exécuter un module bien spécifique ainsi qu’une des vues de ce module. Lorsque s'achève l’exécution de ce module et de la vue associée, la combinaison module/vue génère un résultat accessible via le tableau $module_result disponible dans le template pagelayout.tpl. L’illustration suivante présente, de façon simplifiée, les trois étapes nécessaires à eZ Publish pour répondre à une requête HTTP:

Client - server cycle
Cycle client-serveur.

Every view generates a chunk of HTML code by making use of a template. Templates that are used by views are often referred to as view templates. Whenever a view has finished running, it will issue an internal template request. The requested template will be interpreted, processed and thus converted to HTML. After processing, the system will put the resulting HTML in the module's result array. The module/view's result can be accessed through the ".content" extension: {$module_result.content}. By printing out the contents of this variable, it is possible to include the HTML code that was generated by the view in the pagelayout. The following illustration shows how the module/view result (generated by different modules/views - depending on the request) is included in the pagelayout: 
Chaque vue génère, via l'usage d'un template, un bout de code HTML. Les templates utilisés par les vues sont appelés templates de vue. Chaque fois que l'exécution d'une vue se termine, cela engendre, en interne, une demande de template. Le template demandé est alors interprété, traité puis, finalement, converti en HTML. Le système place ensuite le code HTML résultant dans le tableau de résultat du module. Le résultat de l’exécution du module et de sa vue est accessible à partir de l'extension .content: { $module_result.content}. En affichant le contenu de cette variable, il est possible d’inclure dans le template pagelayout.tpl le code HTML généré par la vue. L’illustration suivante montre comment le résultat de l’exécution du couple module/vue (ce résultat peut être obtenu par l’exécution de plusieurs couples module/vue, cela dépend de la resuête HTTP) est inclus dans le template pagelayout.tpl 

The module result as a part of the pagelayout
Le résultat d'un module en tant que partie de pagelayout.tpl

View templates / Templates de vue

A template used by a view can either be a node template or a system template. A node template will only be used when a node is being viewed, for example when a system URL containing "/content/view" or the virtual URL of a node is requested. A system template typically provides an HTML interface to a specific eZ Publish feature. For example, the template used by the "search" view of the "content" module provides an interface to the built-in search engine. 
Un template utilisé par une vue est soit un template de nœud soit un template système. Alors qu'un template de nœud n'est utilisé que pour l’affichage d’un nœud - par exemple lorsqu’un URI contient content/view ou bien lorsque l’URI virtuel d’un nœud est demandé - un template système fournit, quant à lui, une interface HTML à une fonctionnalité spécifique de eZ Publish. Par exemple, le template utilisé par la vue search (recherche) du module content (contenu) fournit une interface avec le moteur de recherche intégré à eZ Publish.

The difference between the template types mentioned above is the available variables and the combination of override rules that can be used. A node template gives access to a variable ($node) which contains information about the actual node that is being viewed. Depending on the view that was called, a system template typically gives access to several variables. A template override rule makes it possible to display custom templates in specific cases. The override rules for node templates are much more flexible than the override rules for system templates. For example, it is possible to set up complex rule combinations that depend on the type of the node being viewed, the depth of the node in the tree, the section which the node's object is assigned to and so on. Please refer to the "The template override system" section for a detailed description of the template override mechanism. 
Ce qui distingue les deux types de templates dont il est question ci-dessus ce sont, d’une part, les variables disponibles et d’autre part, la combinaison de règles de surcharge pouvant être employées. Un template de nœud donne accès à la variable $node contenant les informations du nœud actuellement affiché. En fonction de la vue qui a été appelée, un template système peut donner accès à plusieurs variables. Une règle de surcharge (override) rend possible, dans certains cas, l’affichage de templates personnalisés. Les règles de surcharge des template de nœud sont plus flexibles que les règles de surcharge des templates système. Il est par exemple possible de paramétrer des combinaisons complexes de règles tenant compte du type de nœud que l’on souhaite afficher, de la profondeur de ce nœud dans l’arborescence, de la section à laquelle ce nœud est affecté, etc... Reportez-vous à la section Système de surcharge des templates  pour une description détaillée du mécanisme de surcharge (override).

Commentaires