Drupal 7 hook_block_info() et hook_block_view() : afficher des informations dans un bloc

Dans la leçon précédente, nous avons créé un module pour Drupal 7, dans cette leçon nous allons continuer à étendre les fonctionnalités de notre module. Nous ajouterons l'affichage d'un bloc via le hook hook_block_view(), ainsi que hook_block_info(). Ce bloc contiendra des informations sur les derniers utilisateurs du site avec un lien vers leur page.

Je commence par décrire le hook_block_info() :

Il définit tous les blocs créés par le module.

Ce hook définit dans Drupal quels blocs seront affichés par le module et peut décrire les réglages d’affichage du bloc.

Dans hook_block_info(), chaque bloc de votre module reçoit un identifiant unique appelé "delta" (un tableau des clés des valeurs retournées). La valeur delta doit être unique dans votre module et doit être utilisée pour :

1. Être passée aux autres hooks comme argument pour identifier le bloc qui sera configuré et affiché.
2. Être utilisée pour créer un modèle HTML de bloc nommé "block-MODULE-DELTA" appliqué à chaque bloc traité par Drupal (cela peut être utilisé pour écrire du CSS ou des scripts JavaScript).
3. Être utilisée pour définir des fonctions de thématisation block__MODULE__DELTA, pour une thématisation approfondie.
4. Être utilisée pour identifier votre bloc dans hook_block_info_alter() et les autres hooks.

La valeur delta peut être une chaîne ou un nombre. La longueur maximale de delta est de 32 octets.

Valeurs retournées

Un tableau associatif dont les clés sont les delta de chaque bloc et dont les valeurs sont les descriptions des blocs. La description de chaque bloc peut aussi être un tableau associatif avec les paires clé-valeur suivantes :

'info' : (obligatoire) Nom lisible du bloc pour l'administration. Cette information est utilisée pour identifier le bloc dans la section d’administration "Blocs" et n’est pas affichée dans le front-end du site.

'cache' : (optionnel) Décrit le comportement de mise en cache du bloc. Drupal définit les comportements suivants :

• DRUPAL_CACHE_PER_ROLE (par défaut) : Le bloc peut changer en fonction du rôle de l’utilisateur qui visite la page.
• DRUPAL_CACHE_PER_USER : Le bloc peut changer pour chaque utilisateur.
• DRUPAL_CACHE_PER_PAGE : Le bloc peut changer en fonction de la page.
• DRUPAL_CACHE_GLOBAL : Le bloc est identique indépendamment de l’utilisateur et de la page.

DRUPAL_NO_CACHE : Le bloc ne sera pas mis en cache.

'properties' : (optionnel) Tableau de métadonnées supplémentaires à ajouter au bloc.

Les propriétés courantes incluent :

'administrative' : Booléen qui indique si le bloc sera utilisé dans un contexte administratif.

'weight' : (optionnel) Initialise la valeur du poids du bloc.

'status' : (optionnel) Initialise la valeur du statut (1 = activé, 0 = désactivé).

'region' : (optionnel) Initialise la valeur de la région.

• 'visibility' : (optionnel) Initialise la visibilité du bloc. Valeurs possibles :
  • BLOCK_VISIBILITY_NOTLISTED : Afficher sur toutes les pages sauf celles listées.
  • BLOCK_VISIBILITY_LISTED : Afficher seulement sur ces pages.
  • BLOCK_VISIBILITY_PHP : Utiliser un code PHP personnalisé pour configurer la visibilité.
• 'pages' : (optionnel) Liste des chemins de pages pour le paramètre de visibilité.

Ajoutons un bloc avec un hook :

<?php

function sitemade_block_info(){
    $blocks = array();
    $blocks[1]['info'] = 'Liste des utilisateurs';
    return $blocks;
}

?>

Le bloc devrait apparaître dans l'administration, ajoutons-le dans la barre latérale gauche :

Maintenant que nous avons ajouté un bloc, affichons son contenu via le hook hook_block_view().

hook_block_view($delta = '') :

Paramètres

$delta - indique quel bloc est traité par le hook. C’est l’identifiant unique du bloc dans le module, défini dans hook_block_info().

Valeur retournée

Un tableau contenant les éléments suivants :

subject : Le titre traduit par défaut du bloc. Si le bloc n’a pas de titre par défaut, NULL sera retourné.

content : Le contenu du corps du bloc. Peut être un tableau rendu (préférable) ou une chaîne contenant du HTML rendu.

Ajoutons ce hook :

<?php
  function sitemade_block_view($delta = ''){
      $block = array(); // initialiser un tableau vide pour le bloc
      switch ($delta){
          case 1: // même delta que celui retourné dans hook_block_info()
              $block['subject'] = 'Utilisateurs'; // afficher le titre du bloc
              $block['content'] = ''; // initialiser la variable chaîne
              $query = db_select('users', 'u') // requête de sélection des utilisateurs
                ->fields('u', array('uid', 'name')) // sélectionner les champs
                ->orderBy('u.uid', 'DESC') // trier par ordre décroissant
                ->range(0, 5) // sélectionner les cinq premiers utilisateurs
                ->execute(); // exécuter la requête à la BDD
              $users = $query->fetchAll(PDO::FETCH_ASSOC); // traiter la requête en tableau associatif
              foreach($users as $user){
                  $block['content'] .= '<div><a href="' . base_path() . 'user/' . $user['uid'] . '">' . $user['name'] . '</a></div>';
                  // base_path() - fonction qui retourne le chemin vers la racine du site
              }
          break;
      }
      return $block;
  }
?>

En résultat, nous afficherons la liste des 5 derniers utilisateurs inscrits sur le site, sous forme de liens vers leurs pages. Bien sûr, il serait préférable d’utiliser la fonction l() pour les liens, mais cette fonction fera l’objet d’un article séparé.