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).

Un module est une extension légère et flexible. 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 ne 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 faire la démonstration de cette technique de base.

Notre module n'utilise pas actuellement de paramètres, mais nous allons tout de même les passer à 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.

The helper class method is invoked in the following way:

$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');

The one line that we haven’t explained so far is the first line. This line checks to make sure that this file is being included from the Joomla! application. This is necessary to prevent variable injection and other potential security concerns.

Création du fichier helper.php

The helper.php file contains that helper class that is used to retrieve the data to be displayed in the module output. As stated earlier, our helper class will have one method: getHello(). This method will return the ‘Hello, World’ message.

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!';
    }
}

There is no rule stating that we must name our helper class as we have, but it is helpful to do this so that it is easily identifiable and locatable. Note that it is required to be in this format if you plan to use the com_ajax plugin.

More advanced modules might include database requests or other functionality in the helper class method.

Création de tmpl/default.php

The default.php file is the template which displays the module output.

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

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

An important point to note is that the template file has the same scope as the mod_helloworld.php file. What this means is that the variable $hello can be defined in the mod_helloworld.php file and then used in the template file without any extra declarations or function calls.

Création du mod_helloworld.xml

The mod_helloworld.xml is used to specify which files the installer needs to copy and is used by the Module Manager to determine which parameters are used to configure the module. Other information about the module is also specified in this file.

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>

Manifest files explains the technical details of the elements used in the XML file.

You will notice that there are two additional files that we have not yet mentioned: index.html and tmpl/index.html. These files are included so that these directories cannot be browsed. If a user attempts to point their browser to these folders, the index.html file will be displayed. These files can be left empty or can contain the simple line:

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

ce qui affichera une page vide.

Since our module does not use any form fields, the config section is empty.

Conclusion

Module development for Joomla! is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.

Préc. : Introduction

Suiv. : Utiliser de la base de données