Naamgevingsconventies voor Twig-sjablonen
Drupal laadt sjablonen op basis van bepaalde naamgevingsconventies. Dit stelt je in staat om sjablonen te overschrijven door ze aan je thema toe te voegen en specifieke namen te geven.
Nadat je een sjabloon hebt toegevoegd, moet je de cache opnieuw opbouwen zodat Drupal je nieuwe sjabloon herkent.
Je kunt Twig-sjablonen debuggen om te ontdekken welke sjablonen gebruikt worden om de markup weer te geven voor een bepaald element. Meer over Twig-debug hier.
Op deze pagina staan de conventies voor de basis HTML-structuur, pagina’s, regio’s, blokken, nodes, velden en andere kerncomponenten. (Handig om te weten: je kunt ook eigen suggesties maken met de hook_theme_suggestions_HOOK_alter-functie.)
HTML (<head>-sjabloon)
Het HTML-sjabloon levert de markup voor de basisstructuur van een HTML-pagina, inclusief de <head>-, <title>- en <body>-tags.
Basissjabloon: html.html.twig (locatie: core/modules/system/templates/html.html.twig)
Voorbeelden hoe je het basissjabloon kunt overschrijven:
- html--[internalviewpath].html.twig
- html--node--[nodeid].html.twig
- html.html.twig
Zie API-documentatie html.html.twig.
Pagina-sjabloon
Sjabloon: page--[front|internal/path].html.twig
Basissjabloon: page.html.twig (locatie: core/modules/system/templates/page.html.twig)
Er zijn veel suggesties mogelijk. De frontpage heeft prioriteit. De rest is gebaseerd op het interne pad van de huidige pagina. De frontpage kun je instellen via Beheer > Configuratie > Systeem > Site-informatie (http://example.com/admin/config/system/site-information). Het sjabloon van de frontpage is page--front.html.twig.
Verwar interne paden niet met URL-aliases, die niet worden meegenomen.
De lijst van sjabloonsuggesties is geordend naar specificiteit op basis van interne paden. Voor elk element van het pad wordt een suggestie gedaan, behalve numerieke onderdelen die niet worden doorgegeven aan volgende suggesties. Bijvoorbeeld: “http://www.example.com/node/1/edit” leidt tot deze suggesties:
- page--node--edit.html.twig
- page--node--1.html.twig
- page--node.html.twig
- page.html.twig
Zie API-documentatie page.html.twig. Zie ook hieronder het maintenance page-sjabloon.
Regio’s
Sjabloon: region--[region].html.twig
Basissjabloon: region.html.twig (locatie: core/modules/system/templates/region.html.twig)
Het regio-sjabloon wordt gebruikt als een gebied van de pagina inhoud bevat, ofwel via blokken of functies zoals hook_page_top() of hook_page_bottom(). Mogelijke regios worden gedefinieerd in het .info.yml-bestand van het thema.
Zie API-documentatie region.html.twig.
Blokken
Sjabloon: block--[module|--[delta].html.twig
Basissjabloon: block.html.twig (locatie: core/modules/block/templates/block.html.twig)
- block--[module]--[delta].html.twig
- block--[module].html.twig
- block.html.twig
“module” is de naam van het module, en “delta” is de interne ID die door het module aan het blok is gegeven.
Bijvoorbeeld, “block--block--1.html.twig” wordt gebruikt voor het eerste door de gebruiker gemaakte blok, toegevoegd in het blokbeheer, omdat dit door de Block-module met ID 1 is gemaakt. Regio-specifieke blok-sjablonen bestaan niet in Drupal 8.
Als je een blok hebt gemaakt met een custom module “custom” en delta “my-block”, dan heet de suggestie voor het thema “block--custom--my-block.html.twig”.
Een voorbeeld met Views: als je een blok hebt gemaakt via een View met naam “front_news” en display ID “block_1”, dan is de suggestie: block--views-block--front-news-block-1.html.twig (let op: underscores in namen worden vervangen door streepjes).
Let op dat modulenaam hier hoofdlettergevoelig is. Bijvoorbeeld: als je module “MyModule” heet, is de algemene suggestie “block--MyModule.html.twig”.
Zie API-documentatie block.html.twig.
Nodes
Sjabloon: node--[content-type|nodeid]--[viewmode].html.twig
Basissjabloon: node.html.twig (locatie: core/modules/node/templates/node.html.twig)
Sjabloonsuggesties worden gemaakt op basis van deze factoren, van meest specifiek naar minst. Drupal gebruikt het meest specifieke sjabloon dat het kan vinden:
- node--[nodeid]--[viewmode].html.twig
- node--[nodeid].html.twig
- node--[content-type]--[viewmode].html.twig
- node--[content-type].html.twig
- node--[viewmode].html.twig
- node.html.twig
Let op: underscores (_) in de machinenaam van het contenttype worden vervangen door streepjes (-).
Zie API-documentatie node.html.twig.
Taxonomy terms
Sjabloon: taxonomy-term--[vocabulary-machine-name|tid].html.twig
Basissjabloon: taxonomy-term.html.twig (locatie: core/modules/taxonomy/templates/taxonomy-term.html.twig)
Sjabloonsuggesties worden gemaakt op basis van deze factoren, van meest specifiek naar minst. Drupal gebruikt het meest specifieke sjabloon dat het kan vinden:
- taxonomy-term--[tid].html.twig
- taxonomy-term--[vocabulary-machine-name].html.twig
- taxonomy-term.html.twig
Let op: underscores in de machinenaam van het vocabulaire worden vervangen door streepjes.
Zie API-documentatie taxonomy-term.html.twig.
Velden
Sjabloon: field--[[type|name]|[entity-type]--[field-name|content-type]].html.twig
Basissjabloon: field.html.twig (locatie: core/modules/system/templates/field.html.twig)
Sjabloonsuggesties worden gemaakt op basis van deze factoren, van meest specifiek naar minst. Drupal gebruikt het meest specifieke sjabloon dat het kan vinden:
- field--node--[field-name]--[content-type].html.twig
- field--node--[field-name].html.twig
- field--node--[content-type].html.twig
- field--[field-name].html.twig
- field--[field-type].html.twig
- field.html.twig
Let op: underscores (_) in de machinenaam van velden worden vervangen door streepjes (-). Vergeet ook niet “field-” toe te voegen aan veldnamen, bijvoorbeeld: field--field-phone.html.twig.
Zie API-documentatie field.html.twig.
Commentaren
Sjabloon: comment--[comment-field-name]--[node-type].html.twig
Basissjabloon: comment.html.twig (locatie: core/modules/comment/templates/comment.html.twig)
Ondersteuning toegevoegd voor bestanden comment--[comment-field-name]--[node-type].html.twig, zodat commentaren van een specifiek nodetype anders kunnen worden weergegeven dan andere commentaren. Bijvoorbeeld: een commentaar bij een node van type article gebruikt “comment--field-comments--article.html.twig”.
Zie API-documentatie comment.html.twig.
Comment wrappers
Sjabloon: field--node--[comment-field-name]--[content-type].html.twig
Basissjabloon: field--comment.html.twig
Forums
Sjabloon: forums--[[container|topic]--forumID].html.twig
Basissjabloon: forums.html.twig (locatie: core/modules/forum/templates/forums.html.twig)
Sjabloonsuggesties worden gemaakt op basis van deze factoren, van meest specifiek naar minst. Drupal gebruikt het meest specifieke sjabloon dat het kan vinden:
Voor forumcontainers:
- forums--containers--[forumid].html.twig
- forums--[forumid].html.twig
- forums--containers.html.twig
- forums.html.twig
Voor forumtopics:
- forums--topics--[forumid].html.twig
- forums--[forumid].html.twig
- forums--topics.html.twig
- forums.html.twig
Zie API-documentatie forums.html.twig.
Maintenance page
Sjabloon: maintenance-page--[offline].html.twig
Basissjabloon: maintenance-page.html.twig (locatie: core/modules/system/templates/maintenance-page.html.twig)
Dit wordt gebruikt wanneer de database faalt. Handig om een vriendelijke pagina te tonen zonder foutmeldingen. Het Maintenance page-thema moet hiervoor correct ingesteld zijn.
Zie API-documentatie maintenance-page.html.twig.
Let op: maintenance-page--offline.html.twig wordt momenteel niet getoond als de database niet beschikbaar is. Issue: #2720109: maintenance-page--offline.html.twig wordt niet gedetecteerd in offline-modus.
Zoekresultaat
Sjabloon: search-result--[search-type].html.twig
Basissjabloon: search-result.html.twig (locatie: core/modules/search/templates/search-result.html.twig)
search-result.html.twig is de standaard wrapper voor afzonderlijke zoekresultaten. Afhankelijk van het zoektype worden andere suggesties gemaakt. Bijvoorbeeld: “example.com/search/node/Search+Term” leidt tot “search-result--node.html.twig”. Terwijl “example.com/search/user/bob” leidt tot “search-result--user.html.twig”. Modules kunnen meer suggesties toevoegen door nieuwe zoektypes te introduceren.
Zie API-documentatie search-result.html.twig.
Views
Alle Views-sjablonen kunnen op verschillende manieren worden overschreven met behulp van de view-naam, display-ID, displaytype of combinaties daarvan.
Voor elke View worden minstens twee sjablonen gebruikt. De eerste geldt voor alle Views: views-view.html.twig.
Het tweede sjabloon wordt bepaald door de gekozen stijl van de View. Let op dat bepaalde aspecten de stijl kunnen wijzigen; bijvoorbeeld, argumenten die een samenvattend overzicht geven, kunnen een speciale samenvattingsstijl activeren.
De standaardstijl voor alle Views is views-view-unformatted.html.twig.
Veel stijlen renderen vervolgens de afzonderlijke rijen via een rijstijl; de standaard rijstijl is views-view-fields.html.twig.
Sjablonen:
- 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
Basissjabloon: views-view.html.twig (locatie: core/themes/stable/templates/views/views-view.html.twig)
Bijvoorbeeld, als we het sjabloon “views-view.html.twig” voor onze View willen overschrijven, zijn dit geldige namen:
- views-view--[viewid]--[view-display-id].html.twig
- views-view--[viewid]--page.html.twig
- views-view--block.html.twig
- views-view--[viewid].html.twig
- views-view.html.twig
Sjablonen gebaseerd op views-view-field.html.twig krijgen een postfix met het veld-ID (zoals bij replacement-templates) om één veld van de View weer te geven:
- 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
Voorbeeld: een View met naam “foobar”, stijl: unformatted, rijstijl: fields, display: 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