Créer un module pour Joomla 1.5

Le 12/09/2007

Un module (aussi appelé box, boîte, encart, cadre, etc) est une petite portion du site contenant des informations qui sortent du cadre de la partie principale de la page (généralement occupée par un composant). Un module peut être affiché sur plusieurs pages et suivre le visiteur tout au long de sa navigation sur le site. Les menus, les bannières, les mentions légales, par exemple sont des modules.

Nous allons utiliser comme exemple mon module Google Analytics, que vous pouvez télécharger sur cette page. Ce module permet d'ajouter à votre site Joomla le tracker de statistiques Google Analytics. Deux paramètres permettent d'indiquer au module votre identifiant Google Analytics et de restreindre l'appel de ce module à certain types d'utilisateurs seulement, afin par exemple que les administrateurs ne faussent pas les statistiques. Contrairement au paramètre “Niveau d'accès” de Joomla, il ne gère pas la hiérarchie des groupes, qui ne permettait pas d'origine d'isoler les Administrateurs.

Un module basique est composé par convention de 4 fichiers :

• mod_ganalytics.php : c'est le point d'entrée du module. Il initialise les variables nécessaires, appelle la partie fonctionnelle (helper.php) et applique la template (tmpl/default.php) avant de renvoyer le tout à Joomla.

• mod_ganalytics.xml : ce fichier contient la description du module et ses procédures d'installation et de paramétrage.

• helper.php : ce fichier contient la partie fonctionnelle du module, telle que l'interaction avec la source de données, le traitement des informations, etc.

• tmpl/default.php : contient la partie esthétique du module, permet de mettre en forme le résultat de la partie fonctionnelle sous forme de code HTML.

Lorsque vous créerez votre propre module, vous devrez renommer mod_ganalytics.php et mod_ganalytics.xml en focntion du nom de votre module.

L'initialisation du module est confiée au fichier mod_ganalytics.php. Ce fichier devra effectuer au minimum les trois tâches suivantes :

• Inclure la classe qui définit la partie fonctionnelle (helper.php)
• Traiter les informations en utilisant les propriétés de cette classe.
• Inclure la partie esthétique du module (tmpl/default.php)

Voici le contenu de notre fichier mod_ganalytics.php :

mod_ganalytics.php

<?php
 
// Protection contre les appels directs
if(!defined("_JEXEC")) die("L'appel direct de ce script est interdit.");
 
// Inclusion de la partie fonctionnelle
require_once(dirname(__FILE__).DS."helper.php");
 
// Appel de la fonction writeScript()
$urchin = modGAnalytics::writeScript($params);
 
// Appel du script Google Analytics
require(JModuleHelper::getLayoutPath("mod_ganalytics"));
 
?>

Dans cet exemple simple le module ne fait qu'appeler les éléments l'un après l'autre, mais c'est dans ce fichier que vous pourrez initialiser vos objets et aiguiller vers l'action à effectuer en fonction du contexte.

Voici le contenu de notre fichier helper.php :

helper.php

<?php
 
class modGAnalytics {
  /**
   * Retourne le code JavaScript nécessaire à Google Analytics
   *
   * @param objet $params Un objet contenant les paramètres du module
   * @access public
  */
  function writeScript($params) {
    global $mainframe;
 
    $showit = false;
 
    if($params->get("restriction") == "all") {
 
      // Pas de restrictions, affichage du code.
      $showit = true;
 
    } else {
 
      // Récupération de l'objet utilisateur.
      $utilisateur = $mainframe->getUser();
 
      // Les conditions ont été décomposées pour plus de lisibilité.
      if($params->get("restriction") == "gst" && $utilisateur->gid == "29") {
        $showit = true;
      } else if($params->get("restriction") == "mbr" && $utilisateur->gid == "18") {
        $showit = true;
      } else if($params->get("restriction") == "adm" && $utilisateur->gid == "25") {
        $showit = true;
      }
    }
 
    if($showit) {
      // Génération du code Google Analytics.
      $resultat = "<script src='http://www.google-analytics.com/urchin.js' type='text/javascript'></script>\n";
      $resultat .= "<script type='text/javascript'>\n";
      $resultat .= "_uacct='".$params->get("identifiant")."';\n";
      $resultat .= "urchinTracker();\n";
      $resultat .= "</script>\n";
    } else {
      $resultat = "";
    }
 
    return $resultat;
  }
}
 
