Gerarchia dei file template nel Tema: sapere quale file viene usato 🧐

Se vuoi sviluppare temi per WordPress, o modificare temi esistenti, ti sarà molto utile capire e imparare subito come funziona la gerarchia dei template. È la prima cosa che bisogna imparare quando si ha a che fare con lo sviluppo di temi per WordPress.

Come funziona la gerarchia

WordPress decide quale contenuto dinamico mostrare, e quale template (o quali template) usare, attraverso la query string.

Per esempio prendiamo l’articolo che stai leggendo in questo momento:

/**
* La query string è quella parte dopo il punto interrogativo,
* in questo caso c'è un solo parametro (p) ma ce ne possono essere
* diversi, separati da &.
*/

https:chrisrodero.local/?p=79

/**
* Di solito la query string viene nascosta in modo che gli utenti,
* e i motori di ricerca, vedano un URL più "parlante" e carino,
* ma che comunque corrisponde a una query string.
*/

https:chrisrodero.local/wordpress-gerarchia-dei-template

L’URL sopra chiede che sia mostrato l’articolo (post) con ID uguale a 79, WordPress mostra l’articolo con ID uguale a 79, ma con quale template? Dipende, appunto perché esiste una gerarchia a cui WordPress si riferisce e grazie alla quale troverà un template, un file, che corrisponde alla richiesta che è stata fatta.

Sostanzialmente WordPress:

• Riceve una richiesta e quindi controlla la query string per capire quale pagina è stata richiesta (una pagina, un archivio, ecc.)
• Sceglie il template giusto dalla gerarchia dei template
• Cerca il file del template nella cartella del tema, partendo dal più specifico e usa il primo che esiste, quindi se non esiste passa al successivo indicato nella gerarchia, l’ultimo della coda è il file index.php

Ecco perchè c’è tanta libertà, a parte il file index.php (che in un tema deve quindi necessariamente esistere), sei libero di usare o non usare un certo template.

Lo schema della gerarchia dei template

Guardiamo lo schema presente nel Theme Handbook di WordPress, è piuttosto chiaro:

Ora vediamo un paio di esempi per capire meglio come WordPress segue lo schema. Trovi lo schema qui.

Abbiamo visto poco sopra che questo articolo è il post con ID 79. Quando hai cliccato sul link che ti ha portato a questo articolo WordPress ha cercato nella cartella del tema un file di template che corrispondesse al post 79, lo ha fatto in questo modo:

• Prima capisce che è stato richiesto un articolo (post) del blog, per cui cerca nella cartella del tema un file corrispondente al template personalizzato che eventualmente è stato selezionato dal pannello di amministrazione (quellochetipare.php), se esiste usa quello
• Se quellochetipare.php manca, cioè non esiste, cerca single-post.php, se esiste usa quello
• Se anche single-post.php non esiste, cerca single.php che se esiste viene usato
• Se anche single.php non esiste (!) cerca il più generico singular.php e se esiste, lo usa
• Se singular.php manca all’appello… rullo di tamburi… utilizza index.php

Adesso dovrebbe essere piuttosto chiaro come funziona la gerarchia dei template, ma facciamo un altro esempio, giusto per esserne sicuri.

Questo articolo è nella categoria WordPress, io qui non chiamo le categorie “categorie”, ma appunti, per cui l’URL è la seguente:

https:chrisrodero.local/appunti/wordpress

che corrisponde a:

https:chrisrodero.local/?cat=1

Ecco cosa succede in questo caso:

• Capisce che è una pagina di archivio, precisamente di una categoria
• Cerca nella cartella del tema il file corrispondente allo slug della categoria, in questo caso category-wordpress.php
• Se category-wordpress.php non esiste, cerca il file di template corrispondente all’ID della categoria: category-1.php
• Se category-1.php non esiste, WordPress cerca il più generico file di template category.php
• Se anche category.php non esiste, cerca archive.php
• Se infine archive.php non esiste, cerca e usa il file di template principale, ovvero index.php

In definitiva, WordPress prima cerca file di template specifici, poi va via via generalizzando, si ferma quando trova un file corrispondente, sempre seguendo la gerarchia dei template che trovi poco più sopra.

Questo comportamento ti permette di intervenire in più tempi sulla personalizzazione del tuo tema senza dover impazzire, per esempio a un certo punto potresti volere una categoria visualizzata in maniera completamente diversa dalle altre, o differenziare la pagina di risultato di una ricerca dal resto degli archivi. Sta a te decidere e strutturare il tema nel modo più comodo per le tue esigenze, attuali e future.

Impostare la Homepage e la Pagina articoli

Come probabilmente sai, una volta installato WordPress imposta come homepage del sito la pagina che mostra gli ultimi articoli del blog (effettivamente WordPress è nato e si distingue come piattaforma di blogging), ma ci da anche la possibilità di impostare una pagina a nostro piacimento.

La pagina con gli ultimi articoli del blog viene chiamata Blog posts index, quando invece parliamo della homepage del sito, parliamo della Front page (sia che questa mostri gli ultimi articoli del blog, sia che si tratti di una pagina statica); per questo motivo troviamo due opzioni riguardanti la personalizzazione della pagina principale del sito: Homepage (front page) e Pagina articoli (blog posts index).

File da usare per la Homepage e Pagina articoli

Il file di template front-page.php viene usato per mostrare la homepage del sito (sia se selezioniamo Gli ultimi articoli, sia se selezioniamo Una pagina statica). Front-page.php quindi vince, ha la precedenza, su home.php e page.php – dei quali leggerai poco sotto.

Il file di template home.php viene usato per mostrare gli ultimi articoli del blog, se non esiste WordPress userà index.php. A seconda di cosa selezioniamo in Pagina articoli, WordPress userà home.php o userà page.php (se viene selezionata una pagina statica).

Riassumendo…

front-page.php – Viene cercato e usato per primo, sia quando selezioniamo Gli ultimi articoli, sia quando scegliamo Una pagina statica.
home.php – Viene cercato e usato quando WordPress non trova front-page.php e abbiamo selezionato Gli ultimi articoli, ma anche per Pagina articoli quando selezioniamo Una pagina statica.
page.php e le sue varianti – Viene usata per Homepage quando selezioniamo Una pagina statica.
index.php – Viene usata quando selezioniamo Gli ultimi articoli ma home.php non esiste, o per Homepage quando selezioniamo Una pagina statica ma page.php non esiste.

😱

Sembra un po’ un delirio ma in realtà ci si abitua subito, e lo schema che hai visto sopra aiuta molto all’inizio per capire quale percorso WordPress prenderà. Questo modo di gestire le cose ci offre una apprezzabile liberà nel decidere come organizzare il tema che stiamo sviluppando.