hook_menu Drupal 7 het aanmaken van pagina’s via een module

In de vorige les hebben we bekeken hoe we informatie uit de database kunnen weergeven met behulp van de Drupal API, namelijk via de hooks hook_block_info() en hook_block_view(). In deze les gaan we pagina’s weergeven, of preciezer gezegd, met behulp van de hook hook_menu een pagina koppelen aan andere delen van Drupal: menu’s, de vertaalmodule, templates enzovoort.

We beginnen eenvoudig door een pagina te maken die de titels en beschrijvingen van de laatste 10 nieuwsberichten toont. Zo krijgen we een kleine nieuwsfeed. Hiervoor gebruiken we de hook hook_menu(). Hieronder volgt de beschrijving ervan, waarna we deze in de praktijk zullen toepassen.

hook_menu()

Definieert een menu-item en retourneert een pagina.

Deze hook, die in een module wordt aangeroepen, registreert een pad in de volgorde waarin Drupal het verwerkt. Paden kunnen alleen worden geregistreerd voor verwerking of ze kunnen in menu’s worden opgenomen, bijvoorbeeld in het navigatiemenu. De paden en de bijbehorende informatie worden menu router items genoemd. Deze hook wordt zelden aangeroepen (bijvoorbeeld wanneer een module wordt ingeschakeld) en het resultaat wordt in de database gecachet. Daarom moet de cache telkens worden geleegd wanneer je de hook in de module aanpast.

hook_menu() retourneert een associatieve array, waarvan de sleutels de paden definiëren en de waarden een associatieve array zijn met eigenschappen van elk pad (zoals hieronder beschreven).

De definitie voor elk pad bevat de pagina die wordt weergegeven wanneer het geregistreerde pad wordt opgevraagd. Als er geen andere paden overeenkomen met de gevraagde URL, wordt de pagina door deze hook geretourneerd. Bijvoorbeeld, jouw module kan het pad ‘abc/def’ registreren.

<?php   

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

?>

Wanneer het pad ‘abc/def’ wordt opgevraagd en er niets extra’s aan de URL is toegevoegd, zullen er geen extra argumenten worden doorgegeven. Wanneer echter het pad ‘abc/def/1/Omsk’ wordt opgevraagd, zullen de argumenten “1” en “Omsk” naar de pagina worden doorgegeven. Dit zal ons later goed van pas komen wanneer we paginatemplates gaan maken.

Extra argumenten in het pad kunnen worden gedefinieerd als een associatieve array. Deze lijst van argumenten kan zowel complexe waarden als eenvoudige numerieke waarden bevatten. Wanneer getallen worden gebruikt en de callback-functie (de functie die de pagina retourneert) wordt aangeroepen, zal het overeenkomstige padgedeelte worden vervangen door dat getal. Bijvoorbeeld, het eerste argument kan worden opgevraagd met de functie arg(0), het tweede argument met arg(1), enzovoort.

<?php   

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

?>

Wanneer het pad ‘abc/def’ wordt opgevraagd, zal de geretourneerde pagina ‘def’ als eerste argument en altijd ‘foo’ als tweede argument ontvangen. De volledige beschrijving van de hook is te vinden op deze pagina: http://api.drupal.org/api/drupal/modules--system--system.api.php/functio...

Laten we nu een eenvoudige pagina maken:

function sitemade_menu(){
    $items = array(); // initialiseer onze lijst van menu-items
     
    $items['page_example'] = array(  // voeg een pagina toe met het pad 'page_example'
      'title' => 'Voorbeeldpagina', // paginatitel
      'description' => 'Een gewone pagina', // paginabeschrijving
      'page callback' => '_page_example', // functie die de inhoud van de pagina retourneert
      'access callback' => TRUE, // geef iedereen toegang tot deze pagina
      'expanded' => TRUE,
  );    
     
    return $items; // retourneer de lijst van pagina’s
}
 
function _page_example($content = NULL) {
    $content = ''; // initialiseer lege inhoudsvariabele
    $query = db_select('node_revision', 'n'); // selecteer de tabel node_revision met de huidige revisie van de node
    $query->innerJoin('field_revision_body', 'b', 'b.revision_id = n.vid'); // voeg de tabel field_revision_body toe waarin de body zich bevindt
    $query->innerJoin('node', 'd', 'n.nid=d.nid'); // voeg de tabel node toe waarin de titel van de node zich bevindt
    $query->fields('n', array('title'), array('nid'), array('vid')); // selecteer velden
    $query->fields('b', array('body_value'));
    $query->condition('d.type', 'news'); // beperk tot content type “news”
    $query->orderBy('n.timestamp', 'DESC'); // sorteer zodat de nieuwste nieuwsberichten eerst komen
    $query->range(0, 10); // selecteer slechts de laatste 10
    $result = $query->execute(); // voer de query uit
    while($nodes = $result->fetch()){ // verwerk de resultaten
        $content .= '<h3>' . $nodes->title . '</h3>'; // toon de titel
        $content .= $nodes->body_value; // toon de body
    }
 
    return $content; // retourneer de inhoud
}

We kunnen ook de eigenschap type van de hook gebruiken om de pagina in verschillende menu’s te plaatsen, bijvoorbeeld in het beheermenu of in het hoofdmenu (main menu).

Laten we dit doen:

function sitemade_menu(){
    $items = array(); // initialiseer onze lijst van menu-items
     
    $items['page_example'] = array(  // voeg een pagina toe met het pad 'page_example'
      'title' => 'Voorbeeldpagina', // paginatitel
      'description' => 'Een gewone pagina', // paginabeschrijving
      'page callback' => '_page_example', // functie die de inhoud van de pagina retourneert
      'access callback' => TRUE, // geef iedereen toegang
      'expanded' => TRUE,
      'type' => MENU_NORMAL_ITEM,
      'menu_name' => 'main-menu',
  );    
    return $items; // retourneer de lijst van pagina’s
}

Na het vernieuwen van de cache verschijnt er nu een link naar deze pagina in het menu.

Naast gewone menu-items kun je een pagina ook zichtbaar maken in de Drupal-beheeromgeving:

function sitemade_menu(){
    $items = array(); // initialiseer onze lijst van menu-items    
    $items['admin/config/content/page_example'] = array(  // voeg een pagina toe met het pad 'admin/config/content/page_example'
      'title' => 'Voorbeeldpagina', // paginatitel
      'description' => 'Een gewone pagina', // beschrijving
      'page callback' => '_page_example', // functie die de inhoud van de pagina retourneert
      'access arguments' => array('administer site configuration'), // geef enkel toegang aan de beheerder
  );    
    return $items; // retourneer de lijst van pagina’s
}

Nu wordt onze pagina alleen voor de beheerder weergegeven en is de link naar deze pagina te vinden in de beheerdersomgeving:

De link verschijnt in het beheermenu omdat Drupal automatisch een link toevoegt voor paden die beginnen met admin/config/content/*. Als we in plaats daarvan het pad admin/config/people/* gebruiken, zal de link verschijnen in het blok “Gebruikers”. (In plaats van het sterretje kun je een eigen naam gebruiken — in ons geval is dat page_example.)

We kunnen nu zowel blokken als pagina’s maken — dit zijn de belangrijkste hooks voor het weergeven van content, en je zult ze vaak in je modules tegenkomen.

In de volgende les bekijken we hook_perm(), om nieuwe gebruikersrechten aan te maken.