hook_menu Drupal 7 — creazione di pagine tramite un modulo

Nella lezione precedente abbiamo visto come visualizzare le informazioni dal database utilizzando le API di Drupal, in particolare con gli hook hook_block_info() e hook_block_view(). In questa lezione mostreremo come visualizzare pagine, o più precisamente, come collegare una pagina ad altre parti di Drupal (menu, modulo di traduzione, template, ecc.) utilizzando l’hook hook_menu.

Cominciamo con qualcosa di semplice: collegheremo una pagina che mostra i titoli e le descrizioni delle ultime 10 notizie. Otterremo così un piccolo feed di notizie. Useremo l’hook hook_menu(). Di seguito ne trovi la descrizione, e dopo la descrizione inizieremo a usarlo.

hook_menu()

Definisce una voce di menu e restituisce una pagina.

Questo hook, chiamato all’interno di un modulo, registra un percorso nell’ordine in cui sarà gestito da Drupal. I percorsi possono essere registrati solo per la gestione, oppure possono essere posizionati in un menu, come ad esempio nel menu di navigazione. I percorsi e le informazioni a essi associate vengono chiamati “menu router item”. Questo hook viene richiamato raramente (ad esempio quando si abilita un modulo) e il suo risultato viene memorizzato nella cache del database. Perciò è necessario svuotare spesso la cache ogni volta che si modifica l’hook nel modulo.

hook_menu() restituisce un array associativo, le cui chiavi definiscono i percorsi e i cui valori sono array associativi con le proprietà di ciascun percorso (le proprietà sono descritte più sotto).

La definizione di ciascun percorso include la pagina restituita, che viene collegata quando la pagina registrata viene richiesta. Se non ci sono altri percorsi che devono rispondere all’URL, l’hook restituisce la pagina. Ad esempio, il tuo modulo può registrare un percorso “abc/def”.

<?php   

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

?>

Quando viene richiesto il percorso “abc/def” e non ci sono altri elementi nell’URL, non verranno passati argomenti aggiuntivi. Quando invece viene richiesto il percorso “abc/def/1/Omsk”, alla pagina verranno passati gli argomenti “1” e “Omsk”. Questo ci sarà molto utile quando creeremo i template delle pagine.

Gli argomenti aggiuntivi del percorso possono essere definiti come array associativi. Questo elenco può contenere sia valori complessi che numerici. Quando vengono utilizzati numeri e viene chiamata la funzione di callback (la funzione che restituisce la pagina), il corrispondente percorso del modulo verrà sostituito dal numero. Ad esempio, il primo argomento può essere recuperato con la funzione arg(0), il secondo con arg(1), e così via.

<?php   

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

?>

Quando viene richiesto il percorso “abc/def”, la pagina restituita riceverà “def” come primo argomento e sempre “foo” come secondo argomento. La descrizione completa dell’hook è disponibile qui: http://api.drupal.org/api/drupal/modules--system--system.api.php/function/hook_menu/7

Creiamo ora una semplice pagina:

function sitemade_menu(){
    $items = array(); // inizializziamo l’array delle nostre voci di menu
     
    $items['page_example'] = array(  // aggiungiamo la pagina al percorso 'page_example'
      'title' => 'Esempio di pagina', // titolo della pagina
      'description' => 'Pagina semplice', // descrizione della pagina
      'page callback' => '_page_example', // funzione che restituisce il contenuto della pagina
      'access callback' => TRUE, // permettiamo a tutti di visualizzare la pagina
      'expanded' => TRUE,
  );    
     
    return $items; // restituiamo l’elenco delle pagine
}
 
function _page_example($content = NULL) {
    $content = ''; // inizializziamo la variabile del contenuto vuoto
    $query = db_select('node_revision', 'n'); // selezioniamo la tabella node_revision che contiene la revisione corrente
    $query->innerJoin('field_revision_body', 'b', 'b.revision_id = n.vid'); // uniamo la tabella field_revision_body che contiene il body
    $query->innerJoin('node', 'd', 'n.nid=d.nid'); // uniamo la tabella node che contiene il titolo del nodo
    $query->fields('n', array('title'), array('nid'), array('vid')); // selezioniamo i campi
    $query->fields('b', array('body_value'));
    $query->condition('d.type', 'news'); // imponiamo una condizione sul tipo di contenuto
    $query->orderBy('n.timestamp', 'DESC'); // ordiniamo le notizie, dalle più recenti
    $query->range(0, 10); // selezioniamo solo le ultime 10
    $result = $query->execute(); // eseguiamo la query nel database
    while($nodes = $result->fetch()){ // elaboriamo i risultati
        $content .= '<h3>' . $nodes->title . '</h3>'; // visualizziamo il titolo
        $content .= $nodes->body_value; // visualizziamo il body
    }
 
    return $content; // restituiamo il contenuto
}

Possiamo anche utilizzare la proprietà type dell’hook per posizionare la pagina in diversi menu, ad esempio nel menu principale o nell’area di amministrazione.

Facciamolo:

function sitemade_menu(){
    $items = array(); // inizializziamo l’array delle nostre voci di menu
     
    $items['page_example'] = array(  // aggiungiamo la pagina al percorso 'page_example'
      'title' => 'Esempio di pagina', // titolo della pagina
      'description' => 'Pagina semplice', // descrizione della pagina
      'page callback' => '_page_example', // funzione che restituisce il contenuto della pagina
      'access callback' => TRUE, // permettiamo a tutti di visualizzare la pagina
      'expanded' => TRUE,
      'type' => MENU_NORMAL_ITEM,
      'menu_name' => 'main-menu',
  );    
    return $items; // restituiamo l’elenco delle pagine
}

Aggiorniamo la cache e ora apparirà un link nel menu che porta a questa pagina.

Oltre ai normali elementi di menu, è possibile aggiungere la visualizzazione della pagina anche nell’area di amministrazione di Drupal:

function sitemade_menu(){
    $items = array(); // inizializziamo l’array delle nostre voci di menu    
    $items['admin/config/content/page_example'] = array(  // aggiungiamo la pagina al percorso 'admin/config/content/page_example'
      'title' => 'Esempio di pagina', // titolo della pagina
      'description' => 'Pagina semplice', // descrizione della pagina
      'page callback' => '_page_example', // funzione che restituisce il contenuto della pagina
      'access arguments' => array('administer site configuration'), // impostiamo i diritti di accesso per l’amministratore
  );    
    return $items; // restituiamo l’elenco delle pagine
}

Ora la nostra pagina è visibile solo all’amministratore, e il link alla pagina si trova nel pannello di amministrazione:

Il link appare nell’amministrazione perché Drupal inserisce automaticamente un collegamento per tutti i percorsi che iniziano con admin/config/content/*. Se impostiamo invece il percorso admin/config/people/*, il link apparirà nella sezione “Utenti” (al posto dell’asterisco possiamo specificare il nostro nome, in questo caso page_example).

Ora sappiamo creare blocchi e pagine; credo che questi siano gli hook principali per la visualizzazione dei contenuti, e li incontreremo spesso nei nostri moduli.

Nella prossima lezione analizzeremo hook_perm(), per creare nuovi permessi per gli utenti.