Une des grandes forces de Drupal réside en son architecture à base de modules. Que ce soit pour la gestion des blogs ou celle d’un forum, chaque fonction fondamentale est en réalité un simple module interagissant avec le cœur de Drupal. Et si les modules fournis en standard ne suffisent pas, des centaines d’autres sont disponibles couvrant à peu prés tous les usages.

Mais malgré cette richesse, il arrive parfois que l’on ne trouve pas LE module « qui va bien ». Alors pourquoi ne pas le fabriquer soi-même et ainsi découvrir à quel point Drupal s'adapte facilement à des besoins spécifiques.

Ce gros tuto est encore en béta test

Où allons nous ?

Les prérequis pour développer un module sont évidemment une bonne connaissance des concepts clés de Drupal (node, type de contenu, taxonomy, etc.), une relative maîtrise de PHP et quelques bases en SQL. Armé de tout cela, nous allons dans ce tutoriel chercher à construire un module permettant de gérer une simple liste de courses. Il s'agira en quelque sorte de la version moderne du tableau sur le réfrigérateur, amélioré d'une petite gestion des réserves. Le module permettra :

• L'enregistrement, la modification et la suppression d'un produit. Un produit étant défini par son nom, sa quantité en réserve et la valeur seuil devant déclencher son rachat.
• L'affichage de la liste des produits. Chaque produit devant être racheté sera surligné. Sur chaque ligne, seront disposées deux actions, l'une permettant de le modifier, l'autre de décrémenter la quantité de produit restant d'une unité.

Des modules et des hooks

Avant de poursuivre, il est important de comprendre ce qu'est réellement un module. Un module Drupal est un bout de code PHP que l'on peut activer ou désactiver, et qui implémente des "hooks".

Un hook (en français, "Crochet") est un prototype de fonction dédié à une tâche spécifique, comme par exemple mettre en forme le contenu d'un node avant affichage. Chaque module peut ainsi implémenter ce hook sous la forme d'une fonction ayant des paramètres calqués sur ceux du prototype. Dans le cas de la mise en forme, le prototype se nomme hook_view:

Ainsi un module désirant implémenter ce hook, devra comporter le code suivant :

Lorsque Drupal aura besoin de mettre en forme un node, il cherchera dans la liste de toutes les fonctions PHP disponibles, c'est-à-dire les fonctions contenues dans tous les modules activés, thèmes compris, celles dont le nom commence par le nom d'un module et se termine par _view, le nom du hook.

Ensuite, Drupal va appeler les fonctions les unes après les autres et chacune d'entre elles va modifier l'objet $node passé en paramètre.

Le hook hook_view est défini et utilisé par le module modules/node.module fournis en standard. Nous comprenons ainsi que tous les modules peuvent proposer leur propre hook pour permettre à d'autres modules de prendre en charge un traitement spécifique. Pour avoir la liste des hooks fournis par un module, il faut se reporter à sa documentation. Dans le cas spécifique des modules fournis en standard dans Drupal (node, book, etc), vous trouverez leur description dans la documentation de l'API Drupal. Bien l'étudier est important car chaque hook a son propre fonctionnement. Certains s'attendent à ce que le contenu de l'objet passé en paramètre soit modifié, d'autres qu'un tableau soit renvoyé par la fonction, etc.

Structure d'un module

Un module est donc un fournisseur d'implémentations de hooks. En conséquence, la majeure partie de son code va s'insérer dans les traitements de Drupal et en étendre le comportement. Maintenant de manière plus prosaïque, un module est simplement un dossier qui contient au minimum deux fichiers.

Ce dossier doit porter le nom du module et doit être placé dans l'arborescence de Drupal, à un endroit qui soit approprié pour que ce dernier puisse le voir. Techniquement il est possible de les mettre dans modules/ mais vous seriez vite embêtés lors d'un changement de version. Il est donc préconisé de mettre cela dans un dossier sites/all/modules/mes_modules que vous créerez si nécessaire. Ainsi lorsque vous changez de version, il suffit de déplacer le dossier sites à sa place dans la nouvelle arborescence.

Dans ce dossier mes_modules, vous allez donc créer le sous-dossier du module lui-même, dans notre cas courses. A l'intérieur de celui-ci, vous devez avoir au minimum deux fichiers, portant le même nom de base que le dossier parent : courses.info et courses.module. Ce qui nous donne l'arborescence suivante :

