Quel est le but du fichier templateDetails.xml ?

From Joomla! Documentation

This page is a translated version of the page What is the purpose of the templateDetails.xml file? and the translation is 100% complete.
Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎português do Brasil • ‎русский

Le fichier templateDetails.xml est exigé pour tous les templates pour Joomla! et il peut être trouvé à la racine du répertoire de chaque template du répertoire templates de Joomla. Ce fichier XML regroupe les méta-données dont Joomla! a besoin afin de les afficher en tant qu'options de template dans l'interface d'administration. Il contient également un ensemble d'autres méta-données qui sont utilisées pour fournir des informations sur le template, ses auteurs et pour définir les fichiers et dossiers qui seront utilisés par le template. Il permet enfin de définir les fichiers de langue ainsi que les paramètres et les réglages qu'offre le template dans l'interface d'administration.

Le fichier templateDetails.xml utilise une structure et un format XML de base. Dans ce fichier, les données XML sont divisées en sections avec une mise en forme spécifique afin de restituer les différents éléments et paramètres. Les données XML sont lues et interprétées par de puissants outils du noyau Joomla, puis restituées au template pour la création de l'affichage dans le gestionnaire de templates. Ceci offre aux développeurs de templates une méthode relativement simple pour créer des assignations, des réglages et des paramètres pour l'utilisation du template.

La mise en œuvre du fichier templateDetails.xml peut varier d'un template à l'autre et peut être plus ou moins complexe au regard des fonctionnalités proposées par le template. Le template par défaut Protostar pour Joomla! 3 représente un excellent exemple pour expliquer comment ce fichier est utilisé. Les différentes sections de ce fichier sont expliquées ci-dessous.

Format XML

Les deux premières lignes de chaque fichier templateDetails.xml doivent permettre de définir le format XML et le doctype.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">

La ligne suivante est également nécessaire car elle explique à Joomla! que les données du fichier seront utilisées dans le cadre d'une extension, ici un template. Toutes les données du template sont insérées entre la balise ouvrante : <extension> et la balise fermante </extension>.

<extension version="3.1" type="template" client="site">

Informations de base

La première section est généralement l'emplacement où les développeurs de templates intègrent des informations propres au template. Ce sont des informations telles que les noms, dates, informations de contact, droits d'auteur, numéro de version ainsi qu'une description sommaire. Ces données sont utilisées dans le gestionnaire de templates et s'affichent dans la liste des templates disponibles ainsi que sur les écrans d'édition des templates.

Informations de base dans la gestion des templates > Templates

Exemple d'informations sur les templates

Code XML pour les informations de base pour le template Protostar :

<extension version="3.1" type="template" client="site">
	<name>protostar</name>
	<version>1.0</version>
	<creationDate>4/30/2012</creationDate>
	<author>Kyle Ledbetter</author>
	<authorEmail>admin@joomla.org</authorEmail>
	<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>
	<description>TPL_PROTOSTAR_XML_DESCRIPTION</description>

Vous pouvez remarquer que la dernière ligne de ce code, la description, contient une chaîne de langue et non pas la description réelle. Cette chaîne fait référence à un fichier de langue du template dans lequel la description réelle est définie et écrite. C'est une méthode par défaut dans Joomla! pour les extensions qui sont distribuées pour l'utilisation et le support de langues. La description pourrait tout simplement être rédigée en dur si sa traduction n'est pas une préoccupation. Les fichiers de langue sont également définis dans le fichier templateDetails.xml, dans la section langue qui est couverte plus en détail plus loin dans cet article.

Description du template lors de l'édition du template Protostar

Exemple de détails sur les templates

Structure des dossiers

Tous les dossiers liés à l'installation du template sont répertoriés ici. Tous les fichiers et tous les dossiers situés à la racine du répertoire du template lors de l'installation doivent être listés ici. Tous les fichiers contenus dans un dossier listé seront automatiquement inclus. Chaque dossier contient toutes les informations pour le chemin d'accès depuis la racine du template. Le programme d'installation de l'administration utilise ces informations pour stocker les fichiers lors de l'installation.

