4. Créer une page Hello World

Maintenant, nous allons implémenter le code permettant d'afficher "Bonjour le monde !" dans une page de notre plate-forme.

Pour réaliser cette page, nous aurons besoin de créer deux fonctions dans le fichier hello_world.module. La première implémentera le hook_menu et la seconde fournira le contenu de notre nouvelle page.

Le code des deux fonctions

Concrètement, nous allons implémenter deux fonctions intitulées hello_world_menu() et _hello_world_first_page(). Elles seront ajoutées à notre fichier hello_world.module.

/**
 *  Implements hook_menu()
 */
function hello_world_menu() {
  $items = array();
$items['hello-world/first'] = array( 'title' => t('First page'), 'description' => t('First page for Hello World module.'), 'page callback' => '_hello_world_first_page', 'access callback' => TRUE, 'type' => MENU_NORMAL_ITEM, 'weight' => -10, );
return $items; } /** * Implements the function _hello_world_first_page() */ function _hello_world_first_page() { return '<p>' . t('Hello world !') . '</p>'; }

La fonction hello_world_menu

Créer une nouvelle page avec Drupal, c'est commencer par créer un chemin vers cette page.

Pour créer ce chemin, il suffit d'implémenter le hook_menu. En effet, c'est grâce à cette fonction que nous pourrons transmettre à Drupal le nom du chemin de notre nouvelle page et les propriétés que nous souhaitons attacher à cette page.

Tout d'abord, commençons par déclarer notre fonction que nous appelons hello_world_menu. Ce nom étant un composé du nom machine de notre module Hello world et du nom du hook.

function hello_world_menu() {
  $items = array();
$items['hello-world/first'] = array( 'title' => t('First page'), 'description' => t('First page for Hello World module.'), 'page callback' => '_hello_world_first_page', 'access callback' => TRUE, 'type' => MENU_NORMAL_ITEM, 'weight' => -10, );
return $items; }

Nous constatons que le hook_menu ne reçoit pas d'argument. Par contre, il retourne une variable de type array().

Dans notre exemple, nous utilisons la variable $items que nous initialisons comme tableau vide.

Ensuite, nous créons un tableau associatif dont la clé principale est le chemin d'accès vers notre page Hello world.

