Dans le tutoriel précédent, nous avons crée notre premier module de gestion d'un liste de courses, pour l'instant capable d'afficher des informations statiques dans un bloc. Ce que nous allons voir maintenant c'est :
Avant de commencer, nous allons donc reprendre les sources du précédent tutoriel à fin d'en étendre les fonctionnalités.
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.
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.
Le dernier paramètre correspond au nom du module qui va gérer ce type de contenu, en l'occurrence notre module courses<.kbd>.
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.
Ici, rien de nouveau par rapport au formulaire que nous avions définit pour le module statistique. Il est juste un peu plus complet mais fonctionne exactement sur le même principe.
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
Ici nous cherchons juste à nous assurer que les valeurs saisies sont numériques et positives. Maintenant notre formulaire est complet. Nous pouvons l'essayer en utilisant l'URL http://mon_site_drupal?q=/node/add/produit.
Nous avons maintenant un objet $node correctement renseigné par notre formulaire. Il ne nous reste donc plus qu'à coder sa sauvegarde en base de données. Pour ce faire, nous allons devoir implémenter quatre hooks, un par commande SQL.
Commençons par le plus simple : la lecture. Elle est prise en charge par le hook hook_load :
hook_load reçoit en paramètre un objet $node contenant déjà des informations extraites de la table node. Cela inclut le nid que nous utilisons dans notre requête pour lire en base nos valeurs supplémentaires. L'objet ainsi formé est renvoyé à Drupal qui l'agrégera à l'objet $node. Les fonctions de base de donnée utilisées ici sont les mêmes que celles abordées dans le précédent tutoriel.
Voyons maintenant comment insérer, mettre à jour ou encore détruire nos données supplémentaires en implémentant respectivement hook_insert, hook_update et hook_delete :
Notre nouveau type de contenu implémente maintenant tous les hooks nécessaires à son stockage en base de données. Nous pouvons maintenant créer un nouveau produit, saisir ses valeurs, le sauvegarder, le modifier, et le détruire.
Un des gros avantage de Drupal est l'abstraction de la couche base de données qu'il propose. Elle est certes simple mais très efficace. Et du point de vue du module, peu importe que l'on utilise PostrgeSQL ou MySQL, Drupal lui fournit un jeu de fonctions permettant d'oublier ce "détail".
La fonction db_query a pour rôle de lancer la requête et de renvoyer un curseur sur le résultat. Elle permet l'utilisation des motifs %d et %s comme la fonction PHP sprintf.
Notez que db_query ne va pas automatiquement insérer de guillemets autour des chaînes. C'est donc à vous de mettre des '%s'. En revanche, elle se charge de l'échappement des caractères spéciaux vous protégeant des injections de code SQL malicieux, ce qui n'est déjà pas si mal.
La fonction db_fetch_object va lire en base un enregistrement à la position courante du curseur (celui renvoyé par db_query) et transformer le résultat en un objet PHP. L'objet reçoit ainsi deux champs type et count contenant les résultats de la requête.
La fonction db_result est une version simplifiée de db_fetch_object qui est utile lorsque la requête ne renvoie qu'une seule valeur.
La première chose que l'on constate une fois que l'on a saisi et validé notre premier produit est que les informations affichées n'incluent ni la quantité, ni le seuil de rachat. Ne sont présentes que les données d'un node standard. Pour changer cela, nous allons implémenter un nouveau hook, hook_view, et une fonction de thème.
Notre première tâche est de préparer le node à l'affichage. C'est le rôle de la fonction node_prepare qui va appliquer les filtres d'entrée au corps et fabriquer le résumé (teaser).
Une fois le node préparé, nous vérifions dans quel contexte nous sommes appelé pour n'inclure nos informations supplémentaire que lorsque Drupal a besoin du node en entier (mode page) et pas seulement du résumé (mode teaser).
Si nous sommes bien en mode page, nous pouvons ajouter à l'objet $node des sections $node->content[]. Ces sections seront affichée par Drupal après le titre et le corps du node. Chacune d'entre elles est composée d'un contenu HTML (propriété #value) et d'un ordre d'apparition (propriété #weight).
Pour renseigner #value nous avons rajouté une petite finesse : l'utilisation d'une fonction de thème theme('courses_view', $node). Cela consiste à demander à Drupal d'habiller l'objet $node avec le thème courses_view. La fonction en interne va procéder de la manière suivante :
Une bonne pratique est donc de toujours fournir un thème par défaut en utilisant ce dernier cas de figure. Ainsi, Drupal pourra toujours trouver de quoi habiller notre node tout en laissant à vos utilisateurs la possibilité d'en changer le style. Là aussi c'est une bonne pratique à garder à l'esprit.
Pour des raisons de performances, ce type de fonction thème n'est pas cherché par Drupal de manière automatique. Il est donc nécessaire d'implémenter un hook supplémentaire, hook_theme, pour enregistrer notre fonction theme_produit_view dans les tablettes de Drupal.
Attention cependant, ce hook n'est lu qu'à l'activation du node. Si l'on veut pour tester avoir une prise en charge dynamique, il est nécessaire d'ajouter, par exemple juste avant l'implémentation ci-dessus, un appel à drupal_rebuild_theme_registry();. Mais pensez à enlever cette ligne lorsque vous avez fini de tester sous peine de plomber les performances.
Vous aurez sans doute remarqué que chaque node disposent, à la fin du résumé ou de la page, d'une série de liens qui offrent des actions qui lui sont propres. Ces liens sont définis grâce à l'implémentation de hook_view. Nous allons donc utiliser cette fonctionnalité pour ajouter à chaque node un lien vers notre future liste de courses.
Attention cependant, contrairement à tous les hooks que nous avons étudié jusqu'à maintenant, ce hook n'est pas spécifique au type produit. Il faut donc vérifier avant d'ajouter un lien que l'on est bien dans le contexte d'un node (et pas d'un commentaire), et que le type du node est bien produit.
Maintenant que nous avons notre lien vers la liste des courses, il ne nous reste plus qu'à la mettre en oeuvre.
Avant de rentrer dans le vif du sujet, arrêtons nous un peu sur la manière dont Drupal gère les URL. Ces dernières sont de la forme http://mon_site_drupal?q=chemin1/chemin2 ou http://mon_site_drupal/chemin1/chemin2 selon que le mode "URL Simplifié" est actif ou non. La chaîne chemin1/chemin2, appelée path, est associée par Drupal à une fonction, appelée callback. Lorsqu'il est exécutée, cette fonction renvoie à Drupal du code HTML qu'il va insérer dans la page. Cette association entre un path et une fonction callback est appelée un menu.
Chaque module a la possibilité de définir ses propres menus en implémentant hook_menu. C'est ce que nous allons utiliser pour afficher notre liste de courses :
Comme pour le hook_theme, hook_menu n'est appelé qu'à l'activation du module. En conséquence, comme avec hook_theme, pour tester, vous devrez placer avant l'implémentation un appel à menu_rebuild(), cela va vous permettre de reconstruire dynamiquement la table des menus à chaque requête. Mais là aussi, pensez à enlever cet appel lorsque vous avez achevé vos tests car les performances seraient catastrophiques.
Une fois le code ajouté allez à l'URL http://mon_site_drupal/?q=courses/liste_items et voyez le résultat. Notre texte s'affiche tranquillement au milieu de la page et le titre de la fenêtre du navigateur est bien Liste des courses.
courses_menu renvoie à Drupal un tableau prenant le path comme id et lui associe un tableau de définition du menu. Mettre le nom du module, courses comme premier élément du path est une convention permettant d'avoir des URL de la forme mon_module/mon_action.
A ce menu nous avons donné un titre (paramètre title) et si vous mettez à jour votre navigateur, vous devriez voir ce titre et le lien associer apparaître dans le bloc de navigation. C'est grâce au paramètre type qui renseigné à MENU_NORMAL_ITEM indique à Drupal de rendre le menu visible.
Enfin les paramètre access callback permet à n'importe quel utilisateur étant capable de voir un node, d'accéder à ce menu.
La fonction de callback quant à elle, commence par changer le titre de la page et poursuit par la construction du contenu HTML du corps qui sera renvoyé à Drupal.
Il ne nous reste maintenant plus qu'à mettre un véritable corps à notre callback pour obtenir enfin notre liste de courses
La fonction commence par deux lignes dont l'objectif est de demander à Drupal de prendre la feuille de style default.css qui se trouve dans le dossier du module, et de la lier à la page. Pour plus d'informations sur cette méthode, reportez vous à ce tutoriel. Cette feuille de style va juste nous servir à mettre en évidence les lignes de produits qui doivent être rachetés.
La requête SQL qui suit nous permet d'itérer sur la liste des nodes de type produit en y ajoutant les informations de la table node_produit. Nous aurions pu seulement récupérer ici le nid et utiliser la fonction node_load mais cette méthode est beaucoup plus rapide. Le reste du code n'est plus qu'un travail de mise en forme du contenu de l'objet $node en ligne d'un tableau, qui sert de retour à la fonction de call-back.
La dernière colonne du tableau contient des liens qui représentent les actions par produit : modifier et diminuer. La première est simplement un raccourcis sur l'édition du node, la seconde va nous permettre de diminuer la quantité restant de produit d'un simple click (voir chapitre suivant).
Notez l'utilisation de la fonction Drupal, l(…). Son rôle est de fabriquer un lien HTML à partir d'un texte et d'un chemin. Il est fortement conseillé de toujours utiliser cette fonction pour générer un lien et ainsi laisser Drupal en trouver la meilleur représentation URL.
Voyons maintenant comment câbler notre action diminuer.
L'action diminuer codée en lien dans la colonne action de notre tableau, s'attend à ce que Drupal sache reconnaître un path de la forme couses/diminuer/1234. 1234 représentant le nid de la ligne courante. Pour cela nous allons devoir créer un nouveau menu d'un genre un peu différent du précédent, c'est à dire capable de comprendre un paramètre (le nid) et ne devant pas s'afficher dans le bloc de navigation.
Mis à part son type, ce menu diffère dans son approche du path. En effet, vous aurez remarqué que le dernier paramètre est le symble %. Cela indique à drupal que n'importe quel élément peut satisfaire à ce troisième morceau de chemin. Dans notre cas, ce sera un chiffre représentant le nid.
Ce motif représente un paramètre qu'il est possible de transmettre à la fonction callback par la propriété #page arguments. Il s'agit d'un simple tableau contenant les indexes (débutant à 0) des parties variables du path (ici le morceau de rang 2).
Il ne nous reste maintenant plus qu'à écrire cette fonction de callback :
Le traitement effectué par cette fonction de callback consiste simplement à charger dans l'objet $node le node dont le nid est passé en paramètre. Ensuite nous décrémentons la quantité. Enfin nous sauvegardons l'objet en base de données.
Pour l'instant, notre bloc est resté avec ses valeurs statiques, il est grand temps de remplacer cela par des valeurs réelles. Pour se faire, rien de nouveau, nous allons utiliser ce que nous avons déjà fait avec la fonction qui liste les items et remplacer la fonction courses_contenu_block du précédent tutoriel avec ceci :
La seule chose intéressante dans ce code est le return NULL à la fin. L'idée est que si nous n'avons aucun produit en manque, nous tombons dans ce cas. Et si Drupal constate que le contenu d'un block est NULL, il n'affiche plus le bloc, titre compris. Cette approche nous permet de ne faire apparaître le bloc QUE lorsqu'il est nécessaire.
Voilà comment en relativement peu de code, il est possible de fabriquer de toute pièce un module prenant en charge un nouveau type de contenu. Il existe une autre méthodes permettant d'arriver au même résultat avec sûrement encore moins de travail, les module