Lavorare con i template Twig
Drupal ti permette di sovrascrivere tutti i template usati per generare il markup HTML, così da avere il pieno controllo sul markup che viene mostrato come output nel tuo tema personalizzato. Esistono template per ogni elemento della pagina, dall’HTML di alto livello fino ai singoli campi.
Sovrascrivere i template
Puoi sovrascrivere i template core di Drupal aggiungendo nella cartella del tuo tema file che seguono le convenzioni di denominazione.
Per sovrascrivere un template devi:
1. Individuare il template che vuoi sovrascrivere.
2. Copiare il file del template dalla sua posizione originale nella cartella del tuo tema.
3. (Opzionale) Rinominare il template secondo le convenzioni di denominazione, per mirare a un sottoinsieme più specifico delle aree in cui il template è utilizzato.
4. Modificare il template secondo le tue esigenze.
Una volta copiato il file nella tua cartella tema e svuotata la cache, Drupal inizierà a usare la tua versione del template invece di quella base.
Puoi scoprire quali template vengono utilizzati in una parte qualsiasi della pagina tramite gli strumenti di debug Twig.
Suggerimenti dei theme hook
A volte vuoi modificare un file di template, ma solo per alcuni contesti in cui viene usato. Un esempio tipico è la modifica del template dei nodi solo per un determinato tipo di contenuto. Il layer di theming di Drupal ti permette di mirare a casi specifici seguendo le convenzioni di denominazione. Ad esempio, per un nodo di tipo articolo, Drupal cercherà prima node--article.html.twig e lo userà se esiste. Se non lo trova, userà node.html.twig. Questo processo con cui Drupal determina i possibili nomi da usare per un template si chiama “theme suggestions”.
I suggerimenti dei theme hook ti consentono di applicare sovrascritture mirate per i template con naming convention definite.
Tutti i layer (core, moduli, motori di tema e temi) possono fornire suggerimenti. Puoi aggiungere o modificare suggerimenti tramite hook:
- hook_theme_suggestions_HOOK(array $variables)
- hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
- hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
Svuotare la cache
Quando lavori con i suggerimenti dei theme hook, può succedere che Drupal utilizzi la cache anziché i nuovi template. In tal caso svuota la cache. Per farlo, usa uno dei metodi descritti in Pulizia della cache in Drupal.
Informazioni di base
I suggerimenti possono essere considerati come regole di naming che indicano al sistema di scegliere il template giusto in base alle circostanze.
I suggerimenti vengono generati tramite hook specifici per le theme suggestions, che possono essere modificati. Questi hook permettono a moduli o temi di fornire funzioni di tema alternative o nuovi suggerimenti di nomi per i template, oltre a riordinare o rimuovere suggerimenti già forniti da hook_theme_suggestions_HOOK() o hook precedenti.
Come Drupal determina i suggerimenti per il template page in base al percorso
Questo è un esempio basato sulla funzione theme_get_suggestions():
L’elenco dei template possibili per una pagina viene generato da Drupal tramite la funzione theme_get_suggestions(), che viene chiamata dalla funzione system_theme_suggestions_page().
Il percorso interno della pagina viene diviso in componenti. Come già detto, il percorso interno di Drupal non è un alias: per ogni pagina esiste un solo percorso Drupal. Per esempio, sia “http://www.example.com/node/1/edit” che “http://www.example.com/mysitename?q=node/1/edit” hanno come percorso Drupal node/1/edit, i cui componenti sono “node”, “1” e “edit”.
Il prefisso viene inizialmente impostato su “page”. Per ciascun componente viene applicata questa logica:
1. Se il componente è un numero, aggiungi al prefisso __% alla lista dei suggerimenti.
2. Aggiungi sempre __ + componente alla lista dei suggerimenti.
3. Se il componente non è un numero, aggiungi __ + componente al prefisso.
Se la pagina è la home (come configurato in Amministrazione > Configurazione > Sistema > Informazioni sul sito), viene aggiunto anche “page__front”.
Infine, “__” diventa “-” e viene aggiunto “.html.twig”. Così, per node/1/edit otteniamo:
1. page.html.twig
2. page--node.html.twig
3. page--node--%.html.twig
4. page--node--1.html.twig
5. page--node--edit.html.twig
6. page--front.html.twig (solo se è impostata come home)
Quando la pagina viene renderizzata, Drupal verifica i suggerimenti in ordine inverso: usa l’ultimo valido trovato. Se nessuno corrisponde, viene usato page.html.twig. Per questo page--front.html.twig, se esiste, ha sempre priorità sulla home.
Differenze con Drupal 7
In passato, per modificare i suggerimenti del template si agiva su $variable['theme_hook_suggestion'] e $variable['theme_hook_suggestions'] nelle funzioni di preprocess. In Drupal 8 invece, moduli e temi definiscono e modificano i suggerimenti nei propri hook dedicati.
Ulteriori informazioni
Consulta la documentazione: Nuovi hook per le theme suggestions