6.6. Travailler avec les templates dans Drupal. Quels sont les templates dans le cœur de Drupal.
Nous avons déjà vu que Drupal intègre Twig et comment l’utiliser. Dans cet article, nous allons expliquer comment travailler avec les templates Drupal, quels templates se trouvent dans le thème Stable, comment redéfinir les templates du thème Stable, ainsi que comment redéfinir les templates de diverses entités Drupal.
Commençons donc par les templates du thème Stable, rendez-vous dans le dossier templates du thème Stable :
Les templates sont classés selon leur fonction :
/core/themes/stable/templates/admin - templates pour l’interface Views UI, pages et éléments d’administration, templates de messages et rapports.
/core/themes/stable/templates/block - templates pour les blocs.
/core/themes/stable/templates/content - templates pour un nœud (node), commentaire, terme de taxonomie, élément RSS, résultats de recherche.
/core/themes/stable/templates/content-edit - templates pour les filtres et formulaires d’édition.
/core/themes/stable/templates/dataset - templates pour forums, flux RSS, tables, listes ul.
/core/themes/stable/templates/field - templates pour différents types de champs.
/core/themes/stable/templates/form - templates pour éléments de formulaire (champs de divers types).
/core/themes/stable/templates/layout - templates pour la structure de la page (page.html.twig), régions, le template principal html.html.twig où s’intègrent tous les autres templates.
/core/themes/stable/templates/misc - templates pour RSS, balisage RDF, icônes, messages Drupal, barre de progression.
/core/themes/stable/templates/navigation - templates pour menus, livres (module book), pagination, barre d’outils, onglets verticaux, fil d’Ariane.
/core/themes/stable/templates/user - templates pour la page utilisateur, nom d’utilisateur, signature de l’auteur d’un message de forum.
/core/themes/stable/templates/views - templates pour divers éléments du module Views.
Comme vous pouvez le voir, le thème Stable fournit un large éventail de templates à personnaliser. Pour redéfinir ces templates, il suffit de copier le template nécessaire dans votre sous-thème et de le modifier à votre convenance. Vous pouvez copier tous les templates, mais il est conseillé de ne copier que ceux dont vous avez besoin.
Redéfinir les templates pour le contenu (suggestions de templates)
Vous pouvez non seulement redéfinir les templates existants, mais aussi ajouter vos propres templates pour des nœuds individuels, termes de taxonomie, blocs, etc. Voici quelques exemples de redéfinitions de templates.
Template HTML
Le template HTML inclut la structure de base d’une page HTML.
Template principal : html.html.twig (emplacement de base : core/modules/system/templates/html.html.twig)
Exemples pour redéfinir ce template :
- html--chemininterne.html.twig
- html--node--id.html.twig
- html.html.twig
Le chemininterne correspond au chemin interne Drupal, par exemple node/15, taxonomy/term/46, user/2, etc.
Voir plus d’informations dans la documentation html.html.twig
Template de page
Options de redéfinition : page--[front|chemin/interne].html.twig
Template principal : page.html.twig (emplacement de base : core/modules/system/templates/page.html.twig)
Les templates de page sont très variés. Le template de la page d’accueil a la priorité. Tous les autres dépendent du chemin interne. La page d’accueil peut être configurée via Configuration du site - Paramètres de base du site - Page d’accueil :
/admin/config/system/site-information
Ne pas confondre chemin interne et alias. Par exemple, une page de news peut avoir l’URL /news/titre-de-node mais le chemin interne est /node/id.
Pour la page d’édition d’un nœud, par exemple http://www.exemple.com/node/1/edit, les templates possibles sont :
page--node--edit.html.twig
page--node--1.html.twig
page--node.html.twig
page.html.twig
Voir plus dans la documentation page.html.twig
Régions
Options de redéfinition : region--[region].html.twig
Template de base : region.html.twig (emplacement : core/modules/system/templates/region.html.twig)
Le template de région est utilisé quand une région contient du contenu créé par le système de blocs ou via la fonction hook_page_build(). Les noms des régions sont définis dans le fichier .info.yml du thème.
Voir la documentation region.html.twig
Blocs
Options de redéfinition : block--[module|--delta].html.twig
Template principal : block.html.twig (emplacement : core/modules/block/templates/block.html.twig)
- block--module--delta.html.twig
- block--module.html.twig
- block.html.twig
‘module’ est le nom du module qui fournit le bloc, delta est l’identifiant interne du bloc dans le module.
Par exemple, block--block--1.html.twig est le premier bloc ajouté via l’interface d’administration des blocs. Pour un module personnalisé, un bloc avec le delta « my-block » aura pour template block--custom--my-block.html.twig.
Pour le module Views, le template de bloc se redéfinit ainsi : si le nom de la vue est « front_news » et l’identifiant d’affichage « block_1 », alors le template sera : block--views-block--front-news-block-1.html.twig
Notez que les underscores sont remplacés par des tirets.
Il n’est pas possible, dans Drupal de base, de spécifier un template différent pour un bloc placé dans une région spécifique.
Notez aussi que les noms de pattern sont sensibles à la casse. Si votre module s’appelle MyModule, alors le template sera block--MyModule.html.twig.
Voir la documentation block.html.twig
Contenus (Nœuds)
Options de redéfinition : node--[type|nodeid]--[viewmode].html.twig
Template principal : node.html.twig (emplacement : core/modules/node/templates/node.html.twig)
Possibilités de redéfinition :
- node--nodeid--viewmode.html.twig
- node--nodeid.html.twig
- node--type--viewmode.html.twig
- node--type.html.twig
- node--viewmode.html.twig
- node.html.twig
Le viewmode correspond à l’affichage du nœud : Full, Teaser, RSS, Token, etc. Le type correspond au type de contenu (News, Articles, Pages). Nodeid est l’identifiant du nœud.
Voir la documentation node.html.twig
Termes de taxonomie
Options de redéfinition : taxonomy-term--[vocabulary-machine-name|tid].html.twig
Template principal : taxonomy-term.html.twig (emplacement : core/modules/taxonomy/templates/taxonomy-term.html.twig)
Possibilités :
- taxonomy-term--tid.html.twig
- taxonomy-term--vocabulary-machine-name.html.twig
- taxonomy-term.html.twig
Tous les underscores dans les noms des vocabulaires doivent être remplacés par des tirets.
Voir la documentation taxonomy-term.html.twig
Champs
Options de redéfinition : field--[type|name[--content-type]|content-type].html.twig
Template principal : field.html.twig (emplacement : core/modules/system/templates/field.html.twig)
Possibilités :
- field--field-name--content-type.html.twig
- field--content-type.html.twig
- field--field-name.html.twig
- field--field-type.html.twig
- field.html.twig
Tous les underscores dans les noms de type de contenu et de champs sont remplacés par des tirets.
Voir la documentation field.html.twig
Commentaires
Options de redéfinition : comment--node-[type].html.twig
Template principal : comment.html.twig (emplacement : core/modules/comment/templates/comment.html.twig)
Vous pouvez définir un template différent pour les commentaires selon le type de contenu, par exemple : comment--node-article.html.twig.
Voir la documentation comment.html.twig
Vous pouvez également définir un template distinct pour l’encapsulation des commentaires :
Options : comment-wrapper--node-[type].html.twig
Template principal : comment-wrapper.html.twig (emplacement : core/modules/comment/templates/comment-wrapper.html.twig)
Views
Tous les templates Views peuvent être redéfinis en utilisant le nom machine de la vue, l’id de l’affichage, le type d’affichage (page, bloc, etc.) ou une combinaison des trois.
Chaque vue utilise au moins deux templates. Le premier est views-view.html.twig :
Le second dépend du style d’affichage (liste non formatée, table, grille, liste HTML). Par défaut, c’est views-view-unformatted.html.twig qui est utilisé.
Si on affiche des entités complètes (nœuds complets ou teasers) via Views, c’est ce template qui s’applique, mais si on affiche des champs, Views utilise un autre template : views-view-fields.html.twig.
Voici quelques noms possibles pour la redéfinition :
Nom de la vue : foobar (nom machine)
Format d’affichage : unformatted (liste non formatée)
Style d’enregistrement : fields
Nom de l’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
Forum
Options de redéfinition : forums--[[container|topic]--forumID].html.twig
Template principal : forums.html.twig (emplacement : core/modules/forum/templates/forums.html.twig)
Vous pouvez définir des templates distincts pour les conteneurs et les sujets de forum :
forums--containers--forumID.html.twig
forums--forumID.html.twig
forums--containers.html.twig
forums.html.twig
Pour les sujets :
forums--topics--forumID.html.twig
forums--forumID.html.twig
forums--topics.html.twig
forums.html.twig
Voir la documentation forums.html.twig
Mode maintenance
Options de redéfinition : maintenance-page--[offline].html.twig
Template principal : maintenance-page.html.twig (emplacement : core/modules/system/templates/maintenance-page.html.twig)
Voir la documentation maintenance-page.html.twig
Résultats de recherche
Options de redéfinition : search-result--[searchType].html.twig
Template principal : search-result.html.twig (emplacement : core/modules/search/templates/search-result.html.twig)
Par exemple, pour une recherche de nœuds :
/search/node/Search+Term
Vous pouvez utiliser le template search-result--node.html.twig.
Pour une recherche d’utilisateurs :
/search/user/bob
Utilisez le template search-result--user.html.twig.