Ce fichier permet de définir un gabarit et les zones qui lui sont associées Il se place dans le répertoire cms/skins/[skinName]/templates/[templateName], il est optionnel mais fortement recommandé afin de décrire au minimum la zone "default" utilisé par défaut par certains plugins Ametys.
Format
template.xml
<template> <label i18n="true|false">...</label> <description i18n="true|false">...</description> <thumbnail> <small>path_to_16px_image_relative_to_resources_dir</small> <medium>path_to_32px_image_relative_to_resources_dir</medium> <large>path_to_48px_image_relative_to_resources_dir</large> </thumbnail> <zones> <zone id="..." inherit="..." type="primary|secondary"> <label i18n="true|false">...</label> <description i18n="true|false">...</description> <thumbnails> <small>path_to_16px_image_relative_to_resources_dir</small> <medium>path_to_32px_image_relative_to_resources_dir</medium> <large>path_to_48px_image_relative_to_resources_dir</large> </thumbnails> </zone> </zones> </template>
Tous les libellés et les descriptions sont internationalisables. Le catalogue utilisé par défaut est celui de la charte graphique se trouvant dans le dossier cms/skins/[skinName]/i18n/.
Les images de prévisualisation et les pictogrammes doivent se trouver dans le dossier resources/ du gabarit : cms/skins/[skinName]/templates/[templateName]/resources/. Elles sont ensuite appelées via un chemin relatif : img/thumb_16.png.
Héritage de zones
Les zones ont une notion d'héritage. Par défaut, les zones ne sont pas héritées, de sorte que si une zone ne contient aucun contenu ou service, elle reste vide. Il est possible d'intégrer une notion d'héritage qui permet, lorsqu'une zone est vide, de récupérer les contenus et/ou services de son parent.
Pour cela, utiliser l'attribut inherit sur la balise zone. Sa valeur peut-être :
- vide, il hérite alors des contenus ou services insérés dans la zone portant le même nom de son parent.
- le nom d'une zone, il hérite alors des contenus ou services insérés dans la zone de son parent portant ce nom
- le nom d'un gabarit vers le nom d'une zone, il hérite alors des contenus ou services insérés dans la zone portant ce nom, si son parent utilise ce gabarit.
Cas 1 - Pas d'héritage
<zone id="z1"/>
L'attribut inherit n'existe pas, il n'y a pas d'héritage
Cas 2 - Héritage simple
<zone id="z1" inherit=""/>
<zone id="z1" inherit="z1"/>
<zone id="z1" inherit="*->z1"/>
La zone z1 hérite de la zone z1 de la page mère. Pour éviter les erreurs dans les journaux, tous les gabarits doivent définir la zone z1.
Cas 3 - Héritage à partir d'une autre zone
<zone id="z1" inherit="z2"/>
La zone z1 hérite de la zone z2 de la page mère. Pour éviter les erreurs dans les journaux, tous les gabarits doivent définir la zone z2.
Cas 4 - Héritage selon le gabarit
<zone id="z1" inherit="t1->z1,t2->z2"/>
La zone z1 hérite de :
- la zone z1 si la page mère utilise le gabarit t1,
- la zone z2 si la page mère utilise le gabarit t2.
Cas 5 - Héritage conditionnel
<zone id="z1" inherit="*->z1,t2->z2,t3->"/>
La zone z1 hérite de :
- la zone z2 si la page mère utilise le gabarit t2,
- rien si la page mère utilise le gabarit t3,
- la zone z1 dans tous les autres cas.
Héritage racine
Depuis Ametys 4.6, il est possible de créer un gabarit spécial "sitemap" (qui ne peut pas être affecté à une page).
Le gabarit "sitemap" est automatiquement assigné à la racine du plan du site. La racine devient alors visualisable dans le CMS (et uniquement dans le CMS) afin de pouvoir y remplir des zones. L'intérêt est que ces zones pourront être héritées dès les pages racines du plan du site.
Exemple, j'ajoute le service Flux RSS personnalisable sur la racine du plan du site dans la zone 3 : il est disponible par héritable sur toutes les pages (avec une personnalisation partagée) sur toutes les zones qui héritent de "sitemap->zone3".
Actuellement il n'est possible d'insérer que des services dans la racine du plan du site.
Tous les services ne fonctionnent pas correctement par héritage et en particulier depuis la racine du plan du site.
Type de zones
Déclaration
Lors de la déclaration d'une zone, il est possible de préciser le type en attribut : primaire (primary) ou secondaire (secondary).
Par défaut les zones sont primaires.
Les zones primaires sont les zones principales du gabarit. En général il n'y en a qu'une, mais l'ordre de déclaration compte sinon.
Il doit toujours y avoir au moins une zone primaire.
Utilisation
Sur les version 3.7 et plus récente d'Ametys, l'assistant de création de page tient compte du type de zone pour placer le contenu/service principal : ils sont placés sur la première primaire.
De même lors de l'affectation d'un nouveau gabarit via le menu, la première zone primaire est sélectionnée par défaut.
Zone "default"
Une zone d'identifiant "default" est toujours la plus prioritaire.
Ainsi par compatibilité, les chartes 3.5 qui n'ont aucune zone primaire mise en avant mais disposant d'une zone "default" fonctionneront comme attendu.
A noter, qu'il est toujours intéressant d'avoir comme zone primaire principale "default" : ceci pour d'autres fonctionnalités ou plugins.
Paramètres de gabarits, zones et éléments de zones
Il est possible de paramétrer ces éléments par l'utilisateur.
Lire la page suivante : Paramètres de vue
Héritage de charte du fichier template.xml
A partir de Ametys 4.3, il est possible d'hériter d'une charte et donc de ses templates.
Cependant un fichier template.xml dans une charte enfant remplace purement et simplement celui de la charte parent.
A partir de Ametys 4.7, il est possible d'hériter de certains attributs à l'intérieur d'un fichier template.xml en suivant la documentation suivante.
Fichier absent
Comme la règle d'héritage générique l'indique, si le fichier est absent, c'est le fichier de la charte parente qui est utilisé.
Héritage
Si le fichier est présent il va être mélangé au fichier de la charte parente selon les règles suivantes :
- Si <label>, <description> ou <thumbnail> est spécifié dans la charte fille, il remplace celui de la charte parente, sinon il en hérite,
- Pour <parameters>
- Il est possible de désigner un <parameter> existant dans la charte parente en utilisant le même attribut "name",
sa définition remplace celle de la charte parent - Il est possible de supprimer un <parameter> existant dans la charte parente en utilisant le même attribut "name",
et en ajoutant l'attribute remove="true".
- Il est possible de désigner un <parameter> existant dans la charte parente en utilisant le même attribut "name",
- Pour <zones>
- Il est possible de désigner une <zone> existante dans la charte parente en utilisant le même attribut "id",
sa définition remplace celle de la charte parent - Il est possible de supprimer une <zone> existant dans la charte parente en utilisant le même attribut "id",
et en ajoutant l'attribute remove="true".
- Il est possible de désigner une <zone> existante dans la charte parente en utilisant le même attribut "id",
<template> <parameters> <parameter name="existinginparent-1" type="boolean">...</parameter> <parameter name="existinginparent-2" remove="true"/> <!-- other parameters from parent are kept --> </parameters> <zones> <zone id="existinginparent-1" type="secondary">...</parameter> <zone id="existinginparent-2" remove="true"/> <!-- other zones from parent are kept --> </zones> </template>
Bloquer l'héritage
Par défaut, l'héritage s'applique, mais si le fichier possède l'attribut inherit="false", alors c'est uniquement le fichier local qui est utilisé.
<?xml version="1.0" encoding="UTF-8" ?> <template inherit="false"> ... </template>
Le fichier template-default.xml
A partir de Ametys 4.8
Il est possible de disposer dans la charte graphique d'un fichier cms/skins/[skinName]/conf/template-default.xml qui servira de valeur par défaut pour tous les fichiers template.xml.
Il existe l'équivalent d'un héritage entre ces 2 fichiers, donc il est possible d'utiliser les options décrites ci-dessus entre ces deux fichiers.
D'autre part, il est possible de mélanger ce pseudo héritage, avec un héritage de charte classique : dans ce cas, voici l'ordre des opérations :
- Le fichier template-default.xml final est déterminé par héritage de charte.
- Le fichier template.xml final est déterminé par héritage de charte.
- Le fichier complet est celui pseudo-hérité entre ces deux fichiers finaux.
Retour en haut