Le fichier courses.info est un simple fichier texte contenant des informations sur le module comme son nom, sa description, la version de Drupal avec lequel il est compatible, etc. Ce qui nous donne pour notre exemple, le contenu suivant :

Le second fichier est le code PHP du module. C'est lui qui va héberger les hooks que nous souhaitons implémenter. Pour l'instant, nous allons faire simple et n'en mettre aucun. Notre fichier va donc contenir une simple balise de démarrage de code PHP :

Voilà, nous avons maintenant un module aussi simple qu'inutile, que Drupal est cependant capable de voir et d'activer. Pour s'en convaincre, il suffit d'aller faire un tour en http://mon_site_drupal/?q=/admin/build/modules pour le voir, comme sur l'illustration, apparaître dans la liste. Vous constatez que les informations affichées sont les champs name et description de notre fichier courses.info.

A ce stade nous pourrions déjà activer notre module, mais ne le faites pas tout de suite, nous avons encore quelque chose à rajouter.

Installation

Notre module courses a pour finalité de pouvoir saisir des produits et de les présenter sous la forme d'une liste. Nous pourrions pour cela utiliser un type de contenu simple comme story mais cette structure de stockage serait trop limitée car nous avons des informations plus précises à saisir que les seuls titre et corps. Il nous faut en effet spécifier le nombre de produits restants et le nombre minimum à avoir en réserve pour pouvoir générer notre liste de courses. Nous allons donc créer un nouveau type de node, produit, en cherchant à étendre le type de node simple.

Drupal stocke les données de base d'un node (titre, corps, etc.) dans la table node dont la clef primaire est le champ nid. Ce sont les valeurs de ce champ que vous retrouvez dans l'URL d'un node, sous la forme http://mon_site_drupal?q=/node/1234. Elle dispose aussi d'un champ type de type texte identifie le type du contenu. Dans notre cas ce type prendra la valeur produit.

Mais pour stocker nos informations supplémentaires, nous allons devoir créer une nouvelle table, traditionnellement nommée node_produit, contenant un champ quantité pour la quantité restante du produit et un champ seuil pour la valeur minimum à conserver en réserve. En outre elle disposera, elle aussi, d'un champ nid. Les informations sur un produit donné seront donc réparties sur les champs des deux tables à la fois (node et node_produit)reliées entre-elles par le même nid.

Du coup, pour obtenir toutes les informations disponibles sur un node de type produit, nous pouvons formuler la requête suivante :

Alors nous pourrions évidemment créer cette nouvelle table à la main mais ce serait bien peu pratique lorsque viendra le moment de redistribuer ce module. La bonne pratique est donc de déléguer ce travail à Drupal lors de l'activation du module. De la même manière, nous allons lui indiquer comment la supprimer, lorsque le module est désactivé puis désinstallé.

Pour ce faire, il nous faut rajouter un troisième fichier à notre dossier module : courses.install qui va contenir deux hooks. Le premier, hook_install, est invoqué lors de la première activation du module (installation). Le second, hook_uninstall, est quant à lui invoqué lors de la désinstallation du module.

Le code n'a rien de compliqué mais quelques points cependant méritent éclaircissement.

Tout d'abord, nous distinguons deux cas qui correspondent aux deux bases de données prises en charge par Drupal : mySQL et PostgreSQL. En effet, si les bases de données sont à peu près équivalentes s'agissant des requêtes INSERT,DELETE,UPDATE et SELECT, c'est un peu moins le cas pour les commandes CREATE et ALTER.

Ensuite concernant l'exécution des requêtes SQL, nous devons à tout prix éviter d'utiliser les fonctions base de données de PHP au profit de celles fournies par Drupal. En effet ces dernières présentent l'avantage de faire abstraction de la base de données sous-jacente.

Dans le cas spécifique de l'installation et de la désinstallation, nous utilisons update_sql mais pour le reste du code elle sera remplacée par db_query. Ces deux fonctions sont pratiquement identiques à la différence près qu'update_sql fournit plus d'informations sur le déroulement de la requête. Informations qui seront utilisées par l'assistant d'installation et de mise à jour de Drupal.

Dernier point : les accolades utilisées pour encadrer le nom des tables. Elles ne sont pas nécessaires mais permettent à Drupal certaines opérations de préparation des requêtes. C'est donc juste une bonne habitude à prendre.