Ci-dessous vous trouverez la structure des dossiers et fichiers pour le template par défaut Protostar. Cette structure de fichiers est un standard pour tout type de template de base pour Joomla.

	<files>
		<filename>component.php</filename>
		<filename>error.php</filename>
		<filename>favicon.ico</filename>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<filename>template_preview.png</filename>
		<filename>template_thumbnail.png</filename>
		<folder>css</folder>
		<folder>html</folder>
		<folder>images</folder>
		<folder>img</folder>
		<folder>js</folder>
		<folder>language</folder>
		<folder>less</folder>
	</files>

Vue du répertoire de fichiers pour Protostar

J3 protostar file structure fr.jpg

Positions de modules

Les positions de modules disponibles pour l'utilisation dans le template sont définies dans cette section.

Voici les positions de modules définies pour le template par défaut Protostar :

	<positions>
		<position>banner</position>
		<position>debug</position>
		<position>position-0</position>
		<position>position-1</position>
		<position>position-2</position>
		<position>position-3</position>
		<position>position-4</position>
		<position>position-5</position>
		<position>position-6</position>
		<position>position-7</position>
		<position>position-8</position>
		<position>position-9</position>
		<position>position-10</position>
		<position>position-11</position>
		<position>position-12</position>
		<position>position-13</position>
		<position>position-14</position>
		<position>footer</position>
	</positions>

La liste des positions est renseignée entre les balises <positions>. Chaque balise <position> permet de créer une position de module qui sera disponible à partir de la liste des positions dans le gestionnaire de modules et dans d'autres éléments de Joomla! où des positions de modules peuvent être sélectionnées.

La simplicité du format utilisé pour la listes des positions permet de les personnaliser très facilement. Par exemple, pour ajouter à la liste une nouvelle position de module, il suffit d'ajouter une nouvelle balise <position> à l'intérieur de la balise <positions> avec un nom unique composé de lettres minuscules et sans espace. Gardez à l'esprit que ceci ajoutera la nouvelle position uniquement dans l'interface d'administration et qu'un développement supplémentaire dans d'autres fichiers du template sera nécessaire pour rendre la nouvelle position visible en frontend.

Les langues

Certains templates intègrent des fichiers de langue pour permettre la traduction de textes statiques présents dans le template. Veuillez noter que le dossier de langue est défini et que les deux fichiers langue à l'intérieur sont également inclus. Même si le dossier de langue a été défini précédemment, ces fichiers ont besoin de leurs propres définitions. Cette méthode permet d'indiquer à Joomla! où se situent les fichiers qui listent les chaînes de caractères utilisées par le template.

Le premier fichier contient le fichier de langue pour les textes qui seront affichés pour l'utilisateur en frontend. Le second fichier, avec l'extension .sys, pour système, contient le texte qui sera affiché dans l'interface d'administration.

Voici la structure du dossier langue et des fichiers pour le template par défaut Protostar :

	<languages folder="language">
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.ini</language>
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.sys.ini</language>
	</languages>

Les chaînes de langue sont utilisées dans les templates et à tous les niveaux de Joomla! pour encourager l'utilisation des fonctionnalités favorisant l’internationalisation offerte par Joomla. Cette méthode fournit, aux développeurs et aux utilisateurs, une méthode relativement simple pour permettre la traduction de tout texte utilisé dans les templates ou les extensions. Joomla! va vérifier les fichiers de langue pour toutes les chaînes de caractères qui sont utilisées. Il chargera alors, en lieu et place de la chaîne, le texte correspondant dans la langue choisie par l'utilisateur. Dans cet exemple, il existe uniquement les fichiers pour l'anglais (en-GB). Les textes des traductions en d'autres langues doivent être fournis par les utilisateurs ou les développeurs avant de pouvoir être utilisés par Joomla.

Plus d'informations sur les fichiers de langue :

Paramètres

Écran des paramètres avancés pour Protostar.

Un template peut proposer différentes options d'affichage ou autres paramètres qui pourront être définis par l'administrateur dans la gestion des templates. Par exemple et concernant le template par défaut Protostar, l'administrateur peut modifier les différentes couleurs, les polices et ajouter un logo. Ces paramètres se situent dans l'onglet paramètres avancés, qui est également créé et défini dans les paramètres XML.

