logo

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

Types de blocs supplémentaires (EBT) – types de blocs stylisés et personnalisables : diaporamas, onglets, cartes, accordéons et bien d’autres. Paramètres intégrés pour l’arrière-plan, la boîte DOM, les plugins JavaScript. Découvrez dès aujourd’hui le futur de la création de mises en page.

Démo des modules EBT Télécharger les modules EBT

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

Types de paragraphes supplémentaires (EPT) – ensemble de modules basé sur les paragraphes analogiques.

Démo des modules EPT Télécharger les modules EPT

Défilement
  1. Accueil
  2. Documentation Drupal
  3. Thématisation Drupal 8
  4. Twig dans Drupal 8

Conventions de nommage des templates Twig

05/07/2025, by Ivan

Menu

Drupal charge les templates selon certaines conventions de nommage. Cela vous permet de surcharger les templates en les ajoutant dans votre thème avec des noms spécifiques.

Après avoir ajouté un template, vous devez vider le cache afin que Drupal détecte votre nouveau template.

Vous pouvez déboguer les templates Twig pour savoir lesquels sont utilisés pour afficher un élément donné. Plus d’informations sur le débogage Twig ici.

Cette page liste les conventions utilisées pour la structure HTML de base, les pages, régions, blocs, nœuds, champs et autres composants principaux. (Il est utile de savoir que vous pouvez créer vos propres suggestions de noms de templates via la fonction hook_theme_suggestions_HOOK_alter.)

HTML (<head> template)

Le template HTML fournit la structure de base de la page HTML, incluant les balises <head>, <title> et <body>.

Template de base : html.html.twig (emplacement de base : core/modules/system/templates/html.html.twig)

Exemples de surcharge :

  1. html--[internalviewpath].html.twig
  2. html--node--[nodeid].html.twig
  3. html.html.twig

Voir la documentation API html.html.twig.

Page template

Template : page--[front|internal/path].html.twig
Template de base : page.html.twig (emplacement : core/modules/system/templates/page.html.twig)

De nombreuses suggestions existent. La page d’accueil a la priorité. Les autres sont basées sur le chemin interne de la page courante. La page d’accueil peut être définie dans Administration > Configuration > Système > Informations sur le site (exemple d’URL). Le template pour la page d’accueil est page--front.html.twig.
Ne confondez pas le chemin interne avec les alias de chemin, qui ne sont pas pris en compte.

Les suggestions de templates sont listées par ordre de spécificité, basées sur les segments du chemin interne. Un template est suggéré pour chaque segment du chemin, mais les segments numériques ne sont pas transmis dans les suggestions suivantes. Par exemple, http://www.example.com/node/1/edit donnera les suggestions :

  1. page--node--edit.html.twig
  2. page--node--1.html.twig
  3. page--node.html.twig
  4. page.html.twig

Voir la documentation API page.html.twig. Voir aussi le template de la page de maintenance.

Regions

Template : region--[region].html.twig
Template de base : region.html.twig (emplacement : core/modules/system/templates/region.html.twig)

Le template région est utilisé lorsqu’une région de page contient du contenu, que ce soit via le système de blocs ou des fonctions comme hook_page_top() ou hook_page_bottom(). Les noms possibles des régions sont définis dans le fichier .info.yml du thème.

Voir la documentation API region.html.twig.

Blocks

Template : block--[module]--[delta].html.twig
Template de base : block.html.twig (emplacement : core/modules/block/templates/block.html.twig)

  1. block--[module]--[delta].html.twig
  2. block--[module].html.twig
  3. block.html.twig

« module » est le nom du module, « delta » est l’identifiant interne assigné par le module au bloc.

Par exemple, block--block--1.html.twig sera utilisé pour le premier bloc personnalisé ajouté via l’interface d’administration des blocs, car il a été créé par le module block avec l’identifiant 1. Les templates spécifiques aux régions ne sont pas disponibles dans Drupal 8.

Si vous avez un bloc créé par un module personnalisé nommé « custom » avec delta « my-block », le template sera nommé block--custom--my-block.html.twig.

Pour un bloc créé par Views avec nom de la vue « front_news » et identifiant d’affichage « block_1 », la suggestion de template sera block--views-block--front-news-block-1.html.twig (notez que les underscores sont remplacés par des tirets).

Les noms de modules sont sensibles à la casse. Par exemple, un module nommé « MyModule » aura pour suggestion de template générale block--MyModule.html.twig.

Voir la documentation API block.html.twig.

Nodes

Template : node--[type-de-contenu|nodeid]--[viewmode].html.twig
Template de base : node.html.twig (emplacement : core/modules/node/templates/node.html.twig)

Les suggestions de templates sont basées sur ces critères, listés du plus spécifique au plus général. Drupal utilise le template le plus spécifique trouvé :

  1. node--[nodeid]--[viewmode].html.twig
  2. node--[nodeid].html.twig
  3. node--[type-de-contenu]--[viewmode].html.twig
  4. node--[type-de-contenu].html.twig
  5. node--[viewmode].html.twig
  6. node.html.twig

Les underscores (_) dans le nom machine du type de contenu sont remplacés par des tirets (-).

Voir la documentation API node.html.twig.

Taxonomy terms

Template : taxonomy-term--[nom-machine-vocabulaire|tid].html.twig
Template de base : taxonomy-term.html.twig (emplacement : core/modules/taxonomy/templates/taxonomy-term.html.twig)

Les suggestions sont basées sur ces critères, du plus spécifique au plus général. Drupal utilise le template le plus spécifique :

  1. taxonomy-term--[tid].html.twig
  2. taxonomy-term--[nom-machine-vocabulaire].html.twig
  3. taxonomy-term.html.twig

