Développement d'un composant minimum

Développement d'un composant basique avec Joomla 1.6

Dans ce premier tutoriel, nous allons développer notre premier composant sous Joomla 1.6.

Pour bien comprendre et avancer doucement, ce composant ne servira à rien.
Il affichera simplement le message "mon premier composant développé en Joomla 1.6". Nous perfectionnerons ce composant au cours des prochains tutoriels.

Objectifs du tutoriel

Ce tutoriel nous permettra :

de mettre en oeuvre le MVC de Joomla,
de nous familiariser avec l'organisation des fichiers d'un composant Joomla 1.6,
de voir certaines classes et méthodes essentielles au développement avec le framework de Joomla 1.6,
de mettre en évidence certaines règles imposées par le framework.

Arborescence et fichiers du composant

Voici le sujet qui est sans doute le plus désagréable dans Joomla ! Les conventions de nommages et d'arborescences des fichiers imposés par le framework sont franchement lourdes !
Mais bon il va falloir nous y faire...

Tout d'abord, créer un dossier "com_minimum", le nom est peu important, mais ce sera plus pratique ainsi, car nous allons appeler notre composant "minimum".

Lancer votre IDE ou éditeur de texte préféré.

Fichiers index.html

Pour éviter qu'un petit malin tente d'accéder à l'arborescence de vos fichiers, une bonne pratique consiste à placer dans chaque dossier un fichier index.html vide ou contenant le minimum:

<html>
 <head></head><body><body>
</html>

Ce fichier s'exécutera si l'url pointe vers le dossier qui le contient. C'est une sécurité très relative, mais comme ca ne mange pas de pain, autant l'utiliser.

Fichier de description

A l'intérieur de ce dossier, créer un fichier xml portant le même nom que notre composant, soit "minimum.xml".

Ce fichier va contenir toute la description nécessaire à Joomla pour installer notre composant (pour le désinstaller aussi d'ailleurs).

Voici le contenu de notre fichier de description :

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade"> 
 <name>Minimum</name>
 <authore>Axoloth</authore>
 <creationDate>18-05-2011</creationDate>
 <copyright>2011. Axoloth</copyright>
 <license>GNU/GPL</license>
 <authorEmail></authorEmail>
 <authoreUrl></authoreUrl>
 <version>1.0.0</version>
 <description>Tutoriel 1 : Composant minimum MVC</description>
 <files folder="site"> 
 <filename>controller.php</filename>
 <filename>index.html</filename>
 <filename>minimum.php</filename>
 <folder>models</folder>
 <folder>views</folder> 
 </files>
 
 <administration>
 <menu>Minimum</menu> 
 </administration> 
</extension>

Explications :

La première ligne indique l'encodage de notre fichier xml.

Le noeud "extension" qui commence en ligne 2, indique le type d'extension, ici "component" pour un composant.
Vous l'aurez compris le paramètre type pourrait prendre la valeur "module", "plugin" ou "template" selon la nature de notre développement, et même "library", "file" ou "language".

Le paramètre "version" indique la version de Joomla pour laquelle notre composant est destiné.

Le paramètre "method" indique à Joomla le type d'installation qu'il doit effectuer avec notre composant. Mettez toujours "upgrade" cela permet à la fois d'installer et de mettre à jour.
Pour info le paramètre "method" aurait pû prendre la valeur "install".

Les balises "name", "author", "authorEmail", "authorUrl", "copyright", "license", "creationDate" et "description" sont simplement des informations qui s'afficheront dans le gestionnaire d'extension.

Plus intéressant, le noeud <files folder="site"> indique à Joomla la présence d'un dossier "site" qu'il devra recopier au bon endroit lors de l'installation.
Les balises qui suivent, "filename" et "folder", indiquent également la présence de fichiers et de dossiers que Joomla devra prendre en compte lors de l'installation.

Nous verrons le noeud "administration" plus en détail ultérieurement, pour l'instant, il contient juste "menu" qui va déterminer le nom qui s'affichera dans le menu extension de l'interface d'administration.

Arborescence minimum

D'après l'explication du fichier xml ci-dessus, vous comprendrez qu'il nous faut créer le dossier "site" à la racine de notre dossier.

dans ce dossier "site", créez les sous dossiers "models" et "views".

Le dossier site contiendra toute la partie public de notre composant. Si notre composant disposait d'une interface d'administration, nous aurions créé un autre dossier avec le nom "admin", nous verrons cela dans un prochain tutoriel.

Les sous dossiers /site/models et /site/views, comme leurs noms l'indiquent, contiendront les fichiers qui concernent respectivement le modèle et la vue de notre architecture MVC.

Nous avons vu que le MVC de Joomla enrichissait la "vue" d'un moteur de template.
Nous allons donc avoir des fichiers définissant notre template.
Pour cela, créez le sous dossier /site/views/minimum/tmpl

Vous pouvez copier le fichier index.html (vu plus haut) dans chacun de ces dossiers.

Pour résumer, voici l'arborescence que vous devez créer :

Point d'entrée du composant

A la racine du dossier "com_minimum/site", créer un fichier "minimum.php".

Ce fichier sera le point d'entré de notre composant, il doit porter le nom du composant, avec l'extension "php".

Rappel : c'est ce fichier qui sera appelé lorsque le serveur recevra une requête du type :
http://www.nomDuSite.com/index.php?option=com_minimum

Cette requête sera générée en cliquant dans un menu que nous définirons un peu plus loin.

Voyons ce que doit contenir notre fichier /minimum.php

<?PHP
defined('_JEXEC') or die('Restricted access');

jimport('joomla.application.component.controller');
$controller = JController::getInstance('Minimum');

$controller->execute(JRequest::getCmd('task'));

$controller->redirect();

Tout d'abord, notons que la balise PHP n'est pas refermée. Cela peut paraître bizarre, mais c'est normal, en fait elle est fermée par joomla au cours des multiples inclusions de fichiers.

Explications :

defined('_JEXEC') or die('Restricted access');

Cette ligne est une sorte de sécurité. Elle teste si la constante _JEXEC est définie. Si ce n'est pas le cas, cela signifie que le fichier minimum.php n'a pas été appelé par Joomla, l'accès est alors refusé. Pour information, cette variable est définie (ainsi que d'autres que nous verrons plus tard) lors du chargement de index.php à la racine de Joomla. Les constantes de Joomla sont définies dans "includes/defines.php" et "administrator/includes/defines.php".

