Date de publication: le jeudi 19 juillet 2007 à 15h58
Dernière modification: par Pascal BOYER le samedi 4 septembre 2010 à 00h20

13/05/2008 4:03  

versions 3.9, 3.10 et 4.0

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 différents templates). Ce mécanisme permet la création de template de surchage pour, virtuellement, n'importe quel template utilisé par eZ publish  (incluant les templates qui sont demandés par la fonction include  qui utilise le préfixe design:  ). En particulier, les templates de surcharge sont particulièrement adaptés 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. Si les conditions sont satisfaites, le template alternatif (de surcharge) sera utilisé. Différentes vues produisent différentes conditions. Certaines vues ne produisent aucune condition. Référez-vous à la section Template override conditions  (Conditions de surcharge de template) du chapitre Référence pour un apperç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 raccorde 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 templates de surcharge doivent être définis dans le fichier override.ini.append.php  du siteaccess. Ce fichier se compose de blocs. Un bloc est un ensemble nommé de règles indiquant à eZ publish  d'utiliser, dans certaines conditions, un template alternatif. Pour chaque bloc, les informations suivantes doivent être spécifiées:

• A unique name for the override  
  Un nom unique pour la surcharge.

• The template that should be overridden  
  Le nom du template devant être surchargé.

• 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 (de 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 template de surcharge.

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 appelée special_folders . Cette surcharge sera utilisée lorsqu'on demande 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 plus d'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é des surcharges est définie par la position des surcharges dans le fichier override.ini.append.php . S'il y a plusieurs surcharges composées de règles identiques/similaires, alors eZ publish  utilisera la première surcharge répondant aux règles et les autres surcharges seront donc ignorées. Pour cette raison, les surcharges qui sont, par exemple, activées pour un ID de nÅ“ud ou pour un ID d'objet devront toujours être placées en premier. Sinon, elles risquent de n'être jamais employées parce que d'autres surcharges génériques, ayant une priorité plus élevée, existent.

Commentaires