J3.x:Creating a simple module/Developing a Basic Module/fr

Joomla! 

3.x

Didacticiel

Création d'un module simple

Les articles de cette série

• Introduction
• Développement d'un module de base
• Utilisation de la base de données
• Ajouter des champs de formulaire
• Ajout d'une mise à jour automatisée
• Ajout d'un fichier script installation/désinstallation/mise à jour

Ceci est une série de plusieurs articles expliquant la façon de développer un module pour Joomla! Version . Vous pouvez naviguer dans les articles de cette série à l'aide du menu déroulant.

Commencez par l'Introduction puis naviguez dans les articles de cette série en utilisant soit les boutons de navigation situés en bas des articles, soit le menu droit (Les articles de cette série).

Les modules sont des extensions légères et flexibles. Ils sont utilisés pour de petites parties de page qui sont généralement moins complexes et peuvent être visibles à travers les différents composants.

Vous pouvez voir de nombreux exemples de modules dans une installation standard de Joomla : - menus - dernières actualités - formulaire de connexion - et bien d'autres.

Ce didacticiel vous explique comment créer un simple module Hello World. Grâce à lui, vous apprendrez la structure de fichiers de base d'un module. Cette structure de base peut ensuite être étendue afin de créer des modules plus élaborés.

Structure de fichier

Quatre fichiers de base sont utilisées dans le modèle standard de développement de modules :

• mod_helloworld.php - Ce fichier est le point d'entrée principale pour le module. Il va effectuer toute routine d'initialisation nécessaire, appeler les routines helper pour collecter les données nécessaires et inclure le template à afficher pour le rendu du module.

• mod_helloworld.xml - Ce fichier contient les informations sur le module. Il définit les fichiers à installer par l'installateur Joomla! et spécifie les paramètres de configuration du module.

