Mésaventures au pays des CMS

Cette série d’articles est une traduction de l’existant en anglais ici.

Introduction

Un Framework logiciel est la base d’une application qui peut être utilisée par un développeur. Dans Joomla 1.5 ce framework est d’une grande puissance pour le développement. Le code de Joomla! a été développé pour être extensible. Ce tutoriel vous guidera au travers du processus de développement d’un composant en utilisant ce framework.

L’objectif de ce projet est de développer un simple composant « Hello World ». Dans les tutoriels à venir ce framework simple sera utilisé pour montrer la pleine puissance du développement MVC avec Joomla!

Prérequis

Vous devez avoir un site Joomla 1.5 installé en local ou chez votre hébergeur.

Introduction au Modèle Vue Contrôleur

Bien que l’idée d’un composant puisse être très simple, le code peut, lui, rapidement devenir complexe quand des fonctionnalités additionnelles sont ajoutées ou que l’interface est modifiée.

Le principe Modèle-Vue-Controleur (appelé par la suite MVC) est un schéma de développement logiciel qui peut être utilisé pour organiser le code pour séparer la logique métier de la présentation des données. Il faudra donc organiser la logique métier dans une section et l’interface ainsi que l’interaction utilisateur seront quand à eux  pourront être modifiés et mis à jour sans avoir à reprogrammer complètement l’application ni modifier la logique métier. Le MVC a été développé à l’origine pour cartographier les tâches d’ajout de données, le traitement de celles-ci et le rendu final dans une interface logique utilisateur (GUI en Anglais).

Ces trois rôles principaux sont la base du MVC de Joomla!. Ils sont décris ici brièvement mais pour de plus amples explications vous pouvez vous référer aux liens à la fin du tutoriel.

Modèle

La partie modèle du composant encapsule les données de l’application. Il fourni souvent les routines utilisées pour gérer et manipuler ces données de façon sensée en plus de récupérer les données depuis le modèle. Dans notre cas, le modèle contiendra les méthodes pour ajouter, supprimer et mettre à jour les informations de bienvenue dans la base de données. Il contiendra aussi les méthodes pour récupérer les données dans la base. En général, l’accès aux données techniques est encapsulé dans le modèle. Ainsi, si l’on passe d’une application dont les données sont stockées dans un fichier vers un système qui utilise une base de données il ne faut modifier que le modèle de l’application pour que celle-ci continue de fonctionner.

Vue

La vue est la partie du composant utilisée pour mettre en forme les données du modèle de façon adéquate pour être présentées à l’utilisateur. Pour une application web, la vue sera généralement une page HTML qui est retournée. La vue prend les données du modèle (qui sont passées par le controleur) et rend les données dans un template qui est mis à jour avec les données puis présenté à l’utilisateur. La vue ne doit en aucun cas modifier les données. Elle affiche simplement les données du modèle mises en forme.

Controleur

Le controleur est responsable de répondre aux actions de l’utilisateur. Dans le cas d’une application web une action utilisateur est généralement une requète pour l’affichage d’une page. Le controleur détermine quelle requête est faite et la réponse appropriée en demandant au modèle de manipuler les données puis d’afficher la vue. Le controleur n’affiche pas de données. Il fait simplement la relation entre la requête et la méthode a utiliser dans le modèle qui lui modifie les données puis transmet à la vue pour faire le rendu final.

Connexions MVC

L’image simplifiée de droite montre un composant basique utilisé avec Joomla.

La partie 1 du tutoriel fera un zoom sur le controleur et sur le vue (avec l’utilisation d’un template). Les parties 2 et 3 traiteront des fonctionnalités du modèle pour la manipulation de données.

Il faut conserver à l’esprit que le schéma s’applique uniquement pour la partie visible du site (le frontend des visiteurs). Un autre schéma identique est appliqué pour la partie gestion du site (backend). La partie administration sera traitée dans les parties 4 à 6 du tutoriel de développement. Les deux parties du site backend et frontend sont maintenues et configurées dans un fichier d’installation XML (appelé communément fichier manifeste).

Joomla! Implémentation MVC

