Werken met Twig-sjablonen
Drupal laat je toe om alle sjablonen die gebruikt worden voor het genereren van HTML-markup te overschrijven, zodat je volledige controle hebt over de markup die in je thema wordt weergegeven. Er bestaan sjablonen voor elk element van de pagina, van de algemene HTML-structuur tot kleine velden.
Sjablonen overschrijven
Je kunt de basis Drupal-sjablonen overschrijven door sjablonen toe te voegen aan je themamap die overeenkomen met een specifieke naamgevingsconventie.
Om sjablonen te overschrijven moet je:
1. Zoek het sjabloon dat je wilt overschrijven.
2. Kopieer het sjabloonbestand vanuit de oorspronkelijke locatie naar je themamap.
3. (optioneel) Hernoem het sjabloon volgens de naamgevingsconventies om je te richten op een specifiek subset van plaatsen waar het sjabloon wordt gebruikt.
4. Bewerk het sjabloon naar wens.
Zodra je het sjabloonbestand naar je thema hebt gekopieerd en de cache hebt geleegd, gebruikt Drupal jouw versie van het sjabloonbestand in plaats van de basisversie.
Je kunt ontdekken welke sjablonen voor elk deel van de pagina gebruikt worden met behulp van de Twig-debugtools.
Thema hook-suggesties
Soms wil je wijzigingen maken in een sjabloonbestand, maar alleen voor specifieke gevallen waarin het gebruikt wordt. Een typisch voorbeeld is het aanpassen van een node-sjabloon, maar alleen voor nodes van een bepaald type. De themalaag van Drupal laat je toe je te richten op specifieke gevallen door een bepaalde naamgevingsconventie te volgen. Bij het renderen van een artikel-node kijkt Drupal eerst of er een bestand node--article.html.twig bestaat en gebruikt dat als het beschikbaar is. Zo niet, dan valt Drupal terug op het standaardsjabloon node.html.twig. Het proces waarmee Drupal bepaalt welke mogelijke namen een sjabloonbestand kan hebben, heet themasuggesties.
Thema hook-suggesties laten je toe om doelgerichte overschrijvingen te implementeren in je thema voor sjabloonbestanden met een specifieke naamgevingsconventie.
Alle lagen – core, modules, theme-engines en thema’s – kunnen suggesties bieden. Je kunt suggesties toevoegen of wijzigen met de hooks:
- hook_theme_suggestions_HOOK(array $variables)
- hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
- hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
Cache herstellen
Bij het werken met themasuggesties kan het gebeuren dat Drupal de cache gebruikt en je nieuwe sjablonen niet worden opgepikt. Maak de cache leeg als dit gebeurt. Om de cache te legen, gebruik een van de methodes beschreven in Cache legen in Drupal.
Achtergrondinformatie
Je kunt suggesties zien als naamgevingshints die het systeem helpen te kiezen op basis van de juiste omstandigheden.
Sjabloonsuggesties worden ingesteld via thema-suggestie-hooks, die aangepast kunnen worden. Deze hooks laten elke module of thema toe om alternatieve functies of sjabloonnaamsuggesties te geven, en suggesties van hook_theme_suggestions_HOOK() of eerdere hooks te herordenen of te verwijderen.
Hoe Drupal themasuggesties voor een pagina bepaalt op basis van het pad
Een extra uitleg gebaseerd op de functie theme_get_suggestions():
De lijst met mogelijke sjablonen voor een bepaalde pagina wordt door Drupal gegenereerd met theme_get_suggestions(), aangeroepen door system_theme_suggestions_page().
Het pad naar de pagina wordt eerst opgesplitst in componenten. Zoals eerder gezegd, is het Drupal-pad niet hetzelfde als een alias: een pagina heeft exact één Drupal-pad. Voorbeelden: "http://www.example.com/node/1/edit" en "http://www.example.com/mysitename?q=node/1/edit" hebben beide het Drupal-pad node/1/edit, met de componenten "node", 1 en "edit".
Vervolgens wordt de prefix ingesteld op “page”. Voor elk component wordt deze logica toegepast:
1. Als de component een getal is, voeg prefix + “__%” toe aan de suggestielijst.
2. Ongeacht of de component een getal is, voeg prefix + “__” + component toe aan de suggestielijst.
3. Als de component geen getal is, voeg “__” + component toe aan de prefix.
Nadat alle componenten doorlopen zijn, wordt – als de pagina de frontpage is (ingesteld bij "Beheer > Configuratie > Systeem > Site-informatie") – “page__front” toegevoegd aan de suggestielijst.
Op het einde worden de suggesties omgezet naar bestandsnamen door “__” te vervangen door “-” en “.html.twig” toe te voegen. Dus voor node/1/edit krijgen we deze lijst:
1. page.html.twig (altijd aanwezig)
2. page--node.html.twig (prefix wordt page__node)
3. page--node--%.html.twig
4. page--node--1.html.twig (prefix blijft gelijk, want component is een getal)
5. page--node--edit.html.twig (prefix wordt page__node__edit)
6. page--front.html.twig (maar alleen als node/1/edit de frontpage is)
Wanneer de pagina wordt weergegeven, wordt de laatste suggestie eerst gecontroleerd. Als die bestaat, wordt die gebruikt. Anders gaat Drupal terug naar de vorige, enzovoort. Als geen van de suggesties bestaat, is page.html.twig de laatste fallback. Dit verklaart ook waarom page--front.html.twig, als het bestaat, elk ander sjabloon voor de frontpage overschrijft: dit is altijd de laatste suggestie voor de frontpage.
Verschillen met Drupal 7
Vroeger wijzigde je $variable['theme_hook_suggestion'] en $variable['theme_hook_suggestions'] in preprocess-functies om themasuggesties toe te voegen. In Drupal 8 definiëren en wijzigen modules en thema’s nu suggesties in hun eigen specifieke hooks.