Ecrivez votre propre module

Vous pouvez déjà sponsoriser ce chapitre

Les modules sont le contenu et les éléments du « menu latéral ». Ils fonctionnent souvent indépendamment du contenu existant et des bases de données. Un exemple pourrait être un module Latest Articles (derniers articles) avec une liste des articles les plus récemment ajoutés au site. Comme vous pourrez le voir au cours de ce chapitre, afin de profiter pleinement de Joomla!, vous devez profiter des outils Joomla! (framework) contenus dans le dossier libraries/joomla. Joomla! utilise du PHP orienté objet donc la plupart des fichiers que vous trouvez dans le dossier libraries/joomla sont des fichiers de classes. En incluant ces dernières dans votre programme, vous laissez à Joomla! le soin d'effectuer tout le “travail lourd” à votre place.

La programmation dans Joomla! utilise des conventions. Cela suppose que vous devez structurer votre programme et choisir le nom de vos fichiers et classes d'une certaine manière. C'est un domaine dans lequel vous ne devriez pas être trop créatifs ;-).

Les modules pour le backend sont contenus dans le dossier administrator/modules, et les modules pour le frontend dans le dossier modules. Au sein de ces dossiers, chaque module possède son propre dossier qui commence par: mod_.

Nous allons maintenant prendre l'exemple d'une liste de contacts utilisée pour afficher une liste de succursales. Le code est dans un fichier joint à la fin de ce tutoriel. Voici à quoi ressemblera le module dans la partie frontend du site:

Dans le backend, vous serez en mesure de sélectionner la catégorie et le nombre de contacts à afficher. (La capture d'écran suivante utilise le template Hathor administrative).

Il y a six fichiers principaux, dont certains dans des sous-dossiers, dans le répertoire module/mod_contact_list. En plus de ces fichiers, chaque dossier contient un fichier factice index.html.

mod_contact_list.xml

Le fichier mod_contact_list.xml définit le module, la version minimum de joomla! sur laquelle il est supporté, les fichiers qu'il utilise ainsi que les paramètres qui seront utilisés. Ce fichier est nécessaire pour que le module puisse être installé. C'est la première partie de ce fichier qui donne la description basique du module:

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" version="1.7" client="site" method="upgrade">
   <name>MOD_CONTACT_LIST</name>
   <author>Andrea Tarr</author>
	<creationDate>November 2011</creationDate>
	<copyright>Copyright (C) 2011 Tarr Consulting. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later</license>
	<authorEmail>atarr@tarrconsulting.com</authorEmail>
	<authorUrl>www.tarrconsulting.com</authorUrl>
   <version>1.0</version>
   <description>MOD_CONTACT_LIST_XML_DESCRIPTION</description>

La balise <extension> détermine le type de module, la version minimum de Joomla! supportée et également si c'est un module frontend (0) ou un module backend (1). La méthode “upgrade” indique que si un répertoire de module portant le même nom existe déjà, on suppose que c'est une version antérieure de ce même programme qui peut donc être mise à jour. Si vous utilisez “install”, tout dossier en doublon empêchera l'installation. Les balises <name> et <description> utilisent des chaines de caractères qui seront traduites dans les fichiers de langues. Les fichiers de langues sont décrits plus loin dans ce tutoriel..

La partie suivante liste les fichiers. Ce sont les fichiers qui seront copiés pendant l'installation. Si vous avez des fichiers extérieurs au fichier zip, ils seront ignorés. Si vous listez un fichier qui n'est pas dans un fichier zip, le module ne s'installera pas.

    <files>
        <filename>mod_contact_list.xml</filename>
        <filename module="mod_contact_list">mod_contact_list.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>

Le fichier principal est repéré par l'attribut module. La balise <folder> va copier tous les fichiers ainsi que les sous-dossiers dans ce dossier.

La section suivante définit les paramètres que vous voyez dans la colonne de droite du backend. Cette section est située entre les balises <config>. Le groupe de paramètres est situé dans les balises <field> avec l'attribut de nom “params”. Chaque sous-ensemble est contenu dans des balises <fieldset>. En premier, les parametres de base, où nous choisissons la catégorie ainsi que le nombre d'articles:

    <config>
        
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="catid"
                    type="category"
                    extension="com_contact"
                    multiple="true"
                    default=""
                    size="10"
                    label="JCATEGORY"
                    description="MOD_CONTACT_LIST_FIELD_CATEGORY_DESC" >
                </field>

                <field
                    name="count"
                    type="text"
                    default="5"
                    label="MOD_CONTACT_LIST_FIELD_ITEMS_LABEL"
                    description="MOD_CONTACT_LIST_FIELD_ITEMS_DESC" />

            </fieldset>    

Chacun des paramètres individuels est dans des balises <field>. L'attribut "name" est utilisé pour récupérer le paramètre dans votre programme. L'attribut "type" définit le type du paramètre. Chacun de ces types est défini dans le Joomla Framework. Les types communément utilisés sont text, list, editor, textarea, category, calendar, radio, checkbox, checkboxes, media, folderlist, et filelist. Pour une liste complète, visitez: http://docs.joomla.org/Standard_form_fie.... Vous pouvez également créer votre propre type comme expliqué ici: http://docs.joomla.org/Creating_a_custom.... Les attributs label et description utilisent les chaines de caractères contenues soit dans les fichiers de langues globaux, soit dans les fichiers de langue de l'extension.

Les paramètres avancés suivants sont ceux que vous devriez utiliser pour tous vos modules sauf si vous ne voulez pas que les utilisateurs possèdent ces droits standards. Tout sauf le moduleclass_sfx fonctionnent automatiquement juste en incluant ce code. Pour faire fonctionner le moduleclass_sfx, vous devez ajouter <?php echo $moduleclass_sfx; ?> à la balise de classe dans le fichier HTML à l'endroit où vous voulez permettre à l'utilisateur de définir une classe spéciale.

            <fieldset
                name="advanced">

                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    description="JFIELD_ALT_MODULE_LAYOUT_DESC" />

                <field
                    name="moduleclass_sfx"
                    type="text"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC" />

                <field
                    name="cache"
                    type="list"
                    default="1"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    description="COM_MODULES_FIELD_CACHING_DESC">
                    <option
                        value="1">JGLOBAL_USE_GLOBAL</option>
                    <option
                        value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>

                <field
                    name="cache_time"
                    type="text"
                    default="900"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    description="COM_MODULES_FIELD_CACHE_TIME_DESC" />

                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid">
                    <option
                        value="itemid"></option>
                </field>

            </fieldset>

Terminez le fichier en fermant les balises

        </fields>
    </config>
</extension>

mod_contact_list.php

Le fichier mod_contact_list.php est le principal pour votre programme. Il joue le rôle du contrôleur dans une structure Model-View-Controller. De la même manière que nous séparons le contenu de la présentation et du comportement en séparant les fichiers HTML/CSS/JavaScript, nous séparons le contrôle du programme, les données (model), et l'affichage (view). Le fichier commence par vérifier que le fichier est appelé par Joomla! et non pas directement:

<?php
/**
 * Contact List
 * 
 */
 
// no direct access
defined('_JEXEC') or die;

Tous vos fichiers php doivent commencer avec ce code.

Nous allons mettre notre code de récupération de données dans le fichier helper.php, donc nous devons inclure ce fichier. Il contient une définition de classe, donc nous devons utiliser le require_once. dirname(__FILE__) donne le chemin du fichier en cours donc cela peut être utilisé comme chemin pour le fichier helper.php. Rappelez-vous que la définition d'une classe n'a aucun effet au moment de l'inclusion.

// Include the class of the syndicate functions only once
require_once(dirname(__FILE__).'/helper.php');

Ensuite, nous récupérons les données en faisant un appel statique à la classe définie dans le fichier helper.php et en mettant le résultat dans $liste. $params est un objet qui contient tous les paramètres définis dans le fichier xml.

// Static call to the class
$list = modContactListHelper::getList($params);

La ligne suivante effectue tout simplement un peu de nettoyage. Nous allons utiliser le paramètre de suffixe de classe du module pour construire une classe, il nous faut donc commencer par "désinfecter". En mettant cela ici, nous nous assurons que c'est fait même si un designer modifie le template.

$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

Pour finir, nous appelons le “framework module processor” qui va tout mettre ensemble et récupérer le HTML à afficher en se basant sur le fichier tmpl/default.php. Puisque c'est fait fait par une inclusion (include), toutes les variables sont encore disponibles.

require(JModuleHelper::getLayoutPath('mod_contact_list'));

C'est la fin du fichier. N'insérez pas de balise de fermeture ?>. La pratique dans Joomla! est de sauter toutes les balises PHP de fermeture parce que les caractères après la balise php, y compris certains caractères de contrôle, déclenchent l'envoi des entetes HTML prématurément, ce qui provoque des erreurs.

helper.php

Nous utilisons le fichier helper.php pour récupérer les données. Nous commençons le fichier php de la manière standard:

<?php
// no direct access
defined('_JEXEC') or die;

Nous voulons lister les contacts de la table de contact Joomla!, dans des catégories données. Comme nous utilisons une table venant d'un composant défini selon les standards de Joomla!, nous pouvons utiliser des définitions de modèle existantes dans notre programme. Pour faire cela, nous incluons la partie du Joomla Framework qui gère les modèles de composants et faisons un appel statique pour inclure les modèles venant du composant com_contact.

jimport('joomla.application.component.model');
JModel::addIncludePath(JPATH_ADMINISTRATOR.'/components/com_contact/models', 'ContactModel');

Maintenant il est temps de faire la définition de la classe. Cette classe n'a pas de propriété et getlist() est la seule méthode:

class modContactListHelper
{
    /**
     * Retrieves the list of contacts
     *
     * @param array $params An object containing the module parameters
     * @access public
     */    
    public function getList($params)
    {

La fonction commence par obtenir l'information globale, qui est récupérée par un appel statique de l'Application. C'est ce qui remplace l'ancienne variable globale $mainframe utilisée antérieurement dans Joomla!.

		$app	= JFactory::getApplication();

Nous récupérons ensuite la connexion à la base de données:

		$db		= JFactory::getDbo();

Maintenant nous devons créer un objet $model à partir des contacts. Nous utilisons un appel statique à Jmodel en lui précisant le composant (Contact) et le préfixe de classe (ContactModel). Le traitement du modèle force les états (states) à se souvenir dans quel état est le modèle (par exemple le réglage des filtres). Lorsque vous créez un module, vous ne souhaitez habituellement pas affecter un état au composant principal, donc ignore_request précise de ne pas se souvenir de l'état lié à ce traitement.

		// Get an instance of the generic contact model
		$model = JModel::getInstance('Contacts', 'ContactModel', array('ignore_request' => true));

Puis nous réglons les paramètres de l'application dans le modèle:

		$appParams = JFactory::getApplication()->getParams();
		$model->setState('params', $appParams);

Ensuite nous réglons les filtres en nous basant sur les paramètres du module. Le paramètre list.start est réglé sur 0 afin de commencer au début et nous réglons la fin (list.limit) en nous basant sur le compteur que nous avons entré dans les paramètres du module. Le paramètre filter.published est réglé sur 1 pour spécifier de ne récupérer que les contacts publiés. Enfin list.select liste les champs à renvoyer.

		$model->setState('list.start', 0);
		$model->setState('list.limit', (int) $params->get('count', 5));
		
		$model->setState('filter.published', 1);

		$model->setState('list.select', 'a.id, a.name, a.catid' . 
				', a.address, a.suburb, a.postcode, a.state, a.telephone ' .
				', a.published, a.access, a.ordering, a.language'.
				', a.publish_up, a.publish_down');

Le filtre suivant est utilisé par l'ACL pour s'assurer que seuls les contacts autorisés seront affichés.

		$access = !JComponentHelper::getParams('com_contact')->get('show_noauth');
		$authorised = JAccess::getAuthorisedViewLevels(JFactory::getUser()->get('id'));
		$model->setState('filter.access', $access);

Ensuite, nous filtrons par catégorie en nous basant sur les paramètres que nous avons entrés dans les paramètres du module. Notez que nous utilisons un tableau puisque nous avons autorisé l'appartenance multiple aux catégories lorsque nous avons défini le paramètre dans le fichier XML.

		$model->setState('filter.category_id', $params->get('catid', array()));

Les derniers filtres concernent le langage et l'ordre des contacts dans la liste.

		$model->setState('filter.language',$app->getLanguageFilter());
		$model->setState('list.ordering', 'ordering');
		$model->setState('list.direction', 'ASC');

Pour finir, nous appelons la méthode getItems() dans l'objet $model . Comme nous utilisons la méthode getItems() du composant de contact, nous n'avons pas besoin de l'écrire nous-même. Nous pouvons simplement utiliser celle qui existe déjà. Tous ce que nous devions faire était de définir l'état des filtres. Ensuite nous retournons la liste que nous venons de récupérer et nous fermons la fonction et la classe. Notez qu'ici aussi nous n'incluons pas de balise de fermeture php.

		$items = $model->getItems();
		      
		return $items;
    }
}

tmpl/default.php

Maintenant, tout ce que nous devons faire c'est écrire le HTML qui affichera la liste des informations que nous avons recueillies. En séparant le HTML et en le mettant dans un fichier layout lui-même situé dans le dossier tmpl nous permettons aux designers de modifier le template en changeant le HTML comme ils le souhaitent. Ce fichier commence comme les autres fichiers PHP, avec un test pour être sûr que seul Joomla! puisse l'appeler.

<?php
/**
 * Contact List Module Entry Point
 */ 

// no direct access
defined('_JEXEC') or die; ?>

Ensuite, nous mettons le HTML qui affichera la liste. C'est une bonne idée d'entourer le tout avec <div> avec une classe afin d'identifier le type de module, comme cela les designers (ou vous même) peuvent ajouter du style seulement pour ce module. C'est également une bonne place pour ajouter le suffixe de classe du module. Mettre le code PHP immédiatement après la classe de type de module est ce qui donne le plus de possibilités aux designers.

<div class="contact_list<?php echo $moduleclass_sfx; ?>">

Pour finir, nous créons une liste non-ordonnée et parcourons $list afin d'afficher chacune des lignes. Nous fermons ensuite le <div> englobant l'ensemble du fichier.

<ul>
<?php foreach ($list as $item) :?>
	<li><h4><?php echo htmlspecialchars($item->name); ?></h4>
	<p><?php echo nl2br(htmlspecialchars($item->address)); ?><br />
	<?php echo htmlspecialchars($item->suburb); ?>, 
	<?php echo htmlspecialchars($item->state); ?> 
	<?php echo htmlspecialchars($item->postcode); ?><br />
	<?php echo htmlspecialchars($item->telephone); ?></p></li>
<?php endforeach; ?>
</ul>
</div>

language/en-GB/en-GB_mod_contact_list.ini

C'est le principal fichier de langues pour le module. Vous mettez dans votre programme les clés du langage en lettres majuscules avec le préfixe MOD_CONTACT_LIST. L'assignation se fait avec le signe = et les chaines de caractères sont délimitées par des guillemets. C'est une structure différente de celle de la version 1.5. Cette nouvelle structure, qui est beaucoup plus rapide, n'autorise plus les espaces à l'intérieur des clés de langage. C'est un fichier ini, donc vous n'utilisez pas le “jexec or die ” au début du fichier.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_FIELD_CATEGORY_DESC="Select Contacts from a specific Category or Categories."
MOD_CONTACT_LIST_FIELD_ITEMS_DESC="The number of Contacts to display within this module"
MOD_CONTACT_LIST_FIELD_ITEMS_LABEL="Number of Contacts"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."

language/en-GB/en-GB_mod_contact_list.sys.ini

Le dernier fichier est le fichier de langue sys.ini. Ce fichier est uniquement utilisé sur les écrans d'installation et de mise à jour dans le backend et n'a besoin que des clés suivantes. Ces deux écrans doivent pouvoir accéder à de nombreuses extensions pouvant avoir de grands fichiers de langue. En incluant des fichiers sys.ini courts pour chaque extension, la performance est ainsi améliorée.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."
MOD_CONTACT_LIST_LAYOUT_DEFAULT="Default"

index.html

Vous devriez mettre un fichier index.html à la racine et dans chaque dossier / sous-dossier de votre module pour empêcher n'importe qui d'obtenir une liste des fichiers en entrant un répertoire dans la barre d'adresse. Le fichier peut être aussi simple que cela:

<!DOCTYPE html><title></title>

Packaging the Module for Installation

Comme nous avons déjà créé le fichier xml, la seule chose que vous devez faire pour créer un package d'installation est de zipper les fichiers et dossiers dans un dossier module. Assurez-vous de seulement zipper les dossiers et fichiers dans le dossier mod_contact_list et de ne pas inclure le dossier de niveau supérieur mod_contact_list lui-même.

Si vos fichiers font déjà partie d'un site Joomla!, vous pouvez utiliser à la place Extensions -> Gestion des extensions -> Découvrir pour installer le module. Cliquez sur l'icône Découvrir pour chercher des fichiers d'extension qui ne sont pas installés. Lorsque votre module apparaît, cochez la case d'à côté et cliquez sur Installer.

Le fichier attaché est téléchargeable à la fin de la page anglaise de ce document.