Dans Joomla! le schéma MVC est implémenté en utilisant trois classes : JModel, JView et JController. Pour plus de détails sur ces classes vous pouvez lire la documentation de l’API.

Pour les besoins de l’apprentissage et de débuggage ajouter un outil de débug à votre installation de Joomla est utile. Un bon exemple d’application est le projet J!Dump qui a l’avantage d’être un pop-up qui laisse la vue inchangée. Le system J!Dump vous permet de voir les propriétés de votre développement en cours mais aussi les méthodes.

Créé un composant

Pour notre composant de base nous avons besoin de seulement cinq fichiers :

• site/hello.php – Le point d’entrée de notre composant
• site/controller.php – Ce fichier contient notre controleur de base
• site/views/hello/view.html.php – Ce fichier récupère les données nécessaires et les inclus dans le template
• site/views/hello/tmpl/default.php – C’est le template pour notre sortie
• hello.xml – Ce fichier XML (manifest) dit à Joomla! comment installer le composant

Il faut ce rappeler que le fichier « point d’entrée » du composant doit porter le même nom que celui-ci. Par exemple, si votre composant s’appelle « mon composant de démo »  Joomla créera lors de l’installation un répertoire com_moncomposantdedemo et le point d’entrée sera le fichier moncomposantdedemo.php, sinon il ne fonctionnera pas. Attention à l’utilisation des caractères spéciaux qui peuvent avoir une signification particulière pour Joomla! (notamment le _ ). Il faut donc éviter de les utiliser dans les noms de fichiers et composants.

The site directory here is for the parts of the component which are installed in the front end site.

Conventions de nommage

Il est important de savoir que certain mots sont réservés pour les composants et les classes. Les utiliser sans savoir ce que l’on fait peut produire des difficultés pour le débuggage. Un des mots réservé est « view » pour la classe vue (sous classe de JView) et pour la classe contrôleur (sous classe de JController) parce que la classe vue a besoin d’avoir la première partie de son nom identique à celle du contrôleur et du composant.

Tous les noms de fichiers et de répertoires des modèles, vues et contrôleurs doivent être ecrit en minuscule afin de fonctionner correctement sur les systèmes UNIX et Linux.

Créer le point d’entrée

Les accès à Joomla se font à partir d’un fichier unique : index.php pour la partie visiteur ou administrator/index.php pour la partie administration.L’application va ensuite charger le composant nécessaire en ce basant sur la valeur de la variable ‘option’ dans l’URL ou les données dans le POST. Pour notre composant l’adresse sera :

index.php?option=com_hello&view=hello

Ceci charge notre fichier principal qui peut être vu comme le seul point d’entrée de note composant : components/com_hello/hello.php

Le code pour ce fichier est presque toujours identique dans sa construction pour les composants.

site/hello.php

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * components/com_hello/hello.php
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
*/

// No direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
    $path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
    if (file_exists($path)) {
        require_once $path;
    } else {
        $controller = '';
    }
}

// Create the controller
$classname    = 'HelloController'.$controller;
$controller   = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getWord( 'task' ) );

// Redirect if set by the controller
$controller->redirect();

La première ligne est une vérification de sécurité.

JPATH_COMPONENT est le chemin absolu vers le composant en cours. Dans notre cas components/com_hello. Si vous avez besoin plus spécifiquement du la partie Front-Office ou Administration de votre composant vous pouvez utiliser JPATH_COMPONENT_SITE ou JPATH_COMPONENT_ADMINISTRATOR.

DS est le séparateur de répertoires de votre système : soit / ou \ en fonction du système d’exploitation utilisé. Ceci est automatiquement pris en compte par le framework et donc le développeur n’a pas besoin de se soucier de développer différentes versions pour chaque système d’opération. A chaque fois qu’il sera fait référence à des fichiers sur le serveur local il sera nécessaire d’utiliser la constante DS pour éviter tout problème.

Après le chargement du contrôleur de base nous vérifions si un contrôleur spécifique est requis. Dans ce composant le contrôleur de base est le seul mais nous conservons la vérification pour une utilisation future.

