3. Créer un fichier .module

Par convention, le fichier .module peut être considéré comme le fichier PHP principal d'un module. D'ailleurs, dans les versions antérieures à Drupal 7, le fichier .module ne devait pas être déclaré dans le fichier .info par l'intermédiaire de la directive files[]. Lorsque le module était activé, Drupal incluait le fichier .module automatiquement (il en allait de même si le dossier du module contenait un fichier .install).

Pour commencer, implémentons notre premier HOOK

Avant d'écrire le code qui nous permettra d'afficher "Bonjour le monde", nous allons commencer par implémenter une petite fonction qui ajoute une page d'aide dans la partie administrative du site. Cette fonction nous permettra de comprendre l'un des concepts majeur de la programmation Drupal : le hook.

Tout d'abord, voici le code complet de notre fonction :

function hello_world_help($path, $arg) {
  if ($path == 'admin/help#hello_world') {
    return t('A demonstration module.');
  }
}

Aussi curieux que cela puisse paraître, cette petite fonction ajoute une page d'aide à la partie administrative du site. Celle-ci affichera cette phrase laconique : "A demonstration module". Quant au chemin permettant d'accéder à cette page, il est créé par le simple fait que la fonction hello_world_help existe. Dans le cas présent, ce chemin est : http://.../admin/help/hello_world.

D'autre part, en implémentant cette fonction, vous ajoutez un raccourci à la page principale d'aide de la partie administrative du site. Ce nouveau raccourci intitullé Hello world, renvoit vers la page http://.../admin/help/hello_world.

Mais comment est-ce possible ?

Tout simplement, parce que la fonction hello_world_help implémente un hook.

Qu'est-ce qu'un hook ?

Un hook (crochet en français) est une fonction exécutée automatiquement par Drupal au moment opportun. Pour implémenter un hook, celui-ci doit être noté d'une manière très spécifique : nomdumodule_nomduhook().

Par exemple, pour que notre module Hello world implémente le hook intitulé hook_help(), nous devons écrire une fonction dont le nom est hello_world_help(). Ainsi, lorsque Drupal en aura besoin, toutes les instructions de cette fonction seront exécutées.

En réalité, pour chaque hook exécuté sur la plate-forme, Drupal exécute ce même hook sur tous les modules installés, activés et ayant implémenté ce hook. L'utilisation de hook par Drupal peut être comparé au principe de surcharge utilisé dans les langages orientés object (POO). L'avantage majeur de l'utilisation de hook, c'est qu'il permet d'ajouter des fonctionnalités à Drupal sans modifier le code interne du CMS.

Bien entendu, tous les hook ne doivent pas être implémentés de la même manières. En effet, ils peuvent recevoir des arguments ou éventuellement retourner une valeur...

Pour connaître les spécificités de chaque hook, il suffit de se rendre sur la page API reference du site Drupal.

Par exemple, pour connaître les spécificités du hook_help(), il suffit d'introduire "hook_help" dans le formulaire de droite dénommé Search Drupal 7 et de cliquer sur Search. Vous serez renvoyé vers une page d'assistance présentant la fonction hook_help() dans tous ses détails. C'est ainsi que vous découvrez qu'en appelant la fonction hook_help(), Drupal lui transmet deux paramètres ($path et $arg) dont les spéficités sont expliqués sur cette même page. De plus, il est précisé que Drupal attend une valeur de retour. Enfin, notons que ces pages de documentation contiennent généralement des commentaires qui peuvent se révéler précieux.

Ecrire une version complète du fichier .module

Nous allons maintenant intégrer notre fonction hello_world_help() dans une version complète du fichier hello_world.module :

/**
 *  @file
 *  A module exemplifying Drupal coding practices and APIs.
 *
 *  This module provides a page that displays Hello World.
 *  It illustrates coding standards, practices, and API use for Drupal 7.
 */

/**
 *  Implements hook_help()
 */
function hello_world_help($path, $arg) {
  if ($path == 'admin/help#hello_world') {
    return t('A demonstration module.');
  }
}

Cette version complète nous permet de présenter les conventions d'écriture adoptées par Drupal.

En effet, lorsque vous développez un module sous Drupal, il importe de respecter certaines règles d'écriture :

  • Dans les fichiers PHP et JavaScript, l'indentation se fait en utilisant deux espaces. Les tabulations ne sont jamais utilisées.
  • Pour éviter l'inclusion d'espaces blancs avant l'en-tête HTTP, les fichiers PHP commencent par l'instruction <?php, mais ils ne sont pas clôturés par l'instruction ?>.
  • Les blocs de commentaires utilisent le style Doxygen (/** */). Dans les fonctions, il est préférable d'introduire un commentaire à l'aide d'un double-slash (//). Le signe dièse (#) ne doit jamais être utilisé.
  • Il faut ajouter un espace de chaque côté d'un opérateur.
  • Il faut mettre un espace entre l'instruction créant une structure de contrôle et l'accolade ouvrant cette même structure.
  • Les noms de fonction doivent s'écrire avec des lettres minuscules et les mots doivent être séparés par des caractères de soulignement (underscrore). Pour les méthodes implémentées dans une classe, d'autres conventions d'écriture doivent être adoptées.
  • Les noms de variables doivent s'écrire avec des lettres minuscules et les mots doivent être séparés par des caractères de soulignement (underscrore). Pour les membres d'un objet, d'autres conventions d'écriture doivent être adoptées.

 

Une fois que vous avez modifié le fichier .module, il est possible que le hook implémenté ne soit pas pris en compte par votre plate-forme Drupal. Si votre code est correcte, cela peut être dû aux caches qui n'ont pas été mis à jour (ceci, même si vous n'avez pas activé la mise en cache). Pour résoudre ce problème, il suffit de vider les caches en vous rendant à la page performance accessible par le panneau de configuration situé dans la partie administrative du site. Vous pouvez également vider les caches manuellement en utilisant l'interface phpMyAdmin.