Dans l'exemple que je propose, j'ai choisi d'attribuer à ma page le chemin hello-world/first. Bien entendu, je suis libre du chemin que j'attribue à la page que je crée (j'aurais pu choisir hello-world, nimporte-quoi, hello/world/, hello-world/page/principale). Toutefois, pour éviter les conflits avec d'autres chemins du site, il est préférable de créer un chemin qui commence par le nom machine du module. Sauf que dans la construction des chemins de menu, le caractère de soulignement (underscore) doit être remplacé par un simple trait d'union.

Les "sous-clés" de ce tableau, sont les noms des propriétés attachés à la page Hello world et auxquelles nous souhaitons attribuer une valeur.

Sans entrer dans le détail de toutes les propriétés qui peuvent être associées à un chemin de menu, soulignons au passage l'importance de certaines d'entre elles.

Ainsi, la propriété 'title' permet d'attribuer un titre à l'item du menu et à la page associé à ce chemin. Il s'agit surtout d'attribuer une valeur par défaut qui pourra être modifié ultérieurement dans le menu à l'aide du panneau de configuration des menus ou dans le code générant la page avec, par exemple, la fonction drupal_set_title().

Soulignons que pour attribuer une valeur à la propriété 'title', j'ai utilisé une fonction particulière: t(). Il s'agit d'une fonction implémentée dans le cœur de Drupal. Elle doit être utilisée pour les textes qui s'affichent à l'écran et qui pourraient être traduit dans une autre langue.

En fait, lorsque la fonction t reçoit un texte en argument, elle commence par vérifier s'il existe une traduction dans la langue courante de la page affichée. Si une traduction existe, le texte traduit sera retourné par la fonction. Si aucune traduction n'a été trouvée, la fonction renvoit simplement le texte reçu en argument.

Lorsque vous développez du code dans l'environnement Drupal, il est préférable d'utiliser l'anglais comme langue par défaut. De plus, en utilisant l'anglais, vous n'êtes pas obligé de sauvegarder vos fichiers PHP dans un format d'encodage spécifique, tel que UTF-8(sans BOM).

La propriété 'description' associe une courte description de la page. Le texte de cette description est également renvoyé comme valeur à l'aide de la fonction t().

Très importante, la propriété 'page callback' associe le chemin du menu avec une fonction chargée de construire le contenu de la page Hello world. Dans notre exemple, cette fonction s'appelle _hello_world_first_page.

Il me semble inutile de préciser que si la fonction spécifiée dans la propriété 'page callback' n'existe pas, vous obtiendrez une erreur lorsque vous utiliserez le chemin de cet item.

La propriété 'access callback' détermine les droits d'accès à la page Hello world. Dans notre exemple, nous lui avons attribué la valeur TRUE parce que nous avons décidé que cette page serait accessible à tous.

Quant à la propriété 'type' elle définit le comportement de l'item dans le système des menus de Drupal. Dans notre exemple, nous avons opté pour la constante MENU_NORMAL_ITEM. Cette constante, définie par Drupal, permet d'insérer notre item de menu dans le menu par défaut de Drupal. En général, il s'agit du menu Navigation.

Enfin, la propriété 'weight' détermine la position de notre item dans le menu Navigation. Les valeurs négatives permettent de faire monter notre item dans la liste des items de menu et la valeurs positives le font descendre.

Pour davantage d'informations sur le hook_menu, vous pouvez vous rendre à la page suivante du site officiel de Drupal : function hook_menu.

La fonction _hello_world_first_page

Cette fonction n'implémentant pas de hook, son nom n'est pas soumis à une convention d'écriture rigoureuse. Sauf que, dans la pratique, nous ne pouvons pas faire n'importe quoi. Il ne faut jamais oublier que nous nous trouvons dans un environnement procédural et qu'il importe de prévenir d'éventuels redéclarations de nom de fonction. Il est donc conseillé d'adopter certaines règles d'écriture.

D'abord, il est préférable que le nom des fonctions commence par le nom machine du module. D'ailleurs, nous avons vu que cette manière de faire était particulièrement recommandée pour l'implémentation des hooks.

Ensuite, pour les fonctions du module qui n'implémentent pas un hook, il est conseillé de les faire commencer par un caractère de soulignement (underscrore).

C'est en respectant ces quelques règles d'écriture que j'ai choisi de nommer ma fonction _hello_world_first_page.

function _hello_world_first_page() {
  return '<p>' . t('Hello world !') . '</p>';
}

Comme nous l'avons vu ci-dessus, cette fonction est appelée lorsque le navigateur charge la page http://.../hello-world/first. Ceci, tout simplement, parce que le nom de cette fonction a été attribuée à la propriété 'page callback' de l'item de menu dont la clé est hello-world/first.

Dans notre module, la fonction _hello_world_first_page génère le contenu d'une page. Le code de cette page est envoyé à Drupal en tant que valeur retournée par la fonction. Il importe donc toujours que ce type de fonction retourne une valeur (même vide). Par contre, si cette fonction retourne une valeur non vide, celle-ci doit être écrite en respectant les recommandations HTML.

Voilà pourquoi notre fonction renvoit simplement la phrase Hello world ! entre des balises de type paragraphe.

Avant de tester le module !

Avant de tester le fonctionnement du module Hello world, n'oubliez pas de vider les caches. En effet, il faut savoir que Drupal range systématiquement les données permettant de construire les menus dans un cache spécifique. Dès lors, le tableau retourné par la fonction hello_world_menu ne sera pris en compte par Drupal que lorsqu'il reconstruira le cache des menus.