Surcharger un gabarit avec un module à l'aide de hook_theme dans un thème Drupal

Drupal 8

Surcharger un gabarit avec un module à l'aide de hook_theme dans un thème Drupal

Soumis par Antoine le sam 11/04/2020 - 19:03

Surcharger un gabarit va permettre de modifier le code html d'une portion plus ou moins grande du code html de votre site. Généralement, on utilise un thème, mais il peut être nécessaire de le faire depuis un module.

La démarche

  • Trouver le nom du gabarit à surcharger, une suggestion de nom et le theme_hook
  • Copier le gabarit dans le module
  • Appeler le nouveau gabarit dans le fichier nommodule.module
  • Saisir le code html

Trouver le nom du gabarit à surcharger, une suggestion de nom et le theme_hook

Pour trouver ces trois informations, il faut avoir paramétré son Drupal pour activer le mode debug de twig et affiché les outils de développeur du navigateur (clic droit -> "examiner" ou F12).

Pour trouver le gabarit, il faut examiner l'élément et chercher dans les commentaires en vert la zone <!-- BEGIN OUTPUT qui indique le chemin et le nom du gabarit utilisé.

Le theme_hook est indiqué juste au dessus dans la zone <!-- THEME HOOK :

Les suggestions sont une liste de noms indiquées entre <!-- THEME HOOK : et <!-- BEGIN OUTPUT. Cette liste est classée du plus précis au moins précis

Copier le gabarit dans le module et le renommer

Créer un répertoire templates à la racine du module et copier le gabarit à l'intérieur. Vous pouvez le renommer comme bon vous semble

Appeler le nouveau gabarit dans le fichier nommodule.module

Si ce n'est pas déjà fait, créer un fichier nommodule.module à la racine de votre module. Insérer le hook "nommodule_theme. Vous trouverez l'api de cet hook dans le répertoire \web\core\lib\Drupal\Core\Render\theme.api.php ou à cette adresse dans la doc officielle. Rappelez vous, le code d'un hook dans l'api ne sert que d'exemple. Vous ne devez copier que les annotations qui explique le fonctionnement du hook, le nom du hook et ses arguments.

function hook_theme($existing, $type, $theme, $path) {
 
}

Ce hook doit renvoyer un tableau associatif dont les clés sont appelées des hook_themes et dont les valeurs sont des tableaux associatifs. Chaque clé hook_theme sert soit à : 

  • surcharger un render élément
  • rattacher un thème à un contrôleur
  • surcharger un gabarit

Pour surcharger un gabarit la clé doit correspondre à une des suggestion de nom de gabarit mais en remplaçant les - par _. La valeur de la clé doit être un tableau associatif avec deux couple clés valeur :

  • La clé "template" doit avoir pour valeur le nom du gabarit que vous lui avez donné dans le point B
  • La clé "base hook" doit avoir pour valeur le thème hook identifié dans le point A.

 

Dans l'exemple ci-dessous, le module "monmodule" surcharge les gabarits des nodes de type page à l'aide du fichier  templates/node--page.html.twig.

function monmodule_theme($existing, $type, $theme, $path)
{
  return array(
    'node__page' => array(
      'template' => 'node--page',
      'base hook' => 'node'
    ),
  );
}

Saisir le code

Il ne reste plus qu'à modifier le gabarit pour obtenir le résultat voulu.

Version