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.

Pré-requis

Les seuls pré-requis pour développer un module sont une bonne connaissance des concepts clés de Drupal (blocks, node, type de contenu, taxinomie, etc.), une relative maîtrise de PHP.

Armé de tout cela, nous allons commencer en douceur avec la création d'un module dont le seul but est de nous fournir un bloc avec du texte dedans, rien de plus. Ce module 'Liste des courses', sera ensuite étendu pour en faire un module complet de gestion de vos achats quotidien. Tant qu'à prendre un exemple, autant qu'il serve à quelque chose (quoi ? vous n'avez pas tous un intranet domestique sous Drupal ??? ). Et tout cela pour Drupal 6.x.

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 obtenir la liste des blocs disponibles et le contenu de chacun d'entre eux.

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 d'un bloc, le prototype se nomme hook_view:

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

Lorsque Drupal aura besoin d'obtenir la liste des blocs, il cherchera dans la liste de toutes les fonctions PHP disponibles, c'est-à-dire les fonctions contenues dans tous les modules activés, celles dont le nom commence par le nom d'un module et se termine par _block, le nom du hook.

La manière dont Drupal utilise un hook est assez simple. Pour rester sur notre exemple, lorsqu'il a besoin d'obtenir la liste des blocs, il va appeler tout les fonctions _block qu'il trouve, les unes après les autres, en leur passant en premier paramètre la chaîne list. Et réponse, chacune va donner un tableau contenant les noms et descriptions des blocs qu'elles prennent en charge.

Ensuite lorsque Drupal va devoir afficher un bloc en particulier, il effectue la même opération mais cette fois en passant en paramètre view suivi du nom du bloc.

Maintenant au delà du mode d'exécution des hooks de même type, chacun est spécifique tant par les paramètres qu'il reçoit que par les valeurs que Drupal s'attend à recevoir. Vous pouvez obtenir leur description dans la documentation de l'API Drupal.

Structure d'un module

Un module est donc un fournisseur d'implémentation de hooks. En conséquence, la majeure partie de son code va s'insérer dans les traitements de Drupal et étendre son 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 :

Fichier .info

Le fichier statistiques.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 :

package indique dans quelle catégorie le module doit être affiché. name, description sont des informations textuelles qui seront affiché dans le panneau d'administration des modules. name reprend le nom du module (qui est aussi le nom du dossier). version indique quant à lui la version du module. C'est d'ailleurs plus une norme qu'autre chose qui se lit "Module version 0.1 pour Drupal 6.x". Enfin core prévient Drupal que le module est seulement compatible avec sa version 6.x. Tout autre version de Drupal empêchera le module de s'activer.

Si nous avions eu besoin de définir une dépendance avec un autre module, nous aurions ajouté une clause de la forme dependencies[] = autre_module. Enfin, si vous désirez ajouter des commentaires, il suffit d'utiliser le symbole ; suivi du texte du commentaire.

Fichier .module

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 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 donc activer notre module, mais ne le faites pas tout de suite, nous avons encore quelque chose à rajouter.

Implémentation de hook_block

Il est maintenant temps d'implémenter notre premier hook. Comme nous l'avons vu plus haut, celui qui est responsable de la génération de bloc est hook_block. Il nous faut donc ajouter son implémentation à la suite, dans notre fichier statistiques.modules:

Le paramètre important de ce hook est $op. Lorsque Drupal a besoin de la liste des blocs disponible, il appelle cette fonction avec $op=='list'. Drupal s'attend alors à ce que la fonction renvoie un tableau associant un id (ici courses) à une définition de bloc. Cette définition est elle aussi un tableau associant une propriété du bloc à sa valeur. Cette organisation des données est un grand classique dans Drupal.

Ici nous renvoyons à Drupal un seul bloc ayant pour description (propriété info) affichage des statistiques. Notez l'utilisation de la fonction t(...) qui permet de prévoir une prise en charge ultérieure de la traduction du module. Pensez à utiliser systématiquement cette fonction pour tous les textes.

