Date de publication: le mardi 29 mars 2011 à 22h47
Dernière modification: par Pascal BOYER le mardi 17 mai 2011 à 01h54

28/09/2010 02:09

versions 3.9, 3.10, 4.x

The template override system makes it possible to use other templates than the default ones (specified in the code for the different views and templates). This mechanism allows the creation of template overrides for virtually any template that is used by eZ Publish (including templates that are requested by the "include" template function using the "design:" prefix). In particular, template overrides are typically useful for displaying different types of nodes in different ways.
Le système de surcharge de templates permet d'utiliser d'autres templates que ceux par défaut (spécifiés dans le code pour les différentes vues et les différents templates). Ce mécanisme permet la création de surcharges de template pour, virtuellement, n'importe quel template utilisé par eZ Publish (incluant les templates demandés par la fonction include qui utilise le préfixe design:). Les surcharges de template sont particulièrement utiles pour afficher différents types de nœuds de différentes manières.

An override for a view template is usually activated by a set of conditions. If the conditions match, the alternate template will be used. Different views provide different conditions, some views do not provide any conditions at all. Please refer to the "Template override conditions" section of the "Reference" chapter for a complete overview of the available match rules. The most flexible set of conditions are provided by the "view" view of the "content" module (used when a node is displayed). The following illustration shows how the override mechanism plugs into the rest of the system.
Une surcharge d'un template de vue est habituellement activée par un jeu de conditions. Lorsque celles-ci sont satisfaites, le template alternatif (de surcharge) est utilisé. Les différentes vues proposent différentes conditions de surcharge et certaines vues n'en proposent aucune. Référez-vous à la section Template override conditions (Conditions de mise en œuvre des surcharges de template) du chapitre Référence pour un aperçu complet des règles de concordances. Le jeu de conditions le plus flexible est fourni par la vue view du module content (utilisé lorsqu'un nœud est affiché). L'image suivante montre comment le mécanisme de surcharge se connecte au reste du système.

The override system
Le système de surcharge

The template overrides must be defined in the "override.ini.append.php" file of a siteaccess. This file consists of override blocks. A block is a named set of rules that tells eZ Publish to use an alternate template in a specific situation. For each block, the following information must be specified:
Les surcharges de template doivent être définies dans le fichier override.ini.append.php d'un siteaccess. Ce fichier se compose de blocs, chacun d'eux constituant un ensemble nommé de règles indiquant à eZ Publish d'utiliser, dans certaines conditions, un template alternatif particulier. Pour chaque bloc, les informations suivantes doivent être spécifiées:

• A unique name for the override
  Un nom unique de surcharge

• The template that should be overridden
  Le nom du template à surcharger

• The template that should be used instead of the one being overridden
  Le nom du template de surcharge

• The name of the directory in which the override template resides (usually "templates")
  Le nom du répertoire (usuellement, templates/) dans lequel est placé le template de surcharge

• A set of conditions/rules that control when the override should be activated
  Un ensemble de conditions/règles définissant quand la surcharge doit être employée

Please note that the rules/conditions are optional. If no rules are specified, the override will always be active. The following illustration shows a typical example of a template override with additional explanations.
Notez que les conditions/règles sont optionnelles. Si aucune règle n'est spécifiée, le template de surcharge sera toujours actif. L'image suivante illustre, avec quelques explication supplémentaires, un exemple typique d'une surcharge de template.

Template override example
Exemple de surcharge de template

The example above defines an override called "special_folders". This override will be used when the system is requested to display a node using the full view node. The override will only be activated if the object referenced by the node is an instance of the folder class and if it belongs to section number 34. When the override is activated, the system will attempt to use the alternate template ("/override/templates/special_folder.tpl", located in the main design). If eZ Publish is unable to find the alternate template, it will look for it in the additional designs and the standard design. Please refer to the documentation page of the "Automatic fallback system" for more information about this feature.
L'exemple ci-dessus définit une surcharge nommée special_folders. Cette surcharge sera utilisée lorsque l'on demandera au système d'afficher un nœud en utilisant le mode de vue full. La surcharge ne sera activée que si l'objet référencé par le nœud est une instance de la classe folder et si cet objet appartient à la section 34. Quand la surcharge est activée, le système essaie d'utiliser le template de surcharge (/override/templates/special_folder.tpl, placé dans le design principal). Si eZ Publish ne peut trouver le template alternatif (de surcharge), il le cherchera dans les design additionnels puis dans le design standard. Référez-vous à la page de documentation du Système de repli automatique pour de plus amples informations sur cette fonctionnalité.

Multiple / conflicting overrides -- Surcharges multiples et conflits

The priorities of the overrides are determined by their positions in the file. If there are several overrides with similar/equal rules, eZ Publish will use the first override that matches and thus the rest of the overrides will be omitted. Because of this, overrides that are for example activated on a node ID or an object ID basis should always be placed first; otherwise they might never be triggered because of the presence of a more generic override with a higher priority.
La priorité d'application des surcharges est fixée par la position celles-ci dans le fichier override.ini.append.php. S'il existe plusieurs surcharges composées de règles identiques/similaires, alors eZ Publish utilise la première surcharge satisfaisant aux conditions et ignore toutes les autres. Pour cette raison, les surcharges activées, par exemple, pour un ID de nœud ou pour un ID d'objet devront toujours être placées en premier sans quoi elles risquent de n'être jamais utilisées en raison de l'existence d'autres surcharges génériques de priorité plus élevée.

Commentaires