Connexion S'inscrire

Connectez-vous

Login *
Mot de passe *
Se souvenir de moi

Créer un compte

Les champs marqués d'un astérisque (*) sont requis.
Nom *
Login *
Mot de passe *
Vérification mot de passe *
Email *
Vérification email *
Captcha *

Création d'un module pour Joomla côté administrateur


Nous allons voir dans ce tutoriel comment créer un module pour le panneau d'administration de Joomla. L'exemple de module que nous allons concevoir permet d'afficher le nombre total de vues des articles de Joomla ou des articles de K2.

Nous allons créer ce module directement dans un site Joomla de développement de préférence en localhost et à la fin, on compilera le tout dans un fichier archive d'installation. J'ai fait le choix d'appeler ce module "mod_dj_hits" mais vous pouvez l'appeler comme vous voulez (dj pour docteur Joomla bien sûr).

1 - l'architecture

Les modules de l'administration de Joomla se trouve dans le dossier "administrator/modules/". Nous allons créer dans ce répertoire le dossier mod_dj_hits qui est le dossier de notre module.

Voici une capture d'écran des différents fichiers et dossiers que ce module va contenir:

 

2 - Présentation des fichiers et dossiers

Deux fichiers sont obligatoires pour l'installation d'un module. L'architecture présenté est donc optionnelle mais offre un grand avantage en terme d'organisation de code et est donc une facile à maintenir.

a - Les fichiers obligatoires

mod_dj_hits.xml, permet d'informer Joomla des différents fichiers à charger lors de l'installation et permet aussi de définir les le formulaire de paramétrage du module.

mod_dj_hits.php, est le fichier principal que Joomla va utiliser.

b - Les fichiers optionnels

 index.html, est un fichier html vide que Joomla recommande pour des mesures de sécurité. Elle permet d'afficher une page blanche et éviter de lister les différents fichiers d'un repertoire si un aventurier essai d'accéder directement au repertoire dans un navigateur.

 helper.php, une classe php pour effectuer les différentes requêtes à la base de données.

tmpl/default.php, le fichier de vue par défaut qui sera utilisé par notre module

3 - Le contenu

1 - le fichier XML (mod_dj_hits.xml)

Tout extension Joomla commence par la balise extension qui a des propriétés suivantes:

type: le type d'extension module dans notre cas. Les valeurs possibles: component, module, file, language, library, module, package, plugin, template

client: peut avoir pour valeur administrator ou site pour indiquer si ce module est utilisé en administration ou sur le site

method: upgrade ou install. La méthode install ne permet pas de mise à jour. Pour installer une nouvelle version, il faudrait désinstaller l'ancienne alors que la méthode upgrade permet d'installer des mise à jour sans désinstaller la version antérieur.

version: version à partir de laquelle le module peut être utilisé. Dans notre cas, c'est à partir de la version 3.0. 

 

Après l'ouverture de la balise extension, un ensemble de balises d'informations:

