Création de templates Twig personnalisés pour un module personnalisé

L’idée générale dans Drupal 8 est que vous souhaitez éviter de créer du HTML directement dans le code PHP de votre module personnalisé. Vous voulez que cela soit géré via des templates Twig. Pour créer de nouveaux templates Twig dans votre module, suivez les étapes suivantes.

Étape n° 1 : Définir hook_theme dans le fichier .module
Créez un fichier [module].module s’il n’existe pas encore, et ajoutez le code qui déclare chacun de vos templates Twig. La clé de chaque élément dans le tableau correspondra au nom que vous utiliserez pour appeler ce template plus tard. N’utilisez pas de tirets dans le nom du fichier.

function test_twig_theme($existing, $type, $theme, $path) {
  return [
    'my_template' => [
      'variables' => ['test_var' => NULL],
    ],
  ];
}

Voir la documentation de hook_theme().

Étape n° 2 : Appeler le template
À l’endroit où vous retournez votre tableau de rendu (depuis la méthode d’un contrôleur appelé via le fichier yml de votre route, ou ailleurs), appelez le template Twig. Voici un exemple d’un module de test appelé depuis un fichier de routing yml :

/**
 * @file
 * Contains \Drupal\test_twig\Controller\TestTwigController.
 */
 
namespace Drupal\test_twig\Controller;
 
use Drupal\Core\Controller\ControllerBase;
 
class TestTwigController extends ControllerBase {
  public function content() {
    return [
      '#theme' => 'my_template',
      '#test_var' => $this->t('Test Value'),
    ];
  }
}

Vous pouvez aussi utiliser la méthode de rendu pour générer la sortie si vous devez l’utiliser dans un autre processus dans votre code :

$renderable = [
  '#theme' => 'my_template',
  '#test_var' => 'test variable',
];
$rendered = \Drupal::service('renderer')->renderPlain($renderable);

Notez que ceci est une implémentation de base sans mise en cache. La documentation du Render API contient plus d’informations pour ajouter la gestion du cache. À propos du cache : les noms des variables seront mis en cache, donc si vous modifiez un nom (par exemple « test_var » en « my_var »), vous devrez reconstruire le cache.

Étape n° 3 : Créer le template Twig
Dans votre module, créez un dossier templates et placez-y votre fichier de template Twig. Le nom du fichier doit correspondre à ce que vous avez défini dans hook_theme() (remplacez les underscores par des tirets). Ici, le fichier sera my-template.html.twig.
Voici un exemple de fichier que j’ai utilisé pour tester :

<p>Test twig template!</p>

<p>test_var: {{ test_var }}</p>

L’avantage est que ce fichier de template défini dans votre module sera utilisé seulement s’il n’existe pas déjà un fichier équivalent dans votre thème. Il suffit de placer un fichier dans le dossier templates de votre thème, vider le cache (drush cache-rebuild), et il sera pris en compte.

Vous pouvez organiser les fichiers dans des sous-dossiers dans le dossier templates de votre thème pour garder une bonne organisation.