?>

La classe fonctionnelle contient les différentes actions à effectuer, qui seront appelées par le module en fonction du contexte. La portée des objets est locale afin d'assurer une plus grande liberté et une meilleure sécurité. C'est pourquoi nous devons récupérer au besoin les objets globaux comme je l'ai fait avec l'objet $mainframe, dont j'avais besoin. Remarquez au passage l'utilisation de l'objet $params, qui permet de récupérer des paramètres que l'administrateur aura renseigné dans l'interface d'administration.

Voici le contenu de notre fichier tmpl/default.php :

default.php

<?
 
// Protection contre les appels directs
if(!defined("_JEXEC")) die("L'appel direct de ce script est interdit.");
 
echo($urchin);
 
?>

Ce fichier se contente d'afficher sous forme de code HTML simple le résultat des étapes antérieures. Ne perdez pas de vue le système de Templates de modules qui s'appliquera au moment du rendu de la page. La portée des variables est ici la même que dans le module et on peut donc utiliser directement les objets déclarés dans ce dernier, dans notre cas la chaîne $urchin.

Le descripteur XML est utilisé par Joomla pour installer et paramétrer votre module. On lui indique par ce biais les informations sur le module (Nom, auteur, description, etc), les fichiers qui le composent, et les paramètres qu'il prend en compte.

Voici le contenu de notre fichier mod_ganalytics.xml :

mod_ganalytics.xml

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
  <name>Google Analytics</name>
  <author><![CDATA[David M&eacute;zi&egrave;re]]></author>
  <creationDate>19/09/2007</creationDate>
  <copyright>Copyright 2007 David Meziere. All rights reserved.</copyright>
  <license>GNU GPL (http://www.gnu.org/licenses/gpl.html)</license>
  <authorEmail>dmeziere at free.fr</authorEmail>
  <authorUrl>http://dmeziere.free.fr</authorUrl>
  <version>1.1</version>
  <description>Ce module permet d'utiliser votre compte Google Analytics sous Joomla 1.5.x.</description>

Ces quelques lignes forment l'entête du descripteur XML. Remarquez l'utilisation de la balise <![CDATA]>, qui permet d'intégrer des caractères spéciaux HTML dans le nom d'auteur, ou la description par exemple. On trouve ensuite la section files, qui informe Joomla sur tous les fichiers qui composent le module :

  <files>
    <filename module="mod_ganalytics">mod_ganalytics.php</filename>
    <filename>index.html</filename>
    <filename>helper.php</filename>
    <filename>tmpl/default.php</filename>
    <filename>tmpl/index.html</filename>
  </files>

Le fichier mod_ganalytics.php est le module lui même. L'attribut module qu'il comporte déterminera le nom du dossier dans lequel il sera stocké. C'est dans cette section que vous ajouterez les fichiers propres à votre module (Descripteurs de classes CSS, scripts client, objets graphiques, etc). Vous remarquerez la présence d'un fichier index.html dans chaque dossier, pour en empêcher le listage. Ces fichier peuvent êtres laissés vierges ou bien contenir cette simple ligne :

<html><body bgcolor="#FFFFFF"></body></html>

La dernière section est la section params, qui définit les paramètres du module :

  <params>
    <param name="identifiant" type="text" default="" label="Identifiant" description="Identifiant du site à analyser au format UA- suivi de votre identifiant client, d'un tiret puis du numéro de votre site dans la liste." />
    <param name="restriction" type="list" default="" label="Restriction" description="Permet de limiter l'appel de statistiques à un type d'utilisateur seulement.">
      <option value="all">Tout le monde</option>
      <option value="gst">Visiteurs</option>
      <option value="mbr">Membres</option>
      <option value="adm">Administrateurs</option>
    </param>
  </params>

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

• default : indique la valeur par défaut de ce paramètre à l'installation du module, 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 module (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 du module :

</install>

Voir aussi :

• Modules Joomla
• Créer une template pour Joomla 1.5.x
• Création d'un module Hello World pour Joomla 1.5 (en anglais)