Les underscores dans le nom machine du vocabulaire sont remplacés par des tirets.

Voir la documentation API taxonomy-term.html.twig.

Fields

Template : field--[[type|nom]--[type-d-entité]--[nom-champ|type-de-contenu]].html.twig
Template de base : field.html.twig (emplacement : core/modules/system/templates/field.html.twig)

Les suggestions sont basées sur ces critères, du plus spécifique au plus général. Drupal utilise le template le plus spécifique :

  1. field--node--[nom-champ]--[type-de-contenu].html.twig
  2. field--node--[nom-champ].html.twig
  3. field--node--[type-de-contenu].html.twig
  4. field--[nom-champ].html.twig
  5. field--[type-champ].html.twig
  6. field.html.twig

Les underscores (_) dans le nom machine du champ sont remplacés par des tirets (-). N’oubliez pas d’inclure le préfixe field-- dans le nom des champs personnalisés, par exemple : field--field-phone.html.twig.

Voir la documentation API field.html.twig.

Comments

Template : comment--[nom-champ-commentaire]--[type-de-noeud].html.twig
Template de base : comment.html.twig (emplacement : core/modules/comment/templates/comment.html.twig)

Le support a été ajouté pour créer des fichiers comment--[nom-champ-commentaire]--[type-de-noeud].html.twig pour formater différemment les commentaires selon le type de nœud. Par exemple, un commentaire sur un nœud de type article sera comment--field-comments--article.html.twig.

Voir la documentation API comment.html.twig.

Comment wrappers

Template : field--node--[nom-champ-commentaire]--[type-contenu].html.twig
Template de base : field--comment.html.twig

Forums

Template : forums--[[container|topic]--forumID].html.twig
Template de base : forums.html.twig (emplacement : core/modules/forum/templates/forums.html.twig)

Les suggestions sont basées sur ces critères, du plus spécifique au plus général. Drupal utilise le template le plus spécifique :

Pour les containers de forums :

  1. forums--containers--[forumid].html.twig
  2. forums--[forumid].html.twig
  3. forums--containers.html.twig
  4. forums.html.twig

Pour les sujets de forums :

  1. forums--topics--[forumid].html.twig
  2. forums--[forumid].html.twig
  3. forums--topics.html.twig
  4. forums.html.twig

Voir la documentation API forums.html.twig.

Page de maintenance

Template : maintenance-page--[offline].html.twig
Template de base : maintenance-page.html.twig (emplacement : core/modules/system/templates/maintenance-page.html.twig)

Ce template s’applique lorsque la base de données est indisponible. Utile pour afficher une page conviviale sans message d’erreur. La thème de maintenance doit être correctement configuré.

Voir la documentation API maintenance-page.html.twig.

Notez que le fichier maintenance-page--offline.html.twig n’est actuellement pas utilisé lorsque la base de données est hors ligne. Problème suivi : #2720109 : maintenance-page-offline.html.twig non détecté en mode hors ligne.

Search result

Template : search-result--[search-type].html.twig
Template de base : search-result.html.twig (emplacement : core/modules/search/templates/search-result.html.twig)

search-result.html.twig est le wrapper par défaut pour les résultats individuels de recherche. Selon le type de recherche, différents templates sont suggérés. Par exemple, example.com/search/node/Search+Term utilisera search-result--node.html.twig, tandis que example.com/search/user/bob utilisera search-result--user.html.twig. Les modules peuvent étendre les types de recherche et proposer des suggestions supplémentaires.

Voir la documentation API search-result.html.twig.

Views

Tous les templates Views peuvent être surchargés avec différents noms selon la vue, l’identifiant d’affichage, le type d’affichage, ou une combinaison de ceux-ci.

Pour chaque vue, au moins deux templates sont utilisés. Le premier est le template général pour toutes les vues : views-view.html.twig.

Le second est déterminé par le style choisi pour la vue. Certains aspects comme les arguments influencent également le style utilisé (ex : styles de résumé).

Le style par défaut est views-view-unformatted.html.twig.

Beaucoup de styles affichent ensuite chaque ligne selon un style de ligne ; par défaut : views-view-fields.html.twig.

Templates possibles :

  • views-view--[viewid]--[view-display-id].html.twig
  • views-view--[viewid]--[view-display-type].html.twig
  • views-view--[view-display-type].html.twig
  • views-view--[viewid].html.twig
  • views-view.html.twig

Template de base : views-view.html.twig (emplacement : core/themes/stable/templates/views/views-view.html.twig)

Exemple pour surcharger views-view.html.twig d’une vue nommée « foobar » :

  • views-view--foobar--page.html.twig
  • views-view--page.html.twig
  • views-view--foobar.html.twig
  • views-view.html.twig

Les templates basés sur views-view-field.html.twig ont un suffixe avec l’identifiant du champ :

  • views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
  • views-view-field--[viewid]--page--[fieldid].html.twig
  • views-view-field--block--[fieldid].html.twig
  • views-view-field--[fieldid].html.twig
  • views-view-field.html.twig

Exemple complet de templates testés pour une vue « foobar », style non formaté, style ligne : champs, affichage : page :

  • views-view--foobar--page.html.twig
  • views-view--page.html.twig
  • views-view--foobar.html.twig
  • views-view.html.twig
  • views-view-unformatted--foobar--page.html.twig
  • views-view-unformatted--page.html.twig
  • views-view-unformatted--foobar.html.twig
  • views-view-unformatted.html.twig
  • views-view-fields--foobar--page.html.twig
  • views-view-fields--page.html.twig
  • views-view-fields--foobar.html.twig
  • views-view-fields.html.twig