Hook_menu Drupal 7 : création de pages via un module

Dans la leçon précédente, nous avons vu comment afficher des informations depuis la base de données en utilisant l'API Drupal, notamment avec les hooks hook_block_info() et hook_block_view(). Dans cette leçon, nous allons afficher des pages, plus précisément utiliser le hook hook_menu pour connecter une page aux différentes parties de Drupal : menu, module de traduction, templates, etc.

Commençons par quelque chose de simple : créer une page affichant les titres des 10 dernières actualités avec leurs descriptions. Nous obtiendrons un petit fil d’actualité. Nous utiliserons le hook hook_menu(). Voici sa description, puis nous passerons à son utilisation.

hook_menu()

Ce hook définit un item de menu et retourne une page.

Ce hook, appelé dans un module, enregistre un chemin selon l'ordre dans lequel Drupal le traite. Les chemins peuvent être simplement enregistrés pour traitement ou placés dans un menu, par exemple dans le menu de navigation. Ces chemins et leurs informations associées sont appelés "menu router items". Ce hook est rarement appelé (par exemple lors de l’activation d’un module) et son résultat est mis en cache dans la base de données. Il faut donc souvent vider le cache lors de modifications dans ce hook.

hook_menu() retourne un tableau associatif dont les clés sont les chemins, et les valeurs un tableau associatif des propriétés de ces chemins (voir ci-dessous).

Chaque chemin enregistré inclut la page à retourner lorsqu’il est appelé. Par exemple, un module peut enregistrer le chemin 'abc/def'.

<?php   

function mymodule_menu() {
    $items['abc/def'] = array(
      'page callback' => 'mymodule_abc_view',
    );
    return $items;
  }
  function mymodule_abc_view($ghi = 0, $jkl = '') {
    // ...   
  }

?>

Quand le chemin 'abc/def' est appelé sans arguments supplémentaires dans l’URL, aucun argument ne sera passé à la fonction. Si l’URL est 'abc/def/1/Omsk', alors les arguments "1" et "Omsk" seront transmis. Ceci est utile pour créer des templates de pages dynamiques.

Les arguments supplémentaires peuvent être spécifiés en tableau associatif. Ce tableau peut contenir des valeurs complexes ou simples. Les arguments numériques sont accessibles via la fonction arg(0), arg(1), etc.

<?php   

function mymodule_menu() {
    $items['abc/def'] = array(
      'page callback' => 'mymodule_abc_view',
      'page arguments' => array(1, 'foo'),
    );
    return $items;
  }

?>

Dans ce cas, la fonction appelée recevra comme premier argument 'def' (arg(1)) et comme second argument la chaîne 'foo'. Pour plus de détails, voir : Documentation officielle de hook_menu().

Créons une page simple :

function sitemade_menu(){
    $items = array(); // initialisation du tableau des items de menu
     
    $items['page_example'] = array(  // ajout d'une page au chemin 'page_example'
      'title' => 'Exemple de page', // titre de la page
      'description' => 'Page simple', // description de la page
      'page callback' => '_page_example', // fonction retournant le contenu de la page
      'access callback' => TRUE, // accès autorisé à tous
      'expanded' => TRUE,
  );    
     
    return $items; // retour du tableau des pages
}
 
 
function _page_example($content = NULL) {
    $content = ''; // initialisation du contenu
    $query = db_select('node_revision', 'n'); // sélection de la table node_revision contenant les versions des nœuds
    $query->innerJoin('field_revision_body', 'b', 'b.revision_id = n.vid'); // jointure avec field_revision_body contenant le body
    $query->innerJoin('node', 'd', 'n.nid=d.nid'); // jointure avec node contenant le titre
    $query->fields('n', array('title'));
    $query->fields('b', array('body_value'));
    $query->condition('d.type', 'news'); // filtrer par type de contenu 'news'
    $query->orderBy('n.timestamp', 'DESC'); // tri par date décroissante
    $query->range(0, 10); // limiter aux 10 derniers
    $result = $query->execute(); // exécution de la requête
    while($nodes = $result->fetch()){ // traitement des résultats
        $content .= '<h3>' . $nodes->title . '</h3>'; // affichage du titre
        $content .= $nodes->body_value; // affichage du body
    }
 
    return $content; // retour du contenu
}

On peut aussi utiliser la propriété type du hook pour placer la page dans différents menus, comme le menu admin ou le menu principal.

Exemple :

function sitemade_menu(){
    $items = array(); // initialisation du tableau des items de menu
     
    $items['page_example'] = array(  
      'title' => 'Exemple de page', 
      'description' => 'Page simple', 
      'page callback' => '_page_example', 
      'access callback' => TRUE, 
      'expanded' => TRUE,
      'type' => MENU_NORMAL_ITEM,
      'menu_name' => 'main-menu',
  );    
    return $items;
}

Après avoir vidé le cache, un lien vers cette page apparaîtra dans le menu principal.

On peut aussi ajouter des pages accessibles uniquement via l’admin Drupal :

function sitemade_menu(){
    $items = array();    
    $items['admin/config/content/page_example'] = array(
      'title' => 'Exemple de page', 
      'description' => 'Page simple', 
      'page callback' => '_page_example', 
      'access arguments' => array('administer site configuration'), // droits admin
  );    
    return $items;
}

Cette page sera accessible uniquement aux administrateurs et un lien apparaîtra dans l’interface admin :

La présence du lien dans l’admin est automatique quand on utilise un chemin sous admin/config/content/*. Par exemple, si vous utilisez admin/config/people/*, le lien apparaîtra dans la section "Utilisateurs". Vous pouvez remplacer le dernier segment par le nom que vous voulez (ici, 'page_example').

Maintenant, nous savons créer des blocs et des pages. Ces hooks sont essentiels pour afficher du contenu et seront souvent utilisés dans vos modules.

Dans la prochaine leçon, nous étudierons hook_perm() pour créer des permissions personnalisées pour les utilisateurs.