Créer un module pour Joomla 1.5

Facebooktwittergoogle_plusredditpinterestlinkedinmail

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.

La structure d’un module

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 fonction du nom de votre module.

Initialisation

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 :

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.

Classe fonctionnelle

Voici le contenu de notre fichier helper.php :

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.

Mise en forme

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

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

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 :

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 :

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 :

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

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 balisesdé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 balisesdé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> :

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 :

Voir aussi :

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *