The pagelayout -- Le template pagelayout.tpl
Date de publication: le Lundi 7 Mai 2007 à 16h13
Dernière modification: par Pascal BOYER le Dimanche 21 Décembre 2008 à 11h43
versions 3.9, 3.10 et 4.0
The pagelayout is the main template. Among other things, it dictates the overall look of a site. The filename of the pagelayout template must be "pagelayout.tpl". It has to be placed inside the "templates" directory of a design. If eZ publish is unable to find a pagelayout within the current design (specified by the siteaccess), it will attempt to use the pagelayout template that is provided by one of the fallback designs. The following illustration shows the location of the pagelayout template located in a design called "example".
Le template principal de eZ publish, nommé pagelayout.tpl, permet entre autres de déterminer l’aspect graphique de tout le site. Le nom de ce template principal doit être pagelayout.tpl et il doit être placé dans un sous-répertoire nommé templates d’un design. Si eZ publish ne trouve pas ce template dans le design courant (qui est spécifié par le siteaccess) alors il essaiera d’utiliser le template pagelayout.tpl fourni par un design de repli. L’illustration suivante montre l’emplacement du template pagelayout.tpl dans le cas d’un design appelé example:
Emplacement du template principal pagelayout.tpl pour le design example
The pagelayout contains the HTML, HEAD and BODY tags (the outher HTML framework). In addition, it dictates the overall look of a site. Among other things, it is used to describe the visual structure (main layout, logo, main menu, footer, etc.) that will be presented for every page request. The following example shows what is considered to be the most basic pagelayout:
Le template pagelayout.tpl, contenant les balises HTML, HEAD et BODY, est utilisé, entre autres, pour décrire la structure visuelle/graphique (mise en page principale, logo, menu principal, pied de page etc...) du site. L’extrait de code ci-dessous montre le contenu du template pagelayout.tpl le plus basique/simple possible:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<style type="text/css">
@import url({'stylesheets/core.css'|ezdesign});
@import url({'stylesheets/debug.css'|ezdesign});
</style>
{include uri='design:page_head.tpl'}
</head>
<body>
{$module_result.content}
<!--DEBUG_REPORT-->
</body>
</html>The document type / Le type de document
The very first line in the pagelayout is used to decalare the document type of the pages that are generated by eZ publish. Per HTML and XHTML standards, a DOCTYPE (short for "document type declaration") informs browsers and syntax validation engines about which version of (X)HTML that is used. This information should be included at the very top of in every web page, this is why it is the first part of the pagelayout.
La toute première ligne de ce template permet de déclarer le type de document des pages que eZ publish génère. Par HTML et XHTML standards, un DOCTYPE (raccourci de type de document) informe les navigateurs et les moteurs de validation de syntaxes (validateur w3c) de la version du (X)HTML utilisée. Cette information devant être incluse au tout début de chaque page HTML cela explique la présence de la première ligne du fichier pagelayout.tpl
The DOCTYPE declaration is one of the key components when it comes to proper rendering and compliant web pages. A DOCTYPE that includes a full URL tells the browser to render the page in standards-compliant mode, treating the (X)HTML, CSS, and DOM structures as they should be treated according to the standards. A missing, incomplete or outdated DOCTYPE throws most browsers into something called "Quirks" mode. In this mode, the browser assumes that the document was written using old-fashioned, invalid markup and code per the chaotic industry norms of the late 1990s. In other words, the page will most likely not be rendered according to the standards and it will certainly not validate.
La déclaration DOCTYPE est un des composants clef permettant d’afficher correctement une page HTML et de la rendre conforme aux recommandations de mise en œuvre d’une page web. Une déclaration DOCTYPE contenant un URI complet indique au navigateur d’afficher la page web conformément aux standards, de traiter les structures (X)HTML, CSS et DOM, elles aussi, conformément aux standards. Une déclaration DOCTYPE manquante, incomplète, périmée, positionne la plupart des navigateurs dans un état appelé "Quirks" (caprice). Dans ce mode, les navigateurs se comportent comme si le document avait été écrit avec les critères désués, invalides et sans norme d’avant les années 1990. En clair, la page sera affichée sans tenir compte des standards et sera très certainement non valide au sens des recommandations du w3c.
The HTML tag / La balise <html>
The HTML tags encapsulate the marked up contents of an actual web page. In addition to the tag itself, the HTML tag in the example above includes a URL to the XHTML specification. XHTML is a family of current and future document types and modules that reproduce, subset, and extend HTML 4. The XHTML family document types are XML based, which means that they are designed to work in conjunction with XML-based user agents.
Les balises <html> encapsulent les déclarations du contenu d’une page web. Dans l’exemple de code présenté ci-dessus, en plus de la balise elle-même, la balise <html> inclu un URI vers le site de spécification du XHTML. XHTML est une famille de types de documents et de modules actuels et futurs qui reproduisent, divisent en sous-ensembles et étendent le HTML 4. La famille des documents de type XHTML étant basée sur XML cela signifie que ces documents sont créés de telle sorte qu'ils seront compatibles avec les navigateurs (logiciels clients) s’appuyant sur XML.
In document processing, it is often useful to identify the natural or formal language in which the content is written. The "lang" and "xml:lang" attributes specify the language of the entire HTML element. The value of the xml:lang attribute takes precedence. The language values should be set to the language that is used throughout the site. The values of the attributes are language identifiers as defined by ISO 3166-1 (and the corresponding ISO 3166-1-alpha-2) standards.
Lors du traitement d’un document, il est souvent bon d’identifier le langage naturel ou formel avec lequel est écrit le contenu du document. Les attributs lang et xml:lang spécifient le langage de tout l’élément HTML. La valeur de l’attribut xml:lang est prépondérante et doit être paramétrée avec le langage utilisé pour tout le site. Les valeurs des attributs sont des identifiants de langages tels que définis par le standard ISO 3166-1 (et le standard ISO 3166-1-alpha-2 correspondant).
The head tag / La balise <head>
The head tag contains information about the document itself. The information contained here doesn't show up on the page displayed in a web browser. Only the contents of the title tag will be made visible (as the title of the browser window). The head tag typically contains information about which CSS files that should be used, a description of the document itself, keywords and so on.
La balise <head> contient des informations sur le document lui-même. Les informations contenues ici ne sont pas visibles sur la page web affichée par le navigateur, execpté le contenu de la balise <title> qui sera visible en tant que titre de la fenêtre du navigateur. Typiquement, la balise <head> contient des informations sur les feuilles de style (CSS) qui doivent être utilisées, une description du document lui-même, des mots clef, etc...
Cascading Style Sheets / Les feuilles de styles en cascade
The pagelayout in the example above makes use of two CSS files: "core.css" and "debugs.css". The code encapsulated by curly brackets is eZ publish specific code. What happens here is that the text within the quotes are being piped into a template operator called ezdesign. The operator prepends the text with the path to the current design directory (the one which is specified using the "SiteDesign" configuration directive). This technique assures that the path to the CSS files are always correct, regardless of the access method that is being used. For example, if the name of the current design is "my_design" and it includes a CSS file called "example.css", the following output will be produced:
Dans l'exemple de code ci-dessus, le template pagelayout.tpl utilise les deux feuilles de style core.css et debug.css. Le code encapsulé dans des accolades ("{" et "}") correspond à du code spécifique à eZ publish. Le texte compris entre apostrophes ( ’ et ’ ) est "pipé" (lire paillepé, c’est à dire "redirigé") vers un opérateur de template appelé ezdesign qui renvoie le chemin complet dans le design courant du texte placé entre apostrophes (le design courant est celui défini par la directive de configuration SiteDesign). Cette technique permet de s’assurer que le chemin vers le fichier CSS est toujours correct (c'est à dire effectivement lié au désign du siteaccess courant) sans avoir à se soucier de la méthode d’accès utilisée. Par exemple, si le nom du design courant est my_design et qu’il inclus un fichier CSS nommé example.css, alors le code suivant sera généré:
@import url("/design/my_design/stylesheets/example.css");
Ce code sera visible en affichant le code source de la page affichée par le navigateur.
The "core.css" and "debug.ss" files are a part of the standard design that comes with eZ publish. It is not necessary to have these CSS files in the "stylesheets" directory of a custom design. If eZ publish is unable to find the files within the current/custom design, it will automatically use the ones that are in the standard design. Please refer to the description of the automatic fallback system for a detailed description of the fallback mechanism. Because of the fallback system, the style-part of the pagelayout presented above will most likely result in the following output:
Les feuilles de style core.css et debug.css sont une partie du design standard intégré à eZ publish (standard écrit en italique désigne le nom même du design). Il n’est pas nécessaire de mettre ces deux feuilles de style dans le sous-réperoire stylesheets/ d’un design personnel car si eZ publish ne les y trouve pas alors il utilisera automatiquement celles du design standard. Référez-vous à la documentation sur le système de repli automatique pour de plus amples détails sur ce mécanisme grâce auquel la partie du template pagelayout.tpl relative aux feuilles de style (présentée ci-dessus) produit le plus souvent un code ressemblant à ceci:
...
<style type="text/css">
@import url("/design/standard/stylesheets/core.css");
@import url("/design/standard/stylesheets/debug.css");
</style>
...
Ce code sera visible en affichant le code source de la page affichée par le navigateur.
The core stylesheet / La feuille de style core.css
The "core.css" file defines a standard set of basic styles (font styles, sizes, margins, etc.) for both general HTML elements and some eZ publish specific classes. The eZ publish specific classes are used by the standard templates. A site that makes an extensive use of the default templates should always have the "core.css" file included in the pagelayout. Otherwise, the missing styles may cause the unexpected rendering of various elements.
La feuille de style core.css définit un jeu standard de styles basiques (style de police, tailles, marges etc...) pour les éléments HTML généraux ainsi que pour quelques classes de eZ publish utilisées par les templates standards. Un site faisant un usage intensif des templates standards devra toujours inclure la feuille de style core.css dans le template pagelayout.tpl sous peine d’obtenir un rendu inattendu pour de nombreux éléments constituant les pages web.
The standard "core.css" file should never be changed. If there are basic styles in core.css that doesn't fit the visual environment of a site, a modified version of "core.css" may be placed in the custom design that the site uses. However, the recommended solution is to create a completely new CSS file that contains both custom classes and overrides for elements defined in "core.css".
Le fichier standard core.css ne doit jamais être modifié. Si les styles basiques définis dans ce fichier ne correspondent pas à l’aspect graphique du site que l’on souhaite obtenir, alors il faut placer une version modifiée de ce fichier dans les design personnalisés utilisés. Cependant, la meilleur solution reste de créer un nouveau fichier CSS incluant à la fois les classes personnalisées et les surcharges pour les éléments définis dans le fichier core.css original.
The debug stylesheet / La feuille de style debug.css
The "debug.css" file contains styles that are used to format the debug output which appears at the bottom of the page when debug output is enabled. The usage of the "debug.css" file is only necessary during the development of the site (typically when debug information is needed) and thus it can be removed or commented out before the site is launched.
La feuille de style debug.css contient les styles utilisés pour formater l’affichage du mode débugage. Cet affichage apparaît au bas des pages web lorsque le mode debug est activé. L’utilisation du fichier debug.css n’est nécessaire que pendant la phase de développement du site et peut donc être supprimé ou commenté lors de sa mise en production.
Document information / Information sur le document
The system is capable of automatically generating information about the page itself (title, meta tags, keywords, etc.). This can be done by the inclusion of the page_head template ("page_head.tpl"), which is located in the templates directory of the standard design. If eZ publish is unable to find the requested file in current/custom design, it will automatically fallback and use the file located in the standard design.
Le système est capable de fournir automatiquement des informations sur la page elle-même (titre, méta balises, mots clef, etc...) grâce à l'inclusion du template d’en-tête page_head.tpl situé dans le sous-répertoire templates/ du design standard. Si eZ publish ne trouve pas ce fichier dans le sous-répertoire templates/ du design courant/utilisé il utilisera automatiquement celui du design standard.
The body tag / La balise <body>
The body tag defines the document's body, which contains the actual contents of the web page (text, images, etc.) marked up in an orderly fashion. At the minimum, an eZ publish pagelayout should contain the result from the requested modules.
La balise <body> définit le contenu du document. Ce contenu, celui de la page web affichée (texte, image, etc...), est balisé de façon ordonnée. Le template pagelayout.tpl doit au minimum contenir le résultat des modules demandés.
Module result / Le tableau module_result
Upon every request, eZ publish automatically generates an array called "module_result". This array is available only in the pagelayout template. It contains all the necessary information about which module that was run, which view that was called, the output that was produced and so on. The actual output (for example the contents of a news article) can be included in the pagelayout by accessing the "content" element of the $module_result array, the syntax is:
Pour toutes les requêtes, eZ publish génère automatiquement un tableau appelé module_result accessible uniquement à partir du template pagelayout.tpl. Ce tableau contient les informations nécessaires sur le modules qui a été utilisé, sur la vue qui a été appelée, sur le code de sortie produit, etc... La sortie réelle (c’est à dire le contenu de la page affichée - un article de news par exemple) peut être incluse dans le template pagelayout.tpl en accédant à l’élément content du tableau $module_result. La syntaxe est la suivante:
{$module_result.content}
When the pagelayout is rendered, the {$module_result.content} part will be replaced with the actual output that the requested module produced. Please refer to the Variables in pagelayout page for an overview of the template variables that can be accessed from within the pagelayout.
Lorsque le template pagelayout.tpl est présenté/affiché, la partie {$module_result.content} est remplacée par le code (la sortie) produit par le module demandé. Référez-vous à la documentation Les variables du template pagelayout.tpl pour une vue d’ensemble des variables accessibles depuis le template pagelayout.tpl
Debug information / Informations de débugage
The last part of a typical eZ publish pagelayout is an HTML comment that looks like this:
La dernière partie d’un template pagelayout.tpl classique de eZ publish est un commentaire HTML ressemblant à ceci:
<!--DEBUG_REPORT-->
If the debug information is turned on, eZ publish will replace this comment with the actual debug report when the pagelayout is processed. In other words, the debug report will be included as a part of the generated page and thus it will not cause invalid output by breaking the HTML structure. The debug reports that eZ publish generates follow the XHTML 1.0 Transitional specification and thus the debug information validates.
Si on décommente cette ligne, alors eZ publish remplacera DEBUG_REPORT par le rapport de débugage engendré lors du traitement du template pagelayout.tpl. En d’autres termes, le rapport de débugage sera inclu et fera partie intégrante de la page web générée sans que cela n’engendrera aucune erreur dans la structure HTML de la page. Les rapports de debugage que génère eZ publish suivent les spécifications XHTML 1.0 Transitional. Les informations de débugage sont donc conformes à ces spécifications.
Commentaires