Vous pouvez dés maintenant voir le hook en action en allant sur l'URL http://mon_site_drupal?q=admin/build/block. Vous devriez alors le voir apparaître dans la liste des blocs désactivés.

Sélectionnez maintenant dans la liste une position pour votre bloc et sauvegardez l'ensemble. Il devrait apparaître à l'endroit désiré.

Paramétrage du bloc

Passons maintenant à la possibilité d'ajoute un formulaire de paramétrage pour notre bloc. Cela se passe toujours dans hook_bloc mais nous nous adressons cette fois aux opérations $op==configure et $op==save. La première fabrique un mini formulaire Drupal. La seconde sauvegarde le résultat du formulaire modifié par l'utilisateur.

Le formulaire est construit dans la variable $form dont la structure de stockage est la même que pour $blocks. C'est à dire un double tableau associatif, contenant la liste par id des champs. Puis par champ, la liste des propriétés et leurs valeurs.

La propriété #type détermine le type du champ (zone de texte,liste déroulante, etc). Ici nous choisissions un champ texte (textfield). La liste de complète des types et de leurs propriétés associées est disponible dans la documentation de Drupal.

Mais la propriété vraiment intéressante est #default_value. Elle définit la valeur que dois prendre le champ au moment de l'affichage du formulaire. Cette valeur est extraite des propriétés générales de Drupal par la fonction variable_get(...), par l'intermédiaire de la fonction courses_nombre_item_max(). En effet, Drupal met à disposition des modules un système de variables persistantes très simple à mettre en oeuvre. Passer par une fonction intermédiaire nous permet seulement de définir la valeur par défaut ((ici 5) de cette variable à un seul endroit et d'utiliser cette fonction partout où nous auront besoin de ce paramétrage.

La dernière propriété #title définit le titre du champ. Là aussi nous utilisons la fonction t(...) en prévision d'éventuelles traductions à venir.

Notre micro formulaire est maintenant prêt à être utilisé par Drupal. Vous pouvez le tester en retournant dans l'administration des blocs, en allant à la ligne que vous avez activée plus haut et en cliquant sur le lien configurer.

Lorsque vous aurez paramétré votre bloc, le fait de clicker sur le bouton Enregistrer le bloc provoquer un nouvel appel de notre hook, mais cette fois avec le paramètre save renvoyant les résultats du formulaire définit à l'étape précédente. Ces résultats sont contenus dans le tableau associatif $edit et notre seule tâche est d'utiliser la fonction Drupal permettant de stocker une variable persistante, variable_set(...);, en lui passant la valeur du champ courses_nombre_item_max.

La dernière étape est la génération du code HTML du bloc. C'est le rôle de l'opération $op==view qui utilise le paramètre du hook $delta.

hook_block permettant de créer autant de blocs que désiré, $delta contient l'ID du bloc à créer. Ici nous n'en avons qu'un mais autant prévoir l'avenir et effectuer tout de même le test. Ensuite, nous définissons une fois de plus un tableau associatif contenant deux propriétés, le titre du node (subject) et le contenu HTML du node (content).

Il est maintenant temps d'afficher notre bloc en sélectionnant une position dans la page d'administration. Une fois ce paramétrage sauvegardé (bouton enregistrer les blocs, le nouveau bloc devrait apparaître là où vous l'avez décidé.

Contenu du bloc

Maintenant que notre bloc est prêt, passons à l'affichage de son contenu. Pour cela nous allons remplacer la ligne content' => 'Un bloc vide'); par 'content' => statistiques_contenu()); et ajouter la fonction de rendu HTML de notre bloc. Bien évidemment, vu que nous n'avons pour l'instant pas de base de données contenant la liste réelle de nos courses, nous allons mettre dans ce bloc des items poétiques :

Voilà, rien de sorcier dans cette fonction, juste la création de code HTML que l'on renvoie à hook_block. Il ne reste maintenant plus qu'à apprécier le résultat.

Conclusion

Voilà, nous avons terminé notre premier module totalement fonctionnel en espérant que vous avoir montré à quel point, une fois quelques notions de base assimilées Drupal est facile à adapter à des besoins même très particuliers.

Comments