Drupal 7 hook_block_info() e hook_block_view() — visualizzare le informazioni in un blocco
Nella lezione precedente abbiamo creato un modulo per Drupal 7; in questa lezione continueremo ad ampliarne le funzionalità. Aggiungeremo la visualizzazione di un blocco tramite gli hook hook_block_view() e hook_block_info(). In questo blocco verranno mostrate informazioni sugli ultimi utenti registrati sul sito, con un link alla loro pagina profilo.
Iniziamo con la descrizione di hook_block_info():
Definisce tutti i blocchi creati dal modulo.
Questo hook informa Drupal su quali blocchi verranno generati dal modulo e può descrivere le impostazioni di visualizzazione del blocco.
In hook_block_info() ogni blocco del tuo modulo riceve un identificatore univoco chiamato "delta" (una chiave dell’array dei valori restituiti). Il valore delta deve essere univoco all’interno del tuo modulo e viene utilizzato per i seguenti scopi:
- Passato come argomento agli altri hook per identificare quale blocco deve essere configurato e visualizzato.
- Utilizzato per creare un template HTML del blocco “block-MODULE-DELTA”, applicato a ogni blocco gestito da Drupal (utile per scrivere CSS o JavaScript personalizzati).
- Utilizzato per definire funzioni di tematizzazione block__MODULE__DELTA, per una tematizzazione più approfondita.
- Utilizzato per identificare il tuo blocco in hook_block_info_alter() e in altri hook correlati.
Il valore di delta può essere una stringa o un numero. La lunghezza massima di delta è 32 byte.
Valori restituiti
Un array associativo le cui chiavi sono i delta di ciascun blocco e i cui valori sono le descrizioni dei blocchi. La descrizione di ogni blocco può essere anch’essa un array associativo con le seguenti coppie chiave-valore:
'info': (obbligatorio) Nome leggibile del blocco per l’interfaccia di amministrazione. Questa informazione serve per identificare il blocco nella sezione “Blocchi” dell’amministrazione e non viene mostrata nel front-end del sito.
'cache': (opzionale) Descrive il comportamento di caching del blocco. Drupal prevede i seguenti comportamenti:
- DRUPAL_CACHE_PER_ROLE (predefinito): il blocco può variare in base al ruolo dell’utente che visualizza la pagina.
- DRUPAL_CACHE_PER_USER: il blocco può variare per ciascun utente.
- DRUPAL_CACHE_PER_PAGE: il blocco può variare in base alla pagina.
- DRUPAL_CACHE_GLOBAL: il blocco è uguale per tutti gli utenti e tutte le pagine.
DRUPAL_NO_CACHE: il blocco non verrà memorizzato nella cache.
'properties': (opzionale) Array di metadati aggiuntivi per il blocco.
Le proprietà comuni includono:
'administrative': Booleano che indica se il blocco verrà utilizzato in un contesto amministrativo.
'weight': (opzionale) Imposta il peso del blocco.
'status': (opzionale) Imposta lo stato del blocco (1 = attivo, 0 = disattivato).
'region': (opzionale) Imposta la regione in cui verrà visualizzato il blocco.
- 'visibility': (opzionale) Imposta la visibilità del blocco. I valori possibili sono:
- BLOCK_VISIBILITY_NOTLISTED: mostra il blocco in tutte le pagine tranne quelle elencate.
- BLOCK_VISIBILITY_LISTED: mostra il blocco solo nelle pagine elencate.
- BLOCK_VISIBILITY_PHP: usa codice PHP personalizzato per controllare la visibilità.
- 'pages': (opzionale) Elenco dei percorsi di pagina per il parametro “visibility”.
Aggiungiamo un blocco tramite l’hook:
<?php
function sitemade_block_info(){
$blocks = array();
$blocks[1]['info'] = 'Elenco utenti';
return $blocks;
}
?>
Il blocco dovrebbe apparire nella sezione di amministrazione. Aggiungiamolo nella barra laterale sinistra:
Ora che abbiamo aggiunto il blocco, mostriamone il contenuto tramite l’hook hook_block_view().
hook_block_view($delta = ''):
Parametri
$delta – indica quale blocco viene elaborato dall’hook. È l’identificatore univoco del blocco nel modulo, definito in hook_block_info().
Valore restituito
Array contenente i seguenti elementi:
subject: Titolo tradotto del blocco. Se il blocco non ha un titolo predefinito, verrà restituito NULL.
content: Contenuto del corpo del blocco. Può essere un array renderizzabile (preferibile) o una stringa contenente HTML già elaborato.
Aggiungiamo questo hook:
<?php
function sitemade_block_view($delta = ''){
$block = array(); // inizializziamo un array vuoto per il blocco
switch ($delta){
case 1: // stesso delta restituito in hook_block_info()
$block['subject'] = 'Utenti'; // titolo del blocco
$block['content'] = ''; // inizializziamo la variabile di contenuto
$query = db_select('users', 'u') // query per selezionare gli utenti
->fields('u', array('uid', 'name')) // selezione dei campi
->orderBy('u.uid', 'DESC') // ordiniamo in ordine decrescente
->range(0, 5) // selezioniamo cinque utenti
->execute(); // eseguiamo la query
$users = $query->fetchAll(PDO::FETCH_ASSOC); // elaboriamo il risultato come array
foreach($users as $user){
$block['content'] .='<div><a href="' . base_path() . 'user/' . $user['uid'] . '">' . $user['name'] . '</a></div>';
// base_path() restituisce il percorso alla radice del sito
}
break;
}
return $block;
}
?>
Come risultato, verrà mostrato l’elenco degli ultimi 5 utenti registrati sul sito, sotto forma di link alle loro pagine profilo. Ovviamente sarebbe meglio utilizzare la funzione l() per generare i link, ma questa merita un articolo a parte.
