Créer un template pour Joomla 1.5

Créer un template pour Joomla 1.5

Le 12/09/2007

Une Template (un gabarit en Français) est un ensemble de fichiers qui va indiquer à Joomla de quelle manière afficher chaque élément du site. Le principe est de séparer le contenu du contenant, ou le fond de la forme, afin de pouvoir changer l'un ou l'autre, indépendamment. Ce dossier explique comment créer une Template pour Joomla 1.5.x à partir de rien.

Nouveautés dans Joomla 1.5

Les Templates ont été améliorées dans Joomla 1.5. Voici donc un court résumé des nouvelles fonctionnalités mises à disposition du développeur de templates.

La fonction mosCountModules() a été remplacée par une propriété de l'objet document. Elle est désormais appelée par la syntaxe $this→countModules() et accepte des arguments plus élaborés. On peut maintenant compter les modules de plusieurs emplacement en un seul appel de la méthode avec la syntaxe $this→countModules(“user1 + user2”), ce qui simplifie la gestion de la mise en page.

Les appels de code passant par le noyau (les modules, par exemple), se font via une balise XML de type <jdoc:include type=“modules” name=“left” />, ce qui restreint le code PHP d'une template.

L'initialisation de l'éditeur WISIWYG est automatique. Plus besoin de l'intégrer à votre template. Un système de détection interne lance son initialisation lorsque c'est nécessaire.

La gestion de l'icône de favoris est automatique. Il suffit d'avoir un fichier favicon.ico dans le dossier de la template pour qu'elle soit intégrée aux pages.

La gestion des paramètres de Template permet au Webmaster de changer l'apparence d'une Template depuis l'admin, via un formulaire comme on en trouve dans les modules. Naturellement c'est au développeur de la Template de faire en sorte qu'elle gère correctement ces paramètres.

La structure d'une Template

Comme toute extension Joomla, une Template est fournie sous la forme d'une archive ZIP contenant au moins un fichier de description XML, la Template elle-même au format PHP, et ses paramètres par défaut. Elle contiendra aussi au besoin les fichiers qui la constituent (Descripteurs de classes CSS, scripts client, objets graphiques, etc).

La première étape consiste à créer localement sur votre machine un dossier qui contiendra les fichiers en phase de développement et sera archivé en phase finale en vue d'être installé sur votre Joomla.

Le descripteur XML

Le descripteur XML d'une Template est un ficher nommé « templateDetails.xml ». Vous trouverez un exemple en bas de page. Les explications vous paraîtront plus claires si vous l'imprimez et le consultez au fur et à mesure. Pour le créer, vous aurez besoin d'un simple éditeur texte, tel que notepad sous Windows ou kate sous KDE. Voici ce qu'il doit contenir (les mentions en noir sont ce que vous devrez personnaliser) :

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="template">
  <name>Nom de la template</name>
  <version>Numéro de version de la template</version>
  <creationDate>Date de création</creationDate>
  <author>Nom du créateur</author>
  <authorEmail>Adresse email du créateur</authorEmail>
  <authorUrl>Site Web du créateur</authorUrl>
  <copyright>Copyright de la template</copyright>
  <licence>Type de licence de la template</licence>
  <description>Description</description>

Ces quelques lignes forment l'entête du descripteur XML de Template. Le nom de la Template doit être formaté de manière à servir de nom de dossier à la Template sur le serveur. Ce qui signifie tout en minuscules, sans accents et sans espaces (à remplacer par des underscores « _ »).

Après l'entête, on trouve la section files, qui informe Joomla sur tous les fichiers qui composent la Template :

  <files>
    <filename>index.php</filename>
    <filename>templateDetails.xml</filename>
    <filename>template_thumbnail.png</filename>
    <filename>params.ini</filename>
    <filename>dossier/fichier.extension</filename>
    ...
  </files>

