Travail avec les templates Twig

05/07/2025, by Ivan

Drupal vous permet de remplacer tous les templates utilisés pour générer le balisage HTML, afin que vous puissiez contrôler entièrement le balisage affiché dans votre thème personnalisé. Il existe des templates pour chaque élément de la page, depuis le HTML de haut niveau jusqu’aux petits champs.

Remplacement des templates

Vous pouvez remplacer les templates principaux de Drupal en ajoutant dans le dossier de votre thème des templates conformément à une convention de nommage spécifique.

Pour remplacer un template, vous devez :

1. Trouver le template que vous souhaitez remplacer.
2. Copier le fichier template depuis son emplacement de base vers le dossier de votre thème.
3. (Optionnel) Renommer le template selon les conventions de nommage afin de cibler un sous-ensemble plus spécifique des zones où le template est utilisé.
4. Modifier le template selon vos besoins.

Une fois que vous avez copié le fichier template dans votre thème et vidé le cache, Drupal utilisera votre version du template à la place de la version de base.

Vous pouvez découvrir quels templates sont utilisés pour n’importe quelle partie de la page en utilisant les outils de débogage Twig.

Les suggestions de hooks de thème

Parfois, vous souhaitez modifier un fichier template mais uniquement pour certains endroits où il est utilisé. Un exemple courant est de modifier le template d’un nœud uniquement pour un type de contenu spécifique. La couche thématique de Drupal vous permet de cibler des cas d’usage précis en suivant une convention de nommage spécifique. Lors du rendu d’un nœud de type article, Drupal cherchera d’abord le fichier template node--article.html.twig et l’utilisera s’il existe. Sinon, Drupal utilisera le template standard node.html.twig. Le processus par lequel Drupal détermine les noms possibles du template s’appelle les suggestions de thème.

Les suggestions de hooks de thème vous permettent de réaliser des remplacements ciblés dans votre thème pour les fichiers template en suivant une convention de nommage précise.

Toutes les couches du noyau, modules, moteurs de thème et thèmes peuvent fournir des suggestions. Vous pouvez ajouter ou modifier les suggestions avec les hooks :

Vider le cache

Lorsque vous travaillez avec les suggestions de thème, Drupal peut utiliser son cache au lieu des nouveaux templates proposés. Videz le cache si vous rencontrez ce problème. Pour vider le cache, choisissez une des méthodes décrites dans la section Vider le cache de Drupal.

Informations de base

Vous pouvez considérer les suggestions comme des indices de nommage indiquant au système quel template choisir selon les circonstances.

Les suggestions de template sont définies via des hooks de suggestions thématiques, qui peuvent être modifiés. Ces hooks permettent à n’importe quel module ou thème de fournir des alternatives ou modifier, réordonner ou supprimer les suggestions fournies par hook_theme_suggestions_HOOK() ou des appels précédents à ce hook.

Comment Drupal détermine les suggestions de thème de page basées sur le chemin

Voici une explication basée sur la fonction theme_get_suggestions() :

La liste des templates possibles pour une page donnée est générée par Drupal via la fonction theme_get_suggestions(), appelée par system_theme_suggestions_page().

Le chemin de la page dans Drupal est d’abord décomposé en ses composants. Comme mentionné, le chemin Drupal n’est jamais un alias : il existe un chemin Drupal unique par page. Par exemple, pour les URL "http://www.example.com/node/1/edit" et "http://www.example.com/mysitename?q=node/1/edit", le chemin Drupal est node/1/edit, dont les composants sont « node », « 1 » et « edit ».

Ensuite, le préfixe est fixé à « page ». Pour chaque composant, la logique suivante est appliquée :

1. Si le composant est un nombre, ajoutez le préfixe suivi de « __% » à la liste des suggestions.
2. Quel que soit le type du composant, ajoutez le préfixe suivi de « __ » puis du composant à la liste des suggestions.
3. Si le composant n’est pas un nombre, ajoutez « __ » suivi du composant au préfixe.

Après avoir parcouru tous les composants, si la page est la page d’accueil (configurée dans "Administration > Configuration > Système > Informations sur le site"), alors page__front est ajouté à la liste des suggestions.

Notez qu’à la fin, pour convertir une suggestion en nom de fichier réel, les doubles underscores __ deviennent des tirets - et .html.twig est ajouté. Ainsi, pour node/1/edit, la liste des suggestions est :

page.html.twig (toujours la suggestion de base)
page--node.html.twig (préfixe page__node)
page--node--%.html.twig
page--node--1.html.twig (le préfixe ne change pas car le composant est un nombre)
page--node--edit.html.twig (préfixe page__node__edit)
page--front.html.twig (uniquement si node/1/edit est la page d’accueil)

Lorsque la page est affichée, la dernière suggestion est testée. Si elle existe, elle est utilisée. Sinon, la suivante est testée, etc. Si aucune suggestion spécifique n’existe, page.html.twig est utilisée par défaut. Cela explique aussi pourquoi page--front.html.twig, s’il existe, remplace toute autre suggestion pour la page d’accueil, car c’est toujours la dernière suggestion pour la page définie comme page d’accueil.

Différences avec Drupal 7

Avant, pour modifier les suggestions de templates, vous modifiiez $variable['theme_hook_suggestion'] et $variable['theme_hook_suggestions'] dans les fonctions de prétraitement. Dans Drupal 8, les modules et thèmes définissent et modifient les suggestions via leurs propres hooks spécialisés.

Plus d’informations

Modifier l’enregistrement : Nouveaux hooks pour les suggestions de thème

Types de blocs supplémentaires (EBT) – Nouvelle expérience de Layout Builder❗

❗Types de paragraphes supplémentaires (EPT) – Nouvelle expérience Paragraphes