Comprendre les templates Joomla!
From Joomla! Documentation
Structure traditionnelle d'un répertoire de template
Les templates pour le CMS Joomla! utilisent habituellement une structure traditionnelle de répertoires et de fichiers, mais cette structure peut varier d'un template à l'autre.
- Les templates de Site (ou de "frontend", sont les templates qui permettent de modifier l'affichage de votre site web) se trouvent dans le répertoire
/templates. Par exemple, si votre template se nomme "montemplate", il sera alors placé dans le dossier :
<chemin-vers-Joomla!>/templates/montemplate
- Les templates d' Administration (ou de "backend", sont les templates qui permettent de modifier l'affichage de l'administration du site) se trouvent dans le répertoire
/administrator/templates. Par exemple, si votre template d'administration se nomme "montemplateadministration", il sera alors placé dans le dossier :
<chemin-vers-Joomla!>/administrator/templates/montemplateadmin
Répertoires de template
Un template typique pour Joomla! comprendra les répertoires suivants :
- css - contient tous les fichiers .css
- html - contient les fichiers de substitution de template (override) pour les rendus du template et du module chrome
- images - contient toutes les images utilisées par le template
- language - contient les fichiers langues supplémentaires utilisés par le template
En fonction de la complexité et de la conception du template, il peut également contenir le dossier :
- javascript - contient le JavaScript utilisé par le template afin d'ajouter certaines fonctionnalités
Exemple de structure de fichiers
Le chemin normal d'un template est <root>/public_html/nom-de-domaine/template/<nom de votre template> qui va contenir, en fonction des spécificités de votre template, les répertoires et les fichiers suivants :
/css /html /images /javascript /language component.php error.php favicon.ico index.php templateDetails.xml template_preview.png template_thumbnail.png
Les fichiers de template
Un template comprend généralement au minimum les fichiers suivants :
- index.php
- Fournit la logique pour l'affichage et le positionnement des modules et composants.
- component.php
- Fournit la logique pour l'affichage de "imprimer la page", "Envoyer à un ami." etc.
- error.php
- Fournit une méthode pour gérer le erreurs, comme les erreurs 404, page non trouvée.
- favicon.ico
- fichier du favicon
- template.css
- Gère les aspects de présentation du template, y compris les spécifications de marges, polices, entêtes, bordures des images, mise en forme des listes, etc. Les fichiers .css peuvent également être situés dans le répertoire
/css.
- templateDetails.xml
- Contient les méta-informations liées au template et est utilisé par l'Installateur et le Gestionnaire de Template.
- template_preview.ext - remplacer .ext avec le format d'extension de l'image (.jpg, .png, .gif)
- Généralement, une image de 600px x 400px qui s'affiche lorsque l'on clique sur la miniature située dans Gestion des templates : Templates et non pas dans Gestion des templates : Styles. Cela ouvre une fenêtre en pop-up permettant à l'Administrateur de visualiser le template avant de l'appliquer au site.
- template_thumbnail.ext - remplacer .ext avec le format d'extension de l'image (.jpg, .png, .gif)
- Généralement, une miniature de 200px x 150px qui s'affiche sur la liste de Template dans Gestion des templates :Templates, et non pas dans Gestion des templates : Styles . Cela permet à l'Administrateur de visualiser une vue miniature du template avant de l'appliquer au site.
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
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
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
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
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
- Plus d'informations sur la création des templates Joomla!
- Créer un fichier de définition de langues
- Charger des fichiers de langues supplémentaires
- Définir un paramètre dans le fichier templateDetails.xml
Le fichier index.php est le squelette du site. Chaque page que Joomla! affiche est l' "index.php" étoffé d'une sélection de contenu inséré dans la base de données.
Le fichier index.php d'un template contient un mélange de code qui s'affichera tel quel, et du code php, qui sera modifié avant d'être affiché. Le code est familier à toute personne ayant déjà créé une simple page web en HTML : il y a deux sections principales - <head> et <body>. L'index.php est différent dans le sens où il utilise du code php pour insérer les informations sélectionnées à partir d'une base de données.
Voici un exemple :
Une section entête (head) HTML traditionnelle :
<head> <title>My Example Webpage</title> <meta name="title" content="example" /> <link rel="stylesheet" href="www.example.com/css/css.css" type="text/css" /> </head>
Et la même chose façon Joomla :
<head> <jdoc:include type="head" /> <link rel="stylesheet" href="<?php echo $this->baseurl ?>templates/mytemplate/css/css.css" type="text/css" /> </head>
Ainsi, au lieu de définir ces parties d'en-tête dans le fichier index.php, les parties d'en-tête sont recherchées dans la base de données grâce à du code PHP. Et ces deux scripts vont délivrer le même code à un utilisateur. Si vous regardez le code d'un site web Joomla, tout le <?php bla /> aura été remplacé par un code html traditionnel.
La bonne conception d'un template
index.php doit, autant que faire se peut, aller à l'essentiel, car il sera renvoyé à chaque fois qu'une nouvelle page est chargée. Les éléments tels que les styles doivent être inclus dans les fichiers CSS, qui sont enregistrés dans le cache des utilisateurs. Les présents tutoriels vont passer en revue les aspects techniques de la création de votre index.php.
Pourquoi index.php ?
Index.htm a toujours été le nom donné historiquement à la page d'accueil d'un site web. Ainsi, lorsqu'un utilisateur accède à www.exemple.org, le serveur web délivre www.exemple.org/index.htm. Joomla! étant écrit en PHP, index.php est le fichier automatiquement délivré. Pour compliquer un peu plus les choses, lorsqu'un utilisateur navigue sur le site Joomla, l'index.php du répertoire racine redirige vers l'index.php du template utilisé par défaut.