6.6. Lavorare con i template in Drupal. Cosa sono i template nel core di Drupal.

Abbiamo già visto che in Drupal è integrato Twig e come utilizzarlo. In questo articolo analizzeremo come lavorare con i template di Drupal, quali template si trovano nel tema Stable, come sovrascriverli e come ridefinire i template di varie entità di Drupal.

Iniziamo con i template del tema Stable. Apri la cartella templates del tema Stable:

I template sono suddivisi per categoria funzionale:

/core/themes/stable/templates/admin – template per l’interfaccia Views UI, pagine e voci di amministrazione, messaggi e report.
/core/themes/stable/templates/block – template dei blocchi.
/core/themes/stable/templates/content – template per i nodi, i commenti, i termini di tassonomia, gli elementi RSS e i risultati di ricerca.
/core/themes/stable/templates/content-edit – template per i filtri e i moduli di modifica.
/core/themes/stable/templates/dataset – template per forum, canali RSS, tabelle e liste <ul>.
/core/themes/stable/templates/field – template dei campi di diversi tipi.
/core/themes/stable/templates/form – template degli elementi dei moduli (campi di vari tipi).
/core/themes/stable/templates/layout – template della struttura della pagina page.html.twig, regioni, e il template principale html.html.twig dove sono inclusi tutti gli altri template.
/core/themes/stable/templates/misc – template per icone RSS, RDF, messaggi di Drupal, barra di progresso.
/core/themes/stable/templates/navigation – template per menu, moduli “book”, pager, toolbar, tab verticali e breadcrumb.
/core/themes/stable/templates/user – template per la pagina utente, nome utente, firma dell’autore nei forum.
/core/themes/stable/templates/views – template dei vari elementi del modulo Views.

Come puoi vedere, il tema Stable fornisce un’ampia gamma di template da personalizzare. Per sovrascrivere un template, basta copiarlo nel tuo sotto-tema e modificarlo a piacimento. Puoi copiarli tutti, ma è consigliabile copiare solo quelli necessari.

Sovrascrivere i template dei contenuti (template suggestions)

Puoi non solo ridefinire i template esistenti, ma anche crearne di personalizzati per singoli nodi, termini di tassonomia, blocchi, ecc. Ecco alcuni esempi di sovrascrittura.

Template HTML

Il template HTML include la struttura di base di una pagina HTML.

Template principale: html.html.twig (posizione base: core/modules/system/templates/html.html.twig)

Esempi di override:

1. html--internalviewpath.html.twig
2. html--node--id.html.twig
3. html.html.twig

internalviewpath è il percorso interno di Drupal, ad esempio: node/15, taxonomy/term/46, user/2, ecc.

Per maggiori informazioni consulta la documentazione di html.html.twig.

Template della pagina

Opzioni di override: page--[front|internal/path].html.twig

Template principale: page.html.twig (posizione base: core/modules/system/templates/page.html.twig)

I template per le pagine sono numerosi. Il template della homepage ha la priorità più alta, mentre gli altri dipendono dal percorso interno. La homepage si imposta in Configurazione → Impostazioni di base del sito → Pagina iniziale:

/admin/config/system/site-information

Non confondere il percorso interno con gli alias URL. Ad esempio, una notizia con percorso /news/titolo potrebbe avere il percorso interno /node/ID.

