Date de publication: le lundi 28 mars 2011 à 22h18
Dernière modification: par Pascal BOYER le lundi 4 avril 2011 à 14h35
Table des matières
- The pagelayout -- Le template pagelayout.tpl
- The page head -- L'en-tête de page (page_head.tpl)
- Variables in pagelayout -- Variables du template pagelayout.tpl
versions 3.9, 3.10, 4.x
The page layout is the main template. Among other things, it dictates the overall look of a site. The file name of the page layout 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 page layout within the current design (specified by the siteaccess), it will attempt to use the page layout 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 la charte graphique générale du site. Ce template 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 (lié au siteaccess utilisé) alors il essaie 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 nommé example:
The location of the pagelayout (main) template
Emplacement du template (principal) pagelayout.tpl pour le design example
The page layout contains the HTML, HEAD and BODY tags (the other 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 page layout:
Le template pagelayout.tpl, contenant les balises HTML, HEAD et BODY, est également utilisé pour décrire la structure visuelle/graphique (mise en page principale, logo, menu principal, pied de page etc...) utilisée pour la présentation de chacune des pages 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 page layout is used to declare 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 page layout.
La toute première ligne de ce template permet de déclarer le type de document des pages que eZ Publish génère. Avec HTML et XHTML standards, un DOCTYPE (raccourci de déclaration 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 sa présence au tout début 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 constitue l'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 contient un URI complet indiquant 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 absente, incomplète ou périmée positionne la plupart des navigateurs dans un mode appelé "Quirks" (caprice). Dans ce mode, les navigateurs se comportent comme si le document avait été écrit avec des balises désuètes et invalides et avec du code non normé datant de la fin des années 1990. En clair, la page sera affichée sans tenir compte des standards actuels et sera très certainement invalide 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 le contenu balisé 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 constitue une famille des types de documents et des modules actuels et futurs qui reproduisent, divisent en sous-ensembles et étendent le HTML 4. Les types de documents de la famille XHTML sont basés sur XML ce qui signifie qu'il sont créés pour être 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 utile d’identifier le langage naturel ou formel dans 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 représenter la langue utilisée sur l'ensemble du site. Les valeurs de ces attributs sont des identifiants de langues 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 styles CSS utilisées, une description du document lui-même, des mots clef, etc...
Cascading Style Sheets / Les feuilles de styles en cascade
The page layout in the example above makes use of two CSS files: "core.css" and "debug.css". The code encapsulated by curly brackets is eZ Publish specific code. What happens here is that the text within the quotes is 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 ajoute avant le texte ("stylesheets/core.css" dans notre exemple) le chemin complet vers le répertoire du design courant (ce dernier étant défini par le paramètre de configuration SiteDesign). Cette technique permet de s’assurer que les chemins vers les fichiers CSS sont toujours corrects, indépendamment de la
méthode d’accès
utilisée. Si le nom du design courant est, par exemple, 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.css" 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 styles 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 dédiée à l'appel des feuilles de style produit le plus souvent un code semblable à celui-ci:
...
<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 page layout. 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 doit 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 des 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 à la présentation graphique que l’on souhaite obtenir, il faut alors placer une version modifiée de ce fichier dans le design personnalisé utilisé. Cependant, la meilleur solution consiste à 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é. Le 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 la mise en production de ce dernier.
Document information / Informations 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 peut 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
placé 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 page layout 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 page layout 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 toutes les informations nécessaires sur le module qui a été exécuté, 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 page layout 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 page layout.
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 page layout 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 l'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’engendre une quelconque 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.
Table des matières
- The pagelayout -- Le template pagelayout.tpl
- The page head -- L'en-tête de page (page_head.tpl)
- Variables in pagelayout -- Variables du template pagelayout.tpl
Commentaires