name: le nom lisible du module (tel qu'il sera afficher aux utilisateurs sur le site)

author: Le nom de l'auteur de l'extension

creationDate: La date de création de l'extension

copyright: Les informations relative au droit d'auteur.

authorEmail: Adresse email de l'auteur

authorUrl: Site web de l'auteur

version: la version de l'extension

description: La description de l'extension qui sera affiché juste après l'installation

 

Les différents fichiers et dossiers sont listés entre les balises files pour informer Joomla des différents fichiers à charger lors de l'installation

filename: permet de définir le fichier principal de notre module.

file: permet de définir un fichier

folder: de définir un dossier

 

La balise config contient les configurations du module.

fields name="params": regroupe les différents champs de configuration

fieldset: bloc de type accordéon pour diviser le formulaire en plusieurs onglets

field: permet de d'ajout un élément au formulaire. Dans notre cas, c'est une liste pour choisir si on compte les clics des articles de K2 (un composant avancé de gestion d'articles) ou des articles de Joomla. Vous pouvez voir la liste complète des champs ici

Voici le contenu de notre fichier mod_dj_hits.xml:


<?xml version="1.0" encoding="utf-8"?>
<extension type="module" client="administrator" method="upgrade" version="3.0">
    <name>DJ Total clics K2 ou Article (admin)</name>
    <author>Docteur Joomla</author>
    <creationDate>November 27, 2016</creationDate>
    <copyright>Copyright (C) 2005 - 2016 Open Source Matters. All rights reserved.</copyright>
    <authorEmail>Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.</authorEmail>
    <authorUrl>www.docteurjoomla.com</authorUrl>
    <version>1.0</version>
    <description>MOD_DJ_HITS_DESCRIPTION</description>
  
    <files>
        <filename module="mod_dj_hits">mod_dj_hits.php</filename>
        <file>helper.php</file>
        <file>index.html</file>
        <folder>tmpl</folder>
    </files>
  
  <config>
        <fields name="params">
            <fieldset name="basic">
		<field name="content_mode" type="list" default="0" label="MOD_DJ_DITS_COMPONENT_CHOICE" description="MOD_DJ_DITS_COMPONENT_CHOICE_DESC">
                    <option value="0">MOD_DJ_HITS_JOOMLA_ARTICLES</option>
                    <option value="1">MOD_DJ_HITS_K2_ARTICLES</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

2 - le fichier mod_dj_hits.php

Pour des raisons de sécurité, Joomla recommande que tout fichier php commence par la verification de l'existante de la constante "_JEXEC". Cette vérification permet d'éviter que le code du fichier soit exécuté si on y accède directement dans le navigateur, d'être sûr que l'exécution soit fait uniquement à l'intérieur de Joomla.

Dans ce fichier, nous incluons le helper pour utiliser ses méthodes qui calcule le nombre total de clics. l'objet $params représente le module en cours et on fait appel à la méthode get pour récupérer la valeur de "content_mode" qui est modifiable dans les configuration du module dans l'administration de Joomla. le second paramètre (0) est la valeur par défaut.

Ensuite, nous faisons appel à la méthode getHits du helper en lui passant le mode en paramètre pour retourner le nombre total de clics. Nous verrons le contenu du helper.php plus bas.

Pour finir, nous utilisons la class JModuleHelper de Joomla pour inclure le layout (fichier de mise en page). Il est possible de faire plusieurs layout dans le dossier tmpl et de permettre à l'utilisateur de choisir son layout dans la configuration. La dernière ligne pourra donc être: require (JModuleHelper::getLayoutPath('mod_dj_hits', $params->get('layout', 'default')));  en supposant que vous avez ajouté un élément (field) nommé "layout" permettant de sélectionner le layout dans le xml (dans la section config) vue précédemment.


<?php
defined('_JEXEC') or die;
  
//On inclut le helper pour pouvoir utiliser les méthodes de classe
require_once (dirname(__FILE__).DIRECTORY_SEPARATOR.'helper.php');

//On utilise l'objet params pour récupérer notre paramêtre pour savoir si c'est des articles Joomla ou K2. il fonctionne avec des articles Joomla par défaut
$mode = $params->get('content_mode', 0); 

$totalHits = DJHelper::getHits($mode); 
  
require (JModuleHelper::getLayoutPath('mod_dj_hits', 'default'));

3 - Le helper 

Vue que notre module est assez simple, notre classe contiendra une seule méthode.

la classe JFactory permet de récupérer une instance des objets au cœur de Joomla. Dans la méthode getHits, on s'en sert pour récupérer une instance de la classe "JDatabaseDriver" qui gère les accès à la base de données. Mais elle peut être dans beaucoup de cas voir plus de détails ici

Le fichier helper.php se présente comme suit:


<?php
defined('_JEXEC') or die;

abstract class DJHelper
{
  
  public static function getHits($mode=0){
    
    $db = JFactory::getDbo();
    $query = $db->getQuery(true);
    $query->select('sum(hits)');
    
    if($mode == 1){
      $query->from('#__k2_items');
    }
    else{
      $query->from('#__content');
    }
    
    $db->setQuery($query);
     
    return $db->loadResult();
      
  }
  
} 

4 - Le layout (default.php)

Le fichier de mise en page (layout) contient le html d'affichage. On ajoute la classe icon-eye à une balise span pour afficher un icône d'œil avant le text. La méthode "_" de la classe JText de Joomla permet d'afficher un texte venant du fichier de langue. En utilisant la clé qui lui es passé en paramètre, cette méthode va sélectionner le texte correspondant dans le fichier de langue. Si l'élément n'existe pas dans le fichier de langue, elle affichera la clé. La concatenation avec la variable $mode ajoute 0 ou 1 en fonction de la valeur que contient mode (valeur qui vient de la configuration du module) pour permettre d'afficher le texte correspondant (items K2 ou Articles Joomla) dans le fichier de langue. Voici le contenu du fichier:


<?php
defined('_JEXEC') or die;

?>
<div>
<p><span class="icon-eye"></span><?php echo JText::_('MOD_DJ_HITS_HITS_TOTAL_'.$mode); ?>: <span class="bigger"><?php echo $totalHits; ?></span></p>
</div> 

 5 - Les fichiers de langue:

 Les fichiers de langues de l'administration de Joomla sont regroupés dans le dossier de langue qui se trouve dans "administrator/language/". Le dossier fr-FR contient tous les fichiers de langue en français de France en-GB pour l'anglais Grande-Bretagne... L'exemple ici se base sur un site en français  mais vous pouvez renommer le fichier pour la langue désirée. Nous allons créer dans le dossier fr-FR les fichiers suivants:

- fr-FR.mod_dj_hits.sys.ini: Ce fichier est utilisé par Joomla au moment de l'installation

- fr-FR.mod_dj_hits.ini: Ce fichier est utilisé pour l'affichage des éléments après l'installation.

Le contenu de fr-FR.mod_dj_hits.sys.ini:


MOD_DJ_HITS="Docteur Total clics Articles ou K2"
MOD_DJ_HITS_DESCRIPTION="Ce module affiche le nombre total de clics sur les article Joomla ou K2!"

Le contenu de fr-FR.mod_dj_hits.ini:


MOD_DJ_HITS_DESCRIPTION="Ce module affiche le nombre total de clics sur les article Joomla ou K2!"
MOD_DJ_DITS_COMPONENT_CHOICE="Type de Contenu"
MOD_DJ_DITS_COMPONENT_CHOICE_DESC="Choisir le type de contenu"
MOD_DJ_HITS_JOOMLA_ARTICLES="Articles de Joomla"
MOD_DJ_HITS_K2_ARTICLES="Items K2"
MOD_DJ_HITS_HITS_TOTAL_0="Nombre total de clics des Articles Joomla"
MOD_DJ_HITS_HITS_TOTAL_1="Nombre total de clics des Items K2"

6 - Installation du module

Connectez-vous à l'interface d'administration de Joomla avec un compte "Super User". Cliquez Extension>>Gérer>>Découvrir

Vous accéderez à une page qui liste les différentes extensions qui ont été déposé directement dans les dossiers de Joomla sans passer par la méthode d'installation classique. Il vous reste juste à sélectionner notre module dans la liste et de cliquer sur installer.

7 - Création d'un paquetage d'installation

copier le dossier du module mod_dj_hits qui se trouve dans "administrator/module" sur le bureau ou à un emplacement de votre choix. Créez un dossier language et dans ce dossier et ajoutez les fichiers fr-FR.mod_dj_hits.ini et fr-FR.mod_dj_hits.sys.ini qui se trouvent dans "administrator/language/fr-FR".

Ajoutez les fichiers de langues au fichier xml d'installation (mod_dj_hits.xml). Vous pouvez le mettre juste après la fermeture de files par exemple:


<languages>
  <language tag="fr-FR">language/fr-FR.mod_dj_hits.ini</language>
  <language tag="fr-FR">language/fr-FR.mod_dj_hits.sys.ini</language>
</languages>

 Compressez le dossier contenant tous les fichiers en choisissant un des format d'archives supportés par Joomla: .gz, .tar, .tar.gz et .zip.

 Vous pouvez maintenant utiliser l'archive pour installer votre module sur n'importe quel site Joomla 3.x. 

Pour savoir comment afficher le module dans l'administration de Joomla, Cliquez ici!


  • Dernière modification le mercredi, 21 février 2018 17:20
  • 1128
Docteur Joomla

Après plus de 10 ans d'expérience en Joomla, je lance ce Blog pour partager mes connaissances avec les autres développeurs Joomla.

Media