User Documentation Emplacement et objectif
Vous pouvez voir un exemple de fichier templateDetails.xml répertorié dans Système → Templates du site → Détails et fichiers de Cassiopeia. Vous pouvez également le modifier à cet endroit si vous avez une bonne raison de le faire. Sinon, n'y touchez pas! Chaque template possède un tel fichier et un template enfant est initialement constitué d'une structure de fichiers ne contenant que ce seul fichier.
Le fichier templateDetails.xml contient les données dont Joomla! a besoin pour gérer et afficher le template. Cela comprend les métadonnées utilisées pour fournir des informations sur le template, les emplacements des dossiers et des fichiers, les positions des modules du template et les options de configuration sélectionnables par l'utilisateur. Le contenu du fichier templateDetails.xml diffère d'un template à l'autre.
Cassiopeia templateDetails.xml
Les fichiers au format xml ont une structure bien définie. Un fichier xml doit avoir une syntaxe correcte, sinon il ne fonctionnera pas!
Format XML
La première ligne de chaque templateDetails.xml doit commencer par la définition du doctype XML.
La ligne suivante indique à Joomla! que les données de ce fichier concernent une extension de template de site. Toutes les données du template sont contenues entre les balises d'ouverture et de fermeture.
<extension type="template" client="site">
...
</extension>
Métadonnées
La première section des données du template définit généralement les informations relatives au template, par exemple : noms, dates, informations de contact, droits d'auteur, numéro de version et description.
<extension version="3.1" type="template" client="site">
<name>cassiopeia</name>
<version>1.0</version>
<creationDate>2017-02</creationDate>
<author>Joomla! Project</author>
<authorEmail>Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser. </authorEmail>
<copyright>(C) 2017 Open Source Matters, Inc.</copyright>
<description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
<inheritable>1</inheritable>
Remarquez qu'un template pouvant avoir des templates enfants a la valeur inheritable définie sur 1. Les templates enfants ont cette valeur définie sur 0. Ces données sont utilisées dans la liste Templates : Templates (Site) comme indiqué ci-dessous.
La description contient une clé de langue et non la chaîne de texte de description réelle. La clé est remplacée par le texte obtenu à partir d'un fichier de langue au moment de l'exécution. Les fichiers de langue sont définis dans la section langue du fichier templateDetails.xml.
Dossiers et fichiers
Les dossiers et fichiers du template Cassiopeia sont stockés à deux endroits distincts. Les fichiers php et apparentés sont stockés dans le dossier site/templates. Les fichiers média (css, images, js et scss) sont stockés dans le dossier site/media. Ces emplacements sont définis dans le fichier xml comme suit :
<files>
<filename>component.php</filename>
<filename>error.php</filename>
<filename>index.php</filename>
<filename>joomla.asset.json</filename>
<filename>offline.php</filename>
<filename>templateDetails.xml</filename>
<folder>html</folder>
</files>
<media destination="templates/site/cassiopeia" folder="media">
<folder>js</folder>
<folder>css</folder>
<folder>scss</folder>
<folder>images</folder>
</media>
Voici le modèle que l'on retrouve dans tous les templates modernes de Joomla 4 et 5. La structure peut être observée dans le formulaire Templates : Personnaliser (Cassiopeia) :
Emplacements de modules
Les emplacements de modules disponibles sont définis comme suit :
<positions>
<position>topbar</position>
<position>below-top</position>
<position>menu</position>
<position>search</position>
<position>banner</position>
<position>top-a</position>
<position>top-b</position>
<position>main-top</position>
<position>main-bottom</position>
<position>breadcrumbs</position>
<position>sidebar-left</position>
<position>sidebar-right</position>
<position>bottom-a</position>
<position>bottom-b</position>
<position>footer</position>
<position>debug</position>
</positions>
Chaque balise crée un emplacement de module disponible dans la liste des emplacements d'un formulaire d'édition de module. Le format simple de la liste des emplacements permet de la personnaliser facilement. Par exemple, pour ajouter un nouvel emplacement de module à la liste dans un template enfant, il suffit d'ajouter une nouvelle balise à l'intérieur de la balise, avec un nom unique composé uniquement de lettres minuscules sans espaces. Gardez à l'esprit que cela ne fait qu'ajouter l'emplacement aux formulaires d'édition de module, et qu'un développement supplémentaire dans d'autres fichiers du template est nécessaire pour afficher le nouvel emplacement sur le site.
Cassiopeia dispose de suffisamment d'emplacements de template ! Si vous pensez avoir besoin d'un emplacement supplémentaire, vous avez probablement tort. N'oubliez pas qu'un nombre illimité de modules peut être assigné à un seul emplacement et trié dans la page de liste des modules. Emplacements disponibles :
Vous pouvez également visualiser les emplacements de modules de n'importe quel template : depuis Système → Templates du site, sélectionnez le bouton Paramètres dans la barre d'outils. Dans le formulaire Paramètres, réglez le champ Prévisualiser les emplacements de modules sur Activé. Enregistrer et fermer. Rendez-vous sur votre site et ajoutez ?tp=1 à la fin de n'importe quelle URL (ou &tp=1 si l'URL contient déjà un ?). Joomla affichera tous les emplacements de template disponibles, même ceux qui n'ont pas été utilisés :
Langues
Les fichiers de langue permettent la traduction du texte statique du template. Le fichier tpl_cassiopeia.ini contient les traductions clé-texte pour le texte visible par l'utilisateur. Le fichier tpl_cassiopeia.sys.ini contient les traductions clé-texte pour le texte visible par l'administrateur.
<languages folder="language">
<language tag="en-GB">en-GB/tpl_cassiopeia.ini</language>
<language tag="en-GB">en-GB/tpl_cassiopeia.sys.ini</language>
</languages>
Les fichiers de langue pour la langue par défaut, l'anglais GB, sont stockés dans site/language/en-GB/. Les autres langues seraient stockées de la même manière dans des fichiers portant le code de langue ISO approprié, par exemple fr-FR pour le français en France ou de-DE pour l'allemand en Allemagne (qui peut être différent de l'allemand suisse et de l'allemand autrichien).
Paramètres
Un template peut proposer des options d'affichage pouvant être choisies par l'Administration dans le formulaire Template : Modifier le style. Par exemple, l'onglet Avancé du template Cassiopeia permet à l'Administration de changer la marque, d'ajouter un logo, de sélectionner un jeu de polices, et plus encore.
Les options du template sont définies au sein d'une structure qui crée des champs dans des ensembles de champs (fieldsets). Chaque fieldset apparaît comme un onglet dans le formulaire d'édition. C'est cette structure qui crée l'onglet Avancé vu ci-dessus.
<config>
<fields name="params">
<fieldset name="advanced">
<field
name="brand"
type="radio"
label="TPL_CASSIOPEIA_BRAND_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
filter="boolean"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
...
</fieldset>
</fields>
</config>
Les options individuelles sont définies avec la balise <field>. Chaque <fieldset>, et chaque paramètre <field> au sein d'un <fieldset>, nécessite un nom unique défini par un attribut name. Ce nom définit le paramètre lui-même et est utilisé pour transmettre les réglages aux fichiers du frontal. Chaque paramètre contient également un attribut label et un attribut description. Le texte du label apparaît avec le paramètre dans l'écran des réglages pour identifier à quoi sert le réglage, et des informations plus détaillées peuvent être incluses dans la description.
Un champ de paramètre peut être pratiquement n'importe quel type de champ de formulaire avec les options correspondantes. Celui-ci est sélectionné par l'attribut type. Les options nécessaires, telles que les boutons radio ou les choix de sélection, sont définies dans des balises <option>. Les noms de classes CSS peuvent être définis avec l'attribut class et une valeur par défaut peut être définie à l'aide de l'attribut default.
Vous trouverez ci-dessous les définitions des options du template Cassiopeia par défaut. Dans cet exemple, tous les labels, descriptions et options utilisent des définitions de chaînes de langue provenant des fichiers de langue définis dans la section précédente, ainsi que de certaines provenant du cœur de Joomla!, afin qu'ils puissent être traduits dans différentes langues si nécessaire.
<config>
<fields name="params">
<fieldset name="advanced">
<field
name="brand"
type="radio"
label="TPL_CASSIOPEIA_BRAND_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
filter="boolean"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="logoFile"
type="media"
default=""
label="TPL_CASSIOPEIA_LOGO_LABEL"
showon="brand:1"
/>
<field
name="siteTitle"
type="text"
default=""
label="TPL_CASSIOPEIA_TITLE"
filter="string"
showon="brand:1"
/>
<field
name="siteDescription"
type="text"
default=""
label="TPL_CASSIOPEIA_TAGLINE_LABEL"
description="TPL_CASSIOPEIA_TAGLINE_DESC"
filter="string"
showon="brand:1"
/>
<field
name="useFontScheme"
type="groupedlist"
label="TPL_CASSIOPEIA_FONT_LABEL"
default="0"
>
<option value="0">JNONE</option>
<group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
<option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
</group>
<group label="TPL_CASSIOPEIA_FONT_GROUP_WEB">
<option value="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@100;300;400;700&display=swap">Fira Sans (web)</option>
<option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&family=Roboto:wght@100;300;400;700&display=swap">Roboto + Noto Sans (web)</option>
</group>
</field>
<field
name="noteFontScheme"
type="note"
description="TPL_CASSIOPEIA_FONT_NOTE_TEXT"
class="alert alert-warning"
/>
<field
name="colorName"
type="filelist"
label="TPL_CASSIOPEIA_COLOR_NAME_LABEL"
default="colors_standard"
fileFilter="^custom.+[^min]\.css$"
exclude="^colors.+"
stripext="true"
hide_none="true"
hide_default="true"
directory="media/templates/site/cassiopeia/css/global/"
validate="options"
>
<option value="colors_standard">TPL_CASSIOPEIA_COLOR_NAME_STANDARD</option>
<option value="colors_alternative">TPL_CASSIOPEIA_COLOR_NAME_ALTERNATIVE</option>
</field>
<field
name="fluidContainer"
type="radio"
layout="joomla.form.field.radio.switcher"
default="0"
label="TPL_CASSIOPEIA_FLUID_LABEL"
>
<option value="0">TPL_CASSIOPEIA_STATIC</option>
<option value="1">TPL_CASSIOPEIA_FLUID</option>
</field>
<field
name="stickyHeader"
type="radio"
label="TPL_CASSIOPEIA_STICKY_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="backTop"
type="radio"
label="TPL_CASSIOPEIA_BACKTOTOP_LABEL"
layout="joomla.form.field.radio.switcher"
default="0"
filter="integer"
>
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
</fieldset>
</fields>
</config>
Dans cet exemple, la balise <fieldset name="advanced"> englobe tous les paramètres et utilise l'attribut name pour créer l'onglet Paramètres avancés dans l'interface. Tout ce qui est nécessaire pour créer un autre onglet dans l'interface est une autre balise <fieldset> avec un attribut name différent. Avec cela à l'esprit, il est relativement simple de créer autant d'onglets et de paramètres supplémentaires que nécessaire dans un template.
Une utilisation potentielle de paramètres supplémentaires concerne les substitutions ou les mises en page, pour les templates parents comme pour les templates enfants.
Résumé
Voici le fichier templateDetails.xml utilisé par Cassiopeia :
<?xml version="1.0" encoding="utf-8"?>
<extension type="template" client="site">
<name>cassiopeia</name>
<version>1.0</version>
<creationDate>2017-02</creationDate>
<author>Joomla! Project
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser. (C) 2017 Open Source Matters, Inc.
TPL_CASSIOPEIA_XML_DESCRIPTION
1
component.php
error.php
index.php
joomla.asset.json
offline.php
templateDetails.xml
html
js
css
scss
images
topbar
below-top
menu
search
banner
top-a
top-b
main-top
main-bottom
breadcrumbs
sidebar-left
sidebar-right
bottom-a
bottom-b
footer
debug
en-GB/tpl_cassiopeia.ini
en-GB/tpl_cassiopeia.sys.ini