Les paramètres de templates sont définis entre les balises <config> contenant les balises <fields> de la balise avec un nom d'attribut : "params". C'est à l'intérieur des balises <fields> que les différents groupes de paramètres et les paramètres individuels sont définis. La balise <fieldset> est utilisée pour créer des groupes de paramètres. Les paramètres individuels sont définis avec la balise <field>.

Chaque <fieldset> et chaque paramètre <field> avec un <fieldset>, exigent un nom unique défini comme nom d'attribut. Ce nom définit le paramètre lui-même et est utilisé pour transmettre des réglages aux fichiers du frontend. Chaque paramètre doit également contenir un attribut d'étiquette et un attribut description. Le texte de l'étiquette s'affiche avec le paramètre dans l'écran des paramètres pour indiquer à quoi ce réglage est destiné alors que la description fournira des informations complémentaires plus détaillées.

Un champ de paramètre peut être pratiquement n'importe quel type de formulaire de saisie avec ses options correspondantes. Celles-ci sont définies par l'attribut type. Toutes les options nécessaires, telles que les boutons radio ou l'option de choix de sélection, sont définies entre les balises <option>. Le nom de classe CSS peut être défini par l'attribut class. Un paramétrage par défaut peut également être défini à l'aide de l'attribut default.

Ci-dessous vous trouverez les définitions des paramètres par défaut pour le template Protostar. Dans cet exemple, toutes les étiquettes, descriptions et options utilisent des chaînes de langue définies dans des fichiers tels que décrit dans la section précédente. D'autres sont communes au noyau Joomla, de sorte qu'elles peuvent être traduites dans d'autres langues si nécessaire.

	<config>
		<fields name="params">
			<fieldset name="advanced">
				<field name="templateColor" class="" type="color" default="#08C"
					label="TPL_PROTOSTAR_COLOR_LABEL"
					description="TPL_PROTOSTAR_COLOR_DESC" />

				<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"
					label="TPL_PROTOSTAR_BACKGROUND_COLOR_LABEL"
					description="TPL_PROTOSTAR_BACKGROUND_COLOR_DESC" />

				<field name="logoFile" class="" type="media" default=""
					label="TPL_PROTOSTAR_LOGO_LABEL"
					description="TPL_PROTOSTAR_LOGO_DESC" />
					
				<field name="sitetitle"  type="text" default=""
					label="JGLOBAL_TITLE"
					description="JFIELD_ALT_PAGE_TITLE_LABEL"
					filter="string" />

				<field name="sitedescription"  type="text" default=""
					label="JGLOBAL_DESCRIPTION"
					description="JGLOBAL_SUBHEADING_DESC"
					filter="string" />

				<field name="googleFont"
					type="radio"
					class="btn-group btn-group-yesno"
					default="1"
					label="TPL_PROTOSTAR_FONT_LABEL"
					description="TPL_PROTOSTAR_FONT_DESC"
				>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

				<field name="googleFontName" class="" type="text" default="Open+Sans"
					label="TPL_PROTOSTAR_FONT_NAME_LABEL"
					description="TPL_PROTOSTAR_FONT_NAME_DESC" />

				<field name="fluidContainer"
					type="radio"
					class="btn-group btn-group-yesno"
					default="0"
					label="TPL_PROTOSTAR_FLUID_LABEL"
					description="TPL_PROTOSTAR_FLUID_DESC"
				>
					<option value="1">TPL_PROTOSTAR_FLUID</option>
					<option value="0">TPL_PROTOSTAR_STATIC</option>
				</field>
			</fieldset>
		</fields>
	</config>

Le template Protostar illustre bien les différentes façons dont un XML peut être utilisé dans le cadre d'une interface de template, mais il existe encore un grand nombre de possibilités. Dans cet exemple, la balise <fieldset name="advanced"> englobe l'ensemble des paramètres et utilise l'attribut name pour la création de l'onglet "Paramètres avancés" dans l'interface d'administration. Tout ce qu'il faut pour créer un autre onglet dans l'interface est une autre balise <fieldset> avec un attribut name différent. En gardant cela à l'esprit, il vous sera relativement simple de créer autant d'onglets supplémentaires et les paramètres nécessaires à votre template.

Ressources complémentaires