Le fichier index.php est la Template elle même. Le fichier templateDetails.xml est le fichier que nous sommes en train de décrire. template_thumbnail.png est un apperçu de la Template en utilisation et permet de différencier rapidement les Templates dans la liste côté administration. Le fichier params.ini permet de définir les valeurs par défaut des paramètres de la Template (la gestion des paramètres n'existait pas dans les Templates avant la version 1.5.x de Joomla et sont décrits deux sections plus bas).

C'est dans cette section que vous ajouterez les fichiers propres à votre Template (Descripteurs de classes CSS, scripts client, objets graphiques, etc). On ajoute généralement un fichier index.html vierge, servant à protéger le dossier de la Template des accès directs qui permettrai sinon d'en afficher le contenu.

Vient ensuite la section positions, qui définit quels emplacements de modules sont pris en charge par votre Template. Nous reparlerons des emplacements de modules lorsque nous étudieront la Template elle même (fichier index.php) :

  <positions>
    <position>Nom de l'emplacement</position>
    ...
  </positions>

La dernière section est la section params, qui définit les paramètres de la Template. Les paramètres ont étés ajouté depuis la version 1.5.x et permettent par exemple de décliner une Template en différents coloris, alignements, etc :

  <params>
    <param name="Parametre" type="Type" default="Valeur" label="Champ" description="Aide" />
    ...
  </params>

Voici les attributs communs à tous les types de paramètres :

default : indique la valeur par défaut de ce paramètre à l'installation de la Template, ou l'option sélectionnée s'il s'agit d'un champ de type list ou radio (voir plus bas).

description : permet de définir une bulle d'aide qui décrive exhaustivement l'usage du paramètre pour l'utilisateur.

label : définit le nom qui sera affiché pour ce champ dans l'interface d'administration, et peut contenir des espaces et caractères spéciaux.

name : doit contenir le nom du paramètre tel que vous l'appellerez depuis votre Template (sans espace ni caractères spéciaux).

type : informe Joomla sur la façon dont l'utilisateur renseignera ce champ (voir ci-dessous).

Les type de paramètre est le même pour les Templates et les Modules, à savoir :

category : liste déroulante dynamique qui contient les catégories du site et retourne leur identifiant. Nécessite un attribut additionnel section=“nomDeLaSection” qui indique dans quelle section on liste les catégories.

imagelist : liste des images situées dans le dossier spécifié dans l'attribut directory=“chemin/relatif”. Nécessite donc un nouvel attribut directory.

list : liste déroulante. Nécessite un jeu de balises <option> décrites plus bas.

menuitem : liste déroulante dynamique qui contient l'arborescence des menus du site et retourne leurs identifiants.

mos_menu : liste déroulante dynamique qui contient les différents modules de menu du site.

radio : boutons radio. Nécessite un jeu de balises <option> décrites plus bas.

spacer : ligne de séparation entre deux groupes de paramètres.

text : champ texte libre.

textarea : champ de texte multi-lignes. Nécessite les attributs cols et rows qui, comme dans une balise HTML <textarea> indiquent le nombre de lignes et de colonnes de ce champ.

Les types list et radio nécessitent une seconde balise, qui fonctionne comme la balise HTML <option> :

  <param name="Parametre" type="Type" default="Valeur" label="Champ" description="Aide">
    <option value="valeur 1">Nom de l'option 1</option>
    <option value="valeur 2">Nom de l'option 2</option>
    ...
  </param>

Dans ce cas la valeur de l'attribut default correspond à la valeur de l'option qui doit être sélectionnée (si type=“list”) ou cochée (si type=“radio”) par défaut. Notez que le slash de fermeture « / » a disparu en fin de balise <param> au profit d'une balise de clôture </param>, comme l'exige XML.

N'oublions pas de clôturer le descripteur XML de la Template :

</install>

Voir comme exemple le fichier templateDetails.xml de la Template rhuk_milkyway, fournie dans l'installation d'origine de Joomla 1.5.

La template de site

La Template est un ficher nommé « index.php ». Vous trouverez un exemple en bas de page. Les explications vous paraîtront plus claires si vous l'imprimez et le consultez au fur et à mesure. Pour le créer, vous aurez besoin d'un simple éditeur texte, tel que notepad sous Windows ou kate sous KDE.

En consultant l'exemple vous constaterez qu'il s'agit d'un fichier HTML dans lequel on trouve quelques balises PHP et des balises propriétaires de forme <jdoc:include> qui sont des balises internes à Joomla.

Ce dossier n'a pas pour but de vous apprendre le HTML. D'autant que vous pouvez pour cela utiliser un logiciel de création de pages Web tel que Frontpage ou DreamWeaver. Nous allons donc nous pencher plus serieusement sur les parties PHP et les fameuses balises <jdoc:include>.

La première chose à être traitée est le code PHP de votre template. Ensuite les balises <jdoc:include> sont évaluées, ce qui vous permet d'intégrer ces balises dans des conditions PHP.

Joomla stocke les différents éléments du document dans l'objet global $this, dont voici les propriétés et méthodes utiles au niveau de la Template:

$this→template : contient le nom de la template en cours.
$this→getType() : retourne le type du document (error, feed, html, pdf, raw).
$this→getHeadData() : retourne un tableau contenant les entêtes HTML.
$this→getMetaData(name, http_equiv = false) : retourne la valeur d'une balise meta.
$this→getCharset() : retourne le jeu de caractères du document.
$this→getLanguage() : retourne le language du document.
$this→getDirection() : retourne le sens de lecture du document.
$this→getTitle() : retourne le titre du document.
$this→getBase() : retourne l'adresse de base du document.
$this→getDescription() : retourne la description du document.
$this→getLink() : retourne l'adresse complète du document.
$this→getGenerator() : retourne la chaine d'identification du générateur du document.
$this→getModifiedDate() : retourne la date de dernière modification du document
$this→countModules() : retourne le nombre de modules affectés à un ou plusieurs emplacements donnés.
$this→params→get(“parametre”) : retourne la valeur du parametre donné.

Notons que la méthode countModules() accepte un ou plusieurs noms d'emplacements, ainsi qu'un nombre impressionnant d'opérateurs. On peut compter les modules d'un emplacement par la syntaxe $this→countModules(“user1”), de plusieurs emplacements avec $this→countModules(“user1 + user2”), mais aussi comparer les nombre de modules entre deux emplacement en utilisant par exemple $this→countModules(“user1 >= user2”). Les opérateurs pris en comptes sont listés sur cette page (en anglais).

Les balises <jdoc>

Une nouvelle balise a été ajoutée aux templates à partir de la version 1.5 de Joomla. Son utilité est d'appeler les sorties du noyau (entêtes, messages, modules, composants) à l'emplacement désiré de votre template. Elle remplace les fonctions mosShowHead(), mosLoadModules() et mosMainBody() des versions précédentes de Joomla, et sa syntaxe est la suivante :

<jdoc:include type="Type" name="Nom" style="Style" id="Identifiant" />

L'attribut type définit quel contenu est appelé et est commun à toutes les syntaxes de la balise <jdoc>. Sa valeur peut être l'une des suivantes :

component : Apparaît une seule fois, dans la section <body> de votre Template. Définit l'emplacement du composant actif (par exemple un article). L'appel de composant ne gère que l'attribut type.

head : Apparaît une seule fois, dans la section <head> de votre Template. Définit l'emplacement des entêtes (inclusions de feuilles de style, de scripts, balises meta, etc). L'appel des entêtes ne gère que l'attribut type.

message : Apparaît une seule fois, dans la section <body> de votre Template. Définit l'emplacement des messages systèmes et d'erreur éventuellement retournés par Joomla. L'appel des messages ne gère que l'attribut type.

module : Apparaît autant de fois que nécessaire, dans la section <body> de votre Template. Appelle la sortie d'un module dont le nom d'emplacement est fourni via l'attribut name. Permet l'utilisation des attributs style et id afin de personnaliser l'aspect du module.

modules : Apparaît autant de fois que nécessaire, dans la section <body> de votre Template. Appelle la sortie de tous les modules dont le nom d'emplacement est fourni via l'attribut name. Permet l'utilisation des attributs style et id afin de personnaliser l'aspect des modules.

L'attribut style, des types module et modules permet d'utiliser une Template de module, qui sont décrites en page suivante.

Enfin, l'attribut id permet d'affecter une classe CSS particulière au module unique appelé via le type module.

On peut afficher les emplacements de modules d'une template en ajoutant le paramètre tp=1 à l'adresse de la page.

Voir comme exemple le fichier index.php de la Template rhuk_milkyway, fournie dans l'installation d'origine de Joomla 1.5.

La template de module

Les Templates de modules sont optionnelles et définissent les différents styles d'affichages de modules. Celles par défaut (none, table, horz, xhtml, rounded et outline) sont définies dans le fichier /templates/system/html/modules.php, Mais vous pouvez définir vos propres Templates de modules en créant dans votre Template un fichier /html/modules.php sur le même modèles que celui d'origine (N'oubliez pas de l'ajouter alors au descripteur XML).

Considérons un exemple de Template de module nommé monmodule :

<?php
// Protection contre les appels directs.
defined("_JEXEC") or die("Restricted access");
 
function modChrome_monmodule($module, &$params, &$attribs) {
 
  // Référence au document, par exemple pour intégrer une feuille de style ou un script
  $document =& JFactory::getDocument();
  $document->addScript("monmodule.js");
  $document->addStyleSheet("monmodule.css");
 
  echo("<table cellpadding='0' cellspacing='0' class='".$params->get("Paramètre")."'>\n");
  if($module->showtitle != 0) {
    echo("  <tr><th valign='top'>".$module->title."</th></tr>\n");
  }
  echo("  <tr><td>".$module->content."</td></tr>\n");
  echo("</table>\n");
}
?>

On voit ici comment accéder aux caractéristiques, aux paramètres et aux attributs d'un module. On peut aussi créer une référence au document (pour récupérer ou modifier le titre, les entêtes, etc) via la méthode getDocument() de l'objet JFactory.

Pour appeler un module depuis la Template de site en utilisant ce style on utilisera :

<jdoc:include type="module" name="user1" style="monmodule" />

Voir aussi

Créer un module pour Joomla 1.5.x
Templates in Joomla! 1.5 (en anglais)
Operators for use with the countModules function (en anglais)
jdoc Statements (en anglais).