• helper.php - Ce fichier contient la classe helper qui est utilisée pour procéder à la récupération des informations à afficher dans le module (généralement à partir de la base de données ou d'une autre source).

• tmpl/default.php - C'est le template du module. Ce fichier va prendre les données recueillies par mod_helloworld.php et générer le code HTML à afficher sur la page.

Création de mod_helloworld.php

Le fichier mod_helloworld.php va effectuer trois tâches :

• inclure le fichier helper.php qui contient la classe à utiliser pour recueillir les données nécessaires,
• invoquer la méthode de classe helper appropriée pour récupérer les données,
• inclure le template pour afficher le rendu.

La classe helper est définie dans notre fichier helper.php. Ce fichier comporte une déclaration require_once :

require_once dirname(__FILE__) . '/helper.php';

require_once est utilisé car nos fonctions helper sont définies dans une classe, et nous souhaitons que cette classe ne soit définie qu'une seule fois.

Notre classe helper n'a pas encore été définie, mais lorsqu'elle le sera, elle contiendra une méthode : getHello(). Pour notre exemple de base, il n'est pas vraiment nécessaire de le faire - le message “Hello, World” que cette méthode retourne pourrait simplement être inclus dans le template. Nous utilisons une classe helper ici afin de démontrer cette technique de base.

Pour l'instant, notre module n'utilise pas de paramètres, mais nous allons tout de même les passer par la méthode helper de sorte qu'ils puissent être utilisés ultérieurement si nous décidions d'étendre les fonctionnalités de notre module.

La méthode de classe helper est appelée de la manière suivante :

$hello = modHelloWorldHelper::getHello($params);

Terminer le fichier mod_helloworld.php

Le fichier mod_helloworld.php complet se présente ainsi :

<?php
/**
 * Hello World! Module Entry Point
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @license    GNU/GPL, see LICENSE.php
 * @link       http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */

// No direct access
defined('_JEXEC') or die;
// Include the syndicate functions only once
require_once dirname(__FILE__) . '/helper.php';

$hello = modHelloWorldHelper::getHello($params);
require JModuleHelper::getLayoutPath('mod_helloworld');

La seule ligne que nous n'ayons pas encore expliquée est la ligne defined('_JEXEC') or die;. Cette ligne garantir que ce fichier est appelé dans l'application Joomlaǃ. Cela est nécessaire pour éviter des injections fluctuantes et d'autres failles de sécurité.

Création du fichier helper.php

Le fichier helper.php contient cette classe helper qui est utilisée pour récupérer les données à afficher dans le rendu du module. Comme indiqué précédemment, notre classe helper contiendra une méthode : getHello(). Cette méthode va retourner le message 'Hello, World'.

Voici le code pour le fichier helper.php :

<?php
/**
 * Helper class for Hello World! module
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @link http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * @license        GNU/GPL, see LICENSE.php
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */
class ModHelloWorldHelper
{
    /**
     * Retrieves the hello message
     *
     * @param   array  $params An object containing the module parameters
     *
     * @access public
     */    
    public static function getHello($params)
    {
        return 'Hello, World!';
    }
}

Aucune règle ne nous contraint à nommer ainsi notre classe helper, mais cela facilite son identification et sa localisation. Notez que ce format est requit si vous prévoyez d'utiliser le composant com_ajax.

Des modules plus complexes peuvent inclure des requêtes de base de données ou d'autres fonctionnalités à l'aide de la méthode de classe helper.

Création de tmpl/default.php

Le fichier default.php est le template qui affiche le rendu du module.

Le code du fichier default.php se présente ainsi :

<?php 
// No direct access
defined('_JEXEC') or die; ?>
<?php echo $hello; ?>

Il est important de noter que le fichier de template a la même portée que le fichier mod_helloworld.php. Cela signifie que la variable $hello peut être définie dans le fichier mod_helloworld.php puis être utilisée dans le fichier de template sans déclarations supplémentaires ou appels de fonction.

Création du mod_helloworld.xml

Le mod_helloworld.xml est utilisé pour spécifier les fichiers que l'installateur doit copier, mais aussi par le gestionnaires des modules pour déterminer les paramètres utilisés pour configurer le module. D'autres informations sur le module sont également spécifiées dans ce fichier.

Le code du mod_helloworld.xml se présente ainsi :

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1.0" client="site" method="upgrade">
    <name>Hello, World!</name>
    <author>John Doe</author>
    <version>1.0.0</version>
    <description>A simple Hello, World! module.</description>
    <files>
        <filename>mod_helloworld.xml</filename>
        <filename module="mod_helloworld">mod_helloworld.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
    <config>
    </config>
</extension>

Les fichiers Manifest expliquent les détails techniques des éléments utilisés dans le fichier XML.

Vous remarquerez la présence de deux fichiers supplémentaires dont nous n'avons pas encore parlés : index.html et tmpl/index.html. Ces fichiers sont inclus afin que ces répertoires ne puissent pas être consultés. Si un utilisateur tente de visiter ces dossiers depuis un navigateur, le fichier index.html sera affiché. Ces fichiers peuvent être laissés vides ou contenir une simple ligne :

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

ce qui affichera une page vide.

Notre module n'utilisant pas de champs de formulaire, la section config est vide.

Installation et visualisation du module

Pour installer le module, compressez le répertoire parent de vos fichiers sources, afin de créer un fichier appelé mod_helloworld.zip. Notez qu'il doit s'agir d'un fichier .zip car le serveur doit pouvoir l'extraire à l'aide de la librairie mod_zlib d'Apache. Allez dans l'administration de Joomla, dans le formulaire Extensions / Gérer / Installer, cliquez sur l'onglet Mise à jour du fichier package, et téléchargez votre fichier zip. Vous devriez constater que le module s'installe correctement. Si ce n'est pas le cas, comparez soigneusement votre code avec le code ci-dessus, et assurez-vous que vos fichiers de code source sont nommés correctement. Pour rendre le module visible sur les pages web de votre site, allez dans la liste des Extensions / Modules et cliquez sur le module Hello World pour le modifier.

1. Définissez le statut sur Publié
2. Sélectionnez la position où le module doit apparaître (si vous n'êtes pas sûr de la position à définir, allez dans Extensions / templates / Styles, vérifiez quel template est attribué à vos pages Web, puis suivez ce guide pour trouver les positions du module).
3. dans l'onglet Affectation des menus, réglez l'affectation des modules sur "Sur toutes les pages".

Enregistrez et fermez votre formulaire d'édition. Maintenant, si vous naviguez sur votre site, vous devriez voir "Hello, World !" affiché dans la position du module que vous avez choisi.

Conclusion

Le développement de modules pour Joomla! est un processus assez simple. En utilisant les techniques de ce didacticiel une variété infinie de module peut être développée sans peine.

Préc. : Introduction

Suiv. : Utiliser de la base de données