jimport('joomla.application.component.controller');
Cette ligne sert à charger le contrôleur principal de Joomla.

$controller = JController::getInstance('Minimum');
Cette ligne va à la fois importer le contrôleur spécifique de notre composant, et en créer une instance utilisable via la variable $controller.

Nous devons créer le fichier qui va contenir notre contrôleur. Ce fichier doit se situer dans le dossier "com_minimum/site" de notre composant, et s'appeler "controller.php".
Le fichier "controller.php" doit contenir une classe qui étend le controleur principal de Joomla, soit la classe JController. Le nom de cette classe doit être "MinimumController", puisque notre composant s'appelle "Minimum".

C'est grâce au respect de cette convention de nommage que Joomla sait importer et instancier la classe en indiquant simplement son nom dans la commande "JController::getInstance('Minimum');".

$controller->execute(JRequest::getCmd('task'));
Cette ligne demande l'éxecution de la méthode dont le nom est transmis en request via le paramètre "task". Par exemple l'url www.monSite.com/index.php?option=com_minimum&task=toto va chercher à appeler une méthode "toto" du contrôleur.
Si aucun nom de méthode est transmis, Joomla appelle la méthode "display()" du contrôleur principal, qui à son tour appel "display()" de la vue par défaut.

La dernière ligne indique à Joomla qu'il doit éventuellement procéder à une redirection ordonnée par le contrôleur.

Le contrôleur minimum

Rappel : notre contrôleur va orienter le code pour exécuter les requêtes demandées. Le code va, par convention contenir des méthodes publiques qui représenteront les actions à exécuter.

Voyons le contenu de notre contrôleur "com_minimum/site/controller.php".
Comme dit plus haut, notre contrôleur doit étendre JController, le contrôleur principal de Joomla, dont la classe est définie dans le fichier "/librairies/joomla/appplication/component/controller.php".

Dans un premier temps, nous n'allons pas créer de méthode spécifique et laisser Joomla appeler la méthode principale "display()", nous aurons ainsi un contrôleur minimal, dont voici le code :

<?PHP
defined('_JEXEC') or die('Restricted access');

jimport('joomla.application.component.controller');

class MinimumController extends JController
{
}

Notre contrôleur, réduit à sa plus simple expression, se contente donc de définir une classe qui étend JController.

La vue

Comme annoncé, notre vue doit déclarer une méthode publique "display()" appelée par "controller.php".

Notre fichier de vue doit s'appeler "view.html.php" et, vous l'aurez deviné, être placé dans le dossier "com_minimum/site/views/minimum/".

Pourquoi le nom "view.html.php" et pas seulement "view.php" ?
Et bien parce que vous êtes libre de faire une vue qui restitue autre chose que de l'HTML. Si vous voulez faire une vue qui crée du pdf, votre fichier s'appellera "view.pdf.php".

Comme notre contrôleur, notre vue doit étendre un objet principal du framework de Joomla, en l'occurence JView, définit dans le fichier "/librairies/joomla/appplication/component/view.php".