Per la pagina di modifica di un nodo (http://www.example.com/node/1/edit), puoi utilizzare i seguenti template:

page--node--edit.html.twig
page--node--1.html.twig
page--node.html.twig
page.html.twig

Vedi la documentazione di page.html.twig.

Regioni

Opzioni di override: region--[region].html.twig

Template principale: region.html.twig (posizione base: core/modules/system/templates/region.html.twig)

Il template della regione viene usato quando essa contiene contenuto generato dal sistema dei blocchi o dalla funzione hook_page_build(). I nomi delle regioni sono definiti nel file .info.yml del tema.

Consulta la documentazione di region.html.twig.

Blocchi

Opzioni di override: block--[module|--delta].html.twig

Template principale: block.html.twig (posizione base: core/modules/block/templates/block.html.twig)

Esempi:

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

module è il nome del modulo che genera il blocco, mentre delta è l’ID interno del blocco.

Esempio: block--block--1.html.twig rappresenta il primo blocco aggiunto manualmente. Per un modulo personalizzato con un blocco “my-block”, il template sarà block--custom--my-block.html.twig.

Per un blocco generato da Views con nome front_news e display ID block_1, il template sarà: block--views-block--front-news-block-1.html.twig (gli underscore diventano trattini).

I nomi dei template sono sensibili alle maiuscole.

Consulta la documentazione di block.html.twig.

Nodi (Contenuti)

Opzioni di override: node--[type|nodeid]--[viewmode].html.twig

Template principale: node.html.twig (posizione base: core/modules/node/templates/node.html.twig)

Esempi di override:

1. node--nodeid--viewmode.html.twig
2. node--nodeid.html.twig
3. node--type--viewmode.html.twig
4. node--type.html.twig
5. node--viewmode.html.twig
6. node.html.twig

Viewmode è la modalità di visualizzazione (Full, Teaser, RSS, ecc.), Type è il tipo di contenuto (News, Article, Page), nodeid è l’ID del nodo.

Consulta la documentazione di node.html.twig.

Termini di tassonomia

Opzioni di override: taxonomy-term--[vocabulary-machine-name|tid].html.twig

Template principale: taxonomy-term.html.twig (posizione base: core/modules/taxonomy/templates/taxonomy-term.html.twig)

Esempi:

1. taxonomy-term--tid.html.twig
2. taxonomy-term--vocabulary-machine-name.html.twig
3. taxonomy-term.html.twig

Gli underscore nei nomi vanno sostituiti con trattini.

Consulta la documentazione di taxonomy-term.html.twig.

Campi

Opzioni di override: field--[type|name[--content-type]|content-type].html.twig

Template principale: field.html.twig (posizione base: core/modules/system/templates/field.html.twig)

Esempi:

1. field--field-name--content-type.html.twig
2. field--content-type.html.twig
3. field--field-name.html.twig
4. field--field-type.html.twig
5. field.html.twig

Gli underscore nei nomi del campo o del tipo di contenuto vanno sostituiti con trattini.

Consulta la documentazione di field.html.twig.

Commenti

Opzioni di override: comment--node-[type].html.twig

Template principale: comment.html.twig (posizione base: core/modules/comment/templates/comment.html.twig)

Puoi impostare un template separato per i commenti di ciascun tipo di contenuto, ad esempio comment--node-article.html.twig.

Consulta la documentazione di comment.html.twig.

Per il wrapper dei commenti:

Opzioni di override: comment-wrapper--node-[type].html.twig

Template principale: comment-wrapper.html.twig (posizione base: core/modules/comment/templates/comment-wrapper.html.twig)

Views

I template di Views possono essere ridefiniti utilizzando il nome macchina della vista, l’ID del display, il tipo di visualizzazione (page, block, ecc.) o una loro combinazione.

Ogni vista utilizza almeno due template:

views-view.html.twig (struttura base della vista)

views-view-unformatted.html.twig (per la visualizzazione non formattata o “lista”)

Se la vista mostra campi invece di entità complete, usa views-view-fields.html.twig.

Esempi di override:

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

Opzioni di override: forums--[[container|topic]--forumID].html.twig

Template principale: forums.html.twig (posizione base: core/modules/forum/templates/forums.html.twig)

Esempi per i container:

forums--containers--forumID.html.twig
forums--forumID.html.twig
forums--containers.html.twig
forums.html.twig

Per gli argomenti del forum:

forums--topics--forumID.html.twig
forums--forumID.html.twig
forums--topics.html.twig
forums.html.twig

Consulta la documentazione di forums.html.twig.

Modalità manutenzione

Opzioni di override: maintenance-page--[offline].html.twig

Template principale: maintenance-page.html.twig (posizione base: core/modules/system/templates/maintenance-page.html.twig)

Consulta la documentazione di maintenance-page.html.twig.

Risultati di ricerca

Opzioni di override: search-result--[searchType].html.twig

Template principale: search-result.html.twig (posizione base: core/modules/search/templates/search-result.html.twig)

Esempio per la ricerca nei nodi:

/search/node/Termine+di+ricerca → search-result--node.html.twig

Per la ricerca utenti:

/search/user/mario → search-result--user.html.twig