JRequest:getWord() récupère la valeur d’une variable dans l’URL ou les données envoyées par POST. Donc si notre URL est index.php?option=com_hello&controller=controller_name, alors nous pouvons récupérer le nom de notre contrôleur dans note composant en utilisant la commande : echo JRequest::getWord(‘controller’);

Maintenant nous avons notre contrôleur de base ‘HelloController’ dans com_hello/controller.php, et, si nécessaire, des contrôleurs additionnels comme ‘HelloControllerController1′ dans le fichier com_hello/controllers/controller1.php. En utilisant ce schéma de nommage il sera plus simple de gérer les modifications du composant par la suite : ‘{Nomcomposant}{Contrôleur}{NomContrôleur}’.

Après la création du contrôleur nous lui ajoutons les conditions d’éxécution de tâches comme défini dans l’URL : index.php?option=com_hello&task=unetache. Si aucune tâche n’est définie alors la tâche ‘display’ sera utilisée par défaut. Quand ‘display’ est utilisé la variable ‘view’ décidera de quoi afficher. D’autres commandes communes sont ‘save’, ‘edit’, ‘new’ …

Le contrôleur devra décider de rediriger la page, par exemple après une tâche ‘save’.

Le point d’entrée principal (hello.php) passe essentiellement le contrôle au contrôleur qui, lui, exécute les tâches spécifiées dans la requête.

Notez que nous n’utilisons pas de balise fermante : ?> La raison à cela est que nous n’aurons pas d’espace blanc non désiré dans le code de sortie. C’est la pratique utilisée par défaut depuis Joomla 1.5 et cela utilisée pour tous les fichiers utilisant uniquement php.

Créer le contrôleur

Notre composant n’a qu’une seule tâche a exécuter : Saluer le monde. Ainsi le composant sera très simple. Aucune manipulation de données n’est nécessaire. Il faut juste charger la bonne vue. Nous aurons une seule méthode dans notre contrôleur : display(). La plupart des fonctionnalités est construite dans la classe JController donc tout ce que nous avons à faire est d’appeler la méthode JController::display().

Le code du contrôleur de base site/controller.php est :

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
 */

// No direct access

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

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

/**
 * Hello World Component Controller
 *
 * @package    Joomla.Tutorials
 * @subpackage Components
 */
class HelloController extends JController
{
    /**
     * Method to display the view
     *
     * @access    public
     */
    function display()
    {
        parent::display();
    }

}

Le constructeur JController aura toujours une tâche display() et à moins que ce soit spécifié (en utilisant la méthode registerDefaultTask() ), il l’utilisera en tâche par défaut.

La méthode minimaliste display() n’est pas vraiment nécessaire étant donné quelle appelle le constructeur parent. Toutefois, c’est une bonne méthode visuelle pour indiquer ce qui ce passe dans le contrôleur.

La méthode Jcontroller::display() déterminera le nom de la vue et sa disposition à partir de la requète et chargera cet vue et sa disposition. Lorsque vous créez un lien menu dans votre composant le gestionnaire de menu permet à l’administrateur de sélectionner la vue  qu’il souhaite afficher par le lien menu et de spécifier sa disposition. Une vue se réfère généralement à la vue d’une certain groupe d’informations (par exemple une liste de voiture, une liste d’évènements, une voiture, un évènement). Une disposition est une façon d’organiser une vue.

Dans notre composant nous aurons une seule vue appelée hello et une seule disposition (default).

Créer la vue

La tâche de la vue est très simple : Elle récupère les données à afficher et les envoie dans le template. Les données sont envoyées au template en utilisant la méthode  JView::assignRef.

(Note: La clé (le premier argument) passé à la méthode assignRef ne peut être précédée par un underscore : $this->assignRef(‘_greeting’,$greeting). En faisant cela la méthode retournera un résultat faux et votre variable ne sera pas envoyée dans le template).

Le code de la vue du site : /views/hello/view.html.php :

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
*/

// no direct access

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

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

/**
 * HTML View class for the HelloWorld Component
 *
 * @package    HelloWorld
 */

class HelloViewHello extends JView
{
    function display($tpl = null)
    {
        $greeting = "Hello World!";
        $this->assignRef( 'greeting', $greeting );

        parent::display($tpl);
    }
}

Créer le template

Les templates Joomla sont des fichiers PHP qui sont utilisés pour disposer les données de la vue dans un ordre particulier (ainsi que son formatage). Les variables assignées par la méthode JView::assignRef peuvent être accédées à partir du template en utilisant $this->{nomdelapropriete} (voir le code ci-dessus pour un exemple).

Notre template est très simple : nous voulons afficher le message de bienvenue qui vient de la vue :
/views/hello/tmpl/default.php :

<?php

// No direct access

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

Emballer tout cela – Créer le fichier hello.xml

Il est possible d’installer un composant manuellement en copiant les fichiers par FTP et en modifiant les tables de la base de données. Mais il est plus efficace (et plus simple aussi) de créer un paquet d’installation qui permettra à l’installateur de Joomla! de faire ceci pour nous. Ce paquet contiendra plusieurs informations :

• Une description basique à propos du composant (son nom), et des information facultatives comme une description détaillée, un copyright, et les informations de licence.
• Une liste des fichiers qui doivent être copiés
• Un fichier PHP facultatif qui effectue des opérations d’installation/désinstallation supplémentaires
• Un fichier SQL facultatif qui contient des requètes de base de données à exécuter pendant l’installation ou la désinstallation

Le format du fichier XML hello.xml est le suivant :

<?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
 <name>Hello</name>
 <!-- The following elements are optional and free of formatting constraints -->
 <creationDate>2007-02-22</creationDate>
 <author>John Doe</author>
 <authorEmail>john.doe@example.org</authorEmail>
 <authorUrl>http://www.example.org</authorUrl>
 <copyright>Copyright Info</copyright>
 <license>License Info</license>
 <!--  The version string is recorded in the components table -->
 <version>1.01</version>
 <!-- The description is optional and defaults to the name -->
 <description>Description of the component ...</description>

 <!-- Site Main File Copy Section -->
 <!-- Note the folder attribute: This attribute describes the folder
      to copy FROM in the package to install therefore files copied
      in this section are copied from /site/ in the package -->
 <files folder="site">
  <filename>controller.php</filename>
  <filename>hello.php</filename>
  <filename>index.html</filename>
  <filename>views/index.html</filename>
  <filename>views/hello/index.html</filename>
  <filename>views/hello/view.html.php</filename>
  <filename>views/hello/tmpl/default.php</filename>
  <filename>views/hello/tmpl/index.html</filename>
 </files>

 <administration>
  <!-- Administration Menu Section -->
  <menu>Hello World!</menu>

  <!-- Administration Main File Copy Section -->
  <files folder="admin">
   <filename>hello.php</filename>
   <filename>index.html</filename>
  </files>

 </administration>
</install>

Mettre ce fichier xml (aussi apellé manifest) à la racine de votre paquet (l’installeur cherche le fichier à cet endroit pour effectuer les opérations nécessaires).
Ne pas inclure le fichier .xml lui même dans la liste des fichiers sous la balise <files>…

Vous devez avoir remarqué que la source manifest mentionnée dans le fichier XML fait référence à des fichiers dont nous n’avons pas encore parlé. Ces fichiers sont le index.html et les fichiers admin. Un fichier index.html est placé dans chaque répertoire afin d’éviter des problèmes de sécurité comme lire la liste des fichiers à un endroit donné. Si il n’y a pas de fichier index.html alors certains serveurs affiche la liste des fichiers contenus dans le répertoire. Ceci est souvent non souhaitable. Les fichiers index.html contiennent une seule ligne :

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

Ceci affichera simplement une page blanche.

Le fichier hello.php dans le répertoire admin est le point d’entrée de notre composant pour la partie administration Comme notre composant n’a pas de besoin d’administration (pas encore), ce fichier contiendra le même contenu que le fichier index.html.

Si vous avez suivi correctement le tutoriel vous pouvez visiter votre site à l’adresse monsite.com/index.php?option=com_hello et voir le résultat de votre travail.