Toujours dans l'idée d'être simple, pour l'instant, notre vue va simplement demander au modèle un contenu à afficher à l'écran.

Voici le code de notre exemple :

<?PHP
defined('_JEXEC') or die('Restricted access');

jimport('joomla.application.component.view');


class MinimumViewMinimum extends JView
{
    /* Surcharge de la méthode display de la classe JView */
    function display($tpl = null) 
    {
        /* Appel de la méthode getMessage du modele */
        $this->message = $this->get("Message");
        
        parent::display($tpl);
    }
}

On remarquera que la fonction "display()" reçoit en paramètre le template à utiliser. Par défaut, Joomla va passer le template par défaut du site.

$this->message = $this->get("Message");
Curieux ? cette ligne fait appel à un attribut "message" non défini dans notre classe !
Idem pour l'appel à la méthode $this->get(), cette méthode n'est pas définie ici !

Normal, ne soyez pas dérouté par cela, prenez le temps de regarder la classe JView de Joomla. Vous comprendrez alors que la "vue" connait le "modèle" et peut appeler des méthodes définies dans celui-ci via la méthode "get( nomMethodeDuModele ).

La prochaine étape va donc consister à écrire une classe modèle contenant une méthode getMessage().

Le modèle

Le fichier va naturellement s'appeler "minimum.php" (nom du composant), et se situer dans le dossier "com_minimum/site/models/".

La classe définissant notre modèle, doit s'appeler "MinimumModelMinimum", elle va étendre une des classes de modèle de Joomla.

Ici nous allons étendre JModelItem, c'est la plus simple. Joomla propose d'autres classes pour faciliter le codage : ModelList, ModelForm. Ces classes étendent toutes JModel, situé dans le fichier "/librairies/joomla/appplication/component/model.php".


defined('_JEXEC') or die('Restricted access');

/* importation de JModelItem, classe de modèle de base de Joomla */
jimport('joomla.application.component.modelitem');

/*
 * Spécialisation de JModelItem pour notre composant
 */
class MinimumModelMinimum extends JModelItem
{

    protected $message;
    
    public function getMessage() 
    {
        if (!isset($this->message)) 
        {
            $this->message = 'mon premier composant d&eacute;velopp&eacute en Joomla 1.6';
        }
        return $this->message;
    }
}

Voilà, rien de particulier ici, notre méthode getMessage renseigne l'attribut $message et le retourne.

Le template

Voici la dernière étape avant de pouvoir lancer notre composant.
Nous allons créer une page de template , très simple, affichant simplement le contenu de la variable $message, fournie par notre modèle et comme nous l'avons vu, transmise à notre vue.

Notre fichier va s'appeler default.php, puisqu'il s'agira de l'affichage par défaut. Il sera situé dans "/site/views/minimum/tmpl" :

defined('_JEXEC') or die('Restricted access');?>
<?php echo $this->message; ?>

Ajoutons simplement un fichier de description de notre template, dans le même dossier et avec un nom identique. Le fichier de description s'appelera donc "default.xml".

<?xml version="1.0" encoding="utf-8"?>
<metadata>
    <layout title="Axoloth, composant minimum">
        <message>Affiche simplement un message à l'écran</message>
    </layout>
</metadata>

Cette description, très simple, indique le titre et la description de notre composant qui apparaîtront dans l'interface "menu" de Joomla.

Nous verrons dans le deuxième tutoriel, que nous aurions dû mettre des "clés" plutôt que le texte. Par exemple plutôt que de mettre "Axoloth, composant minimum", nous aurions dû mettre "COM_MINIMUM_TITLE".

La clé aurait ensuite été associée à notre texte dans un fichier de langues, permettant ainsi l'internationalisation de notre texte.

On verra cela un peu plus tard, cela ne gêne en rien le fonctionnement de notre composant.

Installation du composant dans Jooma 1.6

Vous pouvez installer votre composant comme n'importe lequel., soit en indiquant à Joomla le chemin de votre dossier "/com_minimum", soit en faisant un zip de votre dossier "com_minimum".

Il suffit donc ensuite de vous connecter en admin, d'aller dans le gestionnaire d'extension, de cliquer sur "parcourir" dans l'encart "archive à transférer". Indiquez votre fichier zip et cliquez sur "Envoyer et Installer".

Voilà, Joomla connaît notre composant.

Pour tester notre composant, créez un menu de type "Axoloth, composant minimum". Lancez la prévisualisation du site et cliquez sur le menu.

Le message "mon premier composant développé en Joomla 1.6 " doit apparaître.

Vous pouvez télécharger le zip de ce tutoriel en cliquant ici.

Axoloth

Cours et tutoriels Joomla

Développement de sites clé en main

Joomla 1.6

En vrac

Sites intéressants

A propos d'Axoloth

Partenaires