Il template a blocchi non viene applicato? Parti dal database

Il tuo file di template viene quasi certamente ignorato perché sta vincendo una copia nel database. Nel momento in cui apri un template nell’Editor del sito e premi Salva, WordPress scrive un record post wp_template, e da lì in poi serve quel record al posto del file .html nella cartella del tema — quindi ogni modifica che fai al file dopo quel momento è invisibile sul front end. Cancellare quel record è la soluzione, ed è la prima cosa da verificare prima di toccare la gerarchia, il nome del file o la cache.

Verifica che la copia nel database esista

Vai su Aspetto → Editor → Template. Qualsiasi template che WordPress sta servendo dal database è segnalato nell’elenco: a seconda della tua versione di WordPress il badge dice “Personalizzato” oppure il template compare sotto un filtro “Personalizzati”. Quel badge è tutta la risposta. Se c’è, il tuo file non viene usato.

Puoi verificare la stessa cosa da riga di comando, che è più veloce e funziona anche quando l’Editor del sito fa i capricci:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Ogni riga è un override nel database. Il post_name corrisponde allo slug del template, quindi una riga chiamata single sta oscurando templates/single.html.

Un dettaglio che manda fuori strada: questi record sono legati a un tema tramite un termine di tassonomia, non tramite un percorso. Se rinomini la cartella del tuo tema, i template salvati restano nel database ma smettono di corrispondere al tema attivo, e il sito ricade di colpo sui file. Sembra “le mie personalizzazioni sono sparite” invece di “il mio file viene ignorato” — stesso meccanismo, sintomo opposto.

Cancellalo

Nell’Editor del sito, apri il menu di opzioni del template (i tre puntini accanto) e scegli Azzera personalizzazioni — in alcune versioni la voce si chiama Ripristina. Questo elimina il record nel database e il controllo torna al file su disco.

Se il menu offre Elimina invece di Azzera personalizzazioni o Ripristina, quel template esiste soltanto nel database e non ha nessun file dietro. Eliminarlo rimuove del tutto il template e WordPress scende lungo la gerarchia.

Da WP-CLI, usando un ID preso dall’elenco qui sopra:

wp post delete 482 --force

Sii onesto con te stesso sul costo: azzerare le personalizzazioni scarta in modo permanente tutto ciò che hai costruito nell’Editor del sito per quel template, e non si può annullare. Se nella versione dell’Editor del sito c’è del lavoro vero, copiane prima il markup a blocchi — apri il template nell’editor, passa alla vista codice e incolla il risultato nel tuo file .html. Così il file diventa la fonte di verità e non perdi niente.

Come WordPress sceglie un template

I temi a blocchi usano la stessa logica di gerarchia dei temi classici, solo con file .html in templates/ invece di file .php nella radice del tema. WordPress procede dal più specifico al meno specifico e usa il primo file che esiste.

Cosa si sta visualizzando	Ordine di controllo
Un singolo articolo	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Una pagina	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Un archivio di categoria	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Un tipo di contenuto personalizzato	single-{post-type}.html → single.html → singular.html → index.html
La pagina 404	404.html → index.html

Due cose scavalcano tutto questo. La prima, il record nel database descritto sopra. La seconda, un template assegnato direttamente a un articolo o a una pagina: apri l’editor del contenuto, cerca il pannello Template nella barra laterale e controlla se lì è selezionato qualcosa di specifico. Un’assegnazione esplicita batte la gerarchia ogni volta, ed è invisibile se non vai a cercarla.

I template basati sullo slug sono fragili in un modo che vale la pena interiorizzare. page-about.html corrisponde solo finché lo slug della pagina è about. Rinomina la pagina in about-us e il template smette di applicarsi senza avvisi e senza errori.

Template contro parte di template

Un template renderizza una vista intera ed è scelto dalla gerarchia. Una parte di template è un frammento — intestazione, piè di pagina, barra laterale — che i template richiamano. Le parti stanno in parts/, i template stanno in templates/, e nel database sono salvati separatamente come record wp_template_part.

La confusione tipica: modifichi l’intestazione e la modifica compare su pagine che non volevi toccare. È il comportamento corretto. Una sola parte è condivisa da ogni template che la include. Se vuoi un’intestazione diversa su un solo template, ti serve un secondo file di parte e un template che lo richiami — modificare quella condivisa non ti darà mai una variazione per singolo template.

Capita anche il contrario. Metti il layout di una pagina intera dentro parts/ e ti chiedi perché la gerarchia non lo raccolga mai. Le parti non sono affatto candidate nella gerarchia: niente verrà mai instradato direttamente su di loro.

Nomi dei file e posizione

Controlla queste cose prima di ipotizzare qualcosa di più esotico:

• La cartella è templates/, al plurale, nella radice del tema. Non template/, non block-templates/. block-templates/ era il nome corretto all’epoca del plugin Gutenberg, prima che i temi a blocchi arrivassero nel core, e parecchi tutorial lo mostrano ancora — nelle versioni attuali di WordPress non funziona.
• Le parti di template vanno in parts/, non in template-parts/ (che è la convenzione dei temi classici per i partial PHP).
• L’estensione è .html. Un file .php dentro templates/ viene ignorato.
• I nomi dei file sono in minuscolo e usano i trattini. single-Post.html o single_post.html non corrisponderanno. Su un filesystem che non distingue maiuscole e minuscole come quello di macOS la cosa funziona in locale e si rompe su un server Linux — il classico fallimento “sulla mia macchina funziona”.
• templates/index.html deve esistere. Senza, WordPress non classifica il tema come tema a blocchi e l’Editor del sito potrebbe non comparire affatto.
• Se stai lavorando in un tema child, i suoi template hanno la priorità su quelli del parent. Un file dimenticato nel tema child batterà in silenzio il file del parent che stai modificando.

I template personalizzati che devono essere selezionabili nell’editor dei contenuti vanno anche dichiarati in theme.json sotto customTemplates, indicando il nome base del file, un titolo leggibile e i tipi di contenuto a cui si applica. Senza quella voce il file esiste ma non compare mai nel pannello Template.

Cache — controllala per ultima

La cache è una cosa reale, ma è la causa meno probabile, e partire da lì è il modo migliore per perdere un pomeriggio.

Svuota la cache di pagina e, se usi una cache oggetti persistente come Redis o Memcached, svuota anche quella: i risultati della risoluzione dei template possono restare lì. Poi ricarica bypassando la cache del browser.

Cosa non aiuterà: svuotare OPcache. I template a blocchi sono file .html e non vengono mai compilati da PHP, quindi OPcache non c’entra nulla. Se una volta ti è sembrato che svuotare OPcache risolvesse il problema, nello stesso momento era cambiato qualcos’altro.

Ancora bloccato?

Se non c’è nessun record nel database, il nome del file è corretto, non c’è nessuna assegnazione esplicita di template sul contenuto e le cache sono già state svuotate, guarda ai plugin. Qualsiasi cosa filtri la risoluzione dei template — un page builder, un plugin di membership, un plugin multilingua, un LMS — può sostituire il proprio template alla fine della richiesta. Passa a un tema a blocchi predefinito e prova con i plugin disattivati, poi riattivali uno alla volta.

E se il template viene applicato ma renderizza vuoto, quello è un problema diverso: verifica che il markup a blocchi nel file sia valido, perché un commento di blocco malformato può portare l’editor a rimuovere il contenuto in silenzio invece di segnalare un errore.