Maintenant que notre installation est finalisée, il ne nous reste plus qu'à activer notre module dans le panneau d'administration de Drupal : http://mon_site_drupal?q=/admin/build/modules. Une fois cette opération achevée, vous pouvez vérifier à l'aide de votre explorateur de base de données préféré que la table node_produit a bel et bien été créée. Si vous désactivez et réactivez votre module, notez que le code d'installation n'est pas ré-exécuté. En effet, il vous faut d'abord désinstaller le module, pour que le hook courses_uninstall soit appelé et détruise la table. Ensuite, si vous réactivez à nouveau le module, la table sera recréée.

Type de contenu

Notre base est prête, notre module activé et pourtant si nous allons sur l'URL http://mon_site_drupal/?q=node/add, notre produit n'apparaît pas. En effet, il faut implémenter deux hooks supplémentaires dans courses.module pour indiquer à Drupal qu'un nouveau type de node est à prendre en charge. Le premier hook, hook_node_info, va décrire le nouveau type de node :

Ce hook permet de renvoyer à Drupal une liste de nouveaux types de contenu. Ici nous n'en indiquons qu'un seul, produit, avec sa description et son nom usuel. L'identifiant produit sera utilisé dans la colonne type de la table node comme vu au chapitre précédent. Notez enfin l'utilisation de la fonction t(...) qui permet à Drupal de prendre en charge l'affichage d'une phrase en plusieurs langues. Pensez à utiliser systématiquement cette fonction pour tous les textes.

Le dernier paramètre correspond au nom du module qui va gérer ce type de contenu, en l'occurrence notre module courses<.kbd>.

Formulaire de saisie

Une dernière étape est nécessaire à l'apparition dans la liste de notre nouveau type de contenu : mettre en place le formulaire de saisie. Mais avant cela, il est important de bien comprendre comment Drupal fait vivre un node.

Un node est représenté dans le code de Drupal par l'objet $node. A chaque étape du cycle de vie du node, différents hooks viennent enrichir cet objet jusqu'à y ajouter le code HTML qui sera inséré dans la page. C'est ainsi que dans le template node.tpl.php, l'affichage du titre passe par une référence à $node->title.

Il existe une relation étroite entre l'objet $node et sa représentation en base de donnée. Si le node existe déjà, Drupal transfère les valeurs correspondantes de la table node vers les champs de l'objet $node. Les identifiants de chaque colonne deviennent ainsi les noms d'attributs de l'objet. Lorsque le node n'existe pas encore, Drupal crée simplement un objet vide. C'est donc soit l'objet vide, soit l'objet chargé des valeurs en base, que nous allons récupérer dans le hook qui va créer notre formulaire, hook_form.

Ce hook est chargé de créer le formulaire mais aussi de l'initialiser avec les valeurs de l'objet $node. Ce formulaire sera soit utilisé sur un objet vide ou soit sur contenant les données d'un contenu existant.

Un formulaire Drupal est tableau $form dont chaque entrée correspond à la définition d'un des champs du formulaire ($form['champ']=...).

La définition du champ en elle-même est tableau associant une propriété (#title, #required, etc) à sa valeur. La proprété #type détermine le type du champ (case à cocher, zone de saisie, etc). La liste de ces types et de leurs propriétés associées est disponible dans la documentation de Drupal.

La propriété vraiment intéressante ici est #default_value, car c'est elle qui va permettre d'extraire de $node, les valeurs que le formulaire doit permettre de modifier. Lorsque l'utilisateur validera le formulaire, Drupal se chargera de réintégrer automatiquement les valeurs saisies dans l'objet $node. C'est pour cela que l'identifiant du champ est le même que celui de l'attribut correspondant dans $node ($form['quantite'] et $node->quantite).

Comme nous l'avons vu plus haut, l'objet $node est vide à sa création. Si nous l'utilisons tel quel, les champs quantité et seuil seront vides (et non égal à 0). Il est donc nécessaire d'implémenter un nouveau hook, hook_prepare, qui a pour rôle de préparer l'objet $node avant utilisation dans le formulaire.

Grâce à cette fonction, nous initialisons notre objet $node avec les bonnes valeurs par défaut. De la même manière nous pouvons valider ce que renvoie le formulaire en implémentant cette fois hook_validate