Tema WordPress pronto per la distribuzione (Parte 4: modularizzazione, ACF e Gutenberg)

Alla fine della Parte 3 il tema gestisce ogni tipo di contenuto con il template giusto. Funziona. Quello che gli manca è tutto ciò che serve perché funzioni anche quando non ci sei tu: componenti riutilizzabili invece di codice duplicato, un editor che si comporta come il frontend, e un pacchetto che un’altra persona possa installare senza istruzioni verbali.

Questa quarta e ultima parte chiude la guida su come creare un tema WordPress da zero. Si passa dalla costruzione alla consegna.

Modularizzare con get_template_part()

Se hai seguito le parti precedenti, adesso hai single.php, page.php, archive.php e index.php, e in almeno tre di questi file c’è lo stesso blocco di markup con titolo, meta e contenuto. È il momento di estrarlo.

nome-tema/
└── template-parts/
    ├── content.php          <-- il fallback generico
    ├── content-post.php     <-- articoli
    ├── content-page.php     <-- pagine
    ├── content-excerpt.php  <-- voce di elenco negli archivi
    ├── content-none.php     <-- nessun risultato
    └── card.php             <-- componente riutilizzabile

La chiamata vista nella Parte 2 continua a valere, e il meccanismo di fallback è ciò che rende questa struttura conveniente:

get_template_part( 'template-parts/content', get_post_type() );

Un solo file specifico quando serve, uno generico per tutto il resto. Il giorno in cui il cliente chiede un custom post type “Progetti” con una scheda diversa, crei content-progetto.php e nessun template esistente va toccato.

Sul quando estrarre vale una regola sola: quando lo stesso markup compare in due file. Prima è astrazione prematura — un frammento usato una volta è solo un file in più da aprire per capire cosa succede.

Rendere il tema compatibile con l’editor a blocchi

Anche un tema classico deve andare d’accordo con Gutenberg, perché è l’editor con cui il contenuto viene scritto. Il minimo sindacale sono quattro dichiarazioni in functions.php.

function nometema_supporto_blocchi() {
    add_theme_support( 'wp-block-styles' );
    add_theme_support( 'align-wide' );
    add_theme_support( 'responsive-embeds' );

    add_theme_support( 'editor-styles' );
    add_editor_style( 'assets/css/editor.css' );
}
add_action( 'after_setup_theme', 'nometema_supporto_blocchi' );

• wp-block-styles carica gli stili di base dei blocchi del core. Senza, blocchi come citazione, separatore e tabella arrivano quasi nudi e devi rifarne il CSS da zero.
• align-wide attiva le opzioni di allineamento “largo” e “a tutta larghezza”. Va accompagnato dal CSS che le gestisce: dichiararlo e non stilizzarlo produce blocchi che sforano il contenitore.
• responsive-embeds fa in modo che i video incorporati si adattino alla larghezza disponibile invece di mantenere la dimensione originale.
• editor-styles più add_editor_style() è la coppia che fa apparire il contenuto nell’editor come apparirà sul sito. Sono due chiamate distinte e servono entrambe: la prima dichiara il supporto, la seconda indica il foglio di stile da caricare.

Quest’ultimo punto è quello che si nota di più nell’uso quotidiano. Un editor che mostra un font e una larghezza diversi dal frontend costringe chi scrive a pubblicare, guardare, tornare indietro e correggere, ogni volta.

La scelta della base di partenza pesa anche qui: se stai valutando quale starter theme adottare per un tema classico, tieni conto di quanto ciascuno è già predisposto per l’editor a blocchi.

theme.json: gli stili globali, anche in un tema classico

C’è un equivoco diffuso su theme.json: che serva solo ai block theme. Non è così. Un tema classico come quello che stiamo costruendo può usarlo, e ne guadagna parecchio, perché è il punto in cui si dichiarano una volta sola i colori, le dimensioni del testo e le larghezze di layout che l’editor deve proporre.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "720px",
      "wideSize": "1140px"
    },
    "color": {
      "custom": false,
      "palette": [
        { "slug": "testo",   "color": "#1a1a1a", "name": "Testo" },
        { "slug": "accento", "color": "#0b5ed7", "name": "Accento" },
        { "slug": "chiaro",  "color": "#f4f4f5", "name": "Sfondo chiaro" }
      ]
    },
    "typography": {
      "fluid": true,
      "customFontSize": false
    }
  }
}

Il file va nella root del tema. La versione 3 dello schema è quella introdotta con WordPress 6.6; se devi supportare installazioni più vecchie, usa "version": 2.

Due chiavi meritano attenzione perché risolvono un problema concreto dei siti consegnati ai clienti. "custom": false nei colori rimuove il selettore di colore libero dall’editor: restano solo i colori della palette. Stessa cosa fa "customFontSize": false per le dimensioni del testo. Sono le due righe che impediscono che sei mesi dopo la consegna il sito abbia quattordici sfumature di blu e titoli da 43 pixel. Non è una limitazione imposta all’utente per rigidità: è ciò che mantiene un progetto coerente quando ci lavorano più persone.

appearanceTools: true è invece una scorciatoia: attiva in un colpo solo i controlli di bordo, spaziatura, altezza di riga e colore del testo nei blocchi, senza doverli abilitare uno per uno.

ACF: quando serve davvero e quando no

Advanced Custom Fields aggiunge campi personalizzati a qualsiasi tipo di contenuto e li rende compilabili dal backend con un’interfaccia comprensibile a chiunque. È lo strumento più usato dagli sviluppatori di temi su misura, ed è anche uno di quelli che si aggiungono più spesso senza chiedersi se servano.

Serve quando il contenuto è strutturato e va compilato da altri: il prezzo di un servizio, gli orari di apertura, l’elenco ripetibile dei membri di un team, la scheda tecnica di un prodotto. Sono dati che devono finire in punti precisi del template, non dentro il flusso di testo, e che chi gestisce il sito deve poter cambiare senza toccare l’editor visuale.

Non serve quando l’editor a blocchi fa già il lavoro. Molto di ciò per cui si usava ACF Flexible Content — costruire sezioni componibili in una pagina — oggi si fa con i block pattern, che sono nel core, non aggiungono una dipendenza e restano modificabili anche se il tema cambia. Vale per pezzi di pagina di ogni dimensione, fino a una barra di annunci costruita a blocchi.

Usarlo nel template senza rendere il tema fragile

<?php
if ( function_exists( 'get_field' ) ) {

    $prezzo = get_field( 'prezzo_servizio' );

    if ( $prezzo ) {
        printf(
            '<p class="prezzo">%s</p>',
            esc_html( $prezzo )
        );
    }
}
?>

Il controllo function_exists( 'get_field' ) è la riga che separa un tema robusto da uno che si rompe. Se il tema chiama get_field() senza protezione e il plugin viene disattivato — un aggiornamento andato male, un cliente che fa pulizia tra i plugin, un trasferimento su un altro server — il risultato è un errore fatale di PHP e il sito offline. Con il controllo, la sezione semplicemente non compare.

Nota anche l’esc_html() attorno al valore: un campo personalizzato è input che arriva dal database, e va trattato come tale in uscita. Vale per ogni valore stampato in un template — è lo stesso principio della checklist sicurezza WordPress, applicato al codice invece che alla configurazione.

Quale ACF stai installando

Un dettaglio pratico che vale la pena conoscere prima di scrivere una dipendenza nel README. Nell’ottobre 2024 WordPress.org ha preso in gestione la scheda del plugin nella directory ufficiale, rinominando quella versione Secure Custom Fields. ACF continua a essere sviluppato e distribuito dai suoi autori dal sito ufficiale, versione gratuita compresa.

In pratica: cercando “Advanced Custom Fields” dal pannello plugin ottieni Secure Custom Fields, mentre scaricando dal sito degli autori ottieni ACF. Le due versioni condividono l’origine e gran parte delle funzioni, ma sono progetti ormai separati. Se il tuo tema dipende dai campi personalizzati, scrivi nella documentazione quale dei due hai usato e con quale versione l’hai testato: è il tipo di informazione che, senza, costa un pomeriggio a chi riprende il progetto.

Ricorda infine che i campi ripetibili, il contenuto flessibile, la galleria e le pagine di opzioni globali sono funzioni della versione a pagamento. Un tema che li usa richiede una licenza a chi lo installa, e va detto prima, non dopo.

Full Site Editing: quando ha senso e quando no

Il Full Site Editing, introdotto con WordPress 5.9, permette di modificare header, footer e template direttamente dall’editor a blocchi, senza codice. È la differenza che si sente di più proprio sull’header, dove modifiche che in un tema classico richiedono un file si fanno da un pannello. Un tema che lo supporta si chiama block theme, e non è una variante del tema classico: è un’altra cosa.

Il discrimine tecnico è preciso: è la presenza di templates/index.html che fa considerare il tema un block theme. Sotto quella soglia resti un tema classico, e puoi comunque adottare theme.json, la palette globale e gli stili dei blocchi — è l’approccio ibrido, ed è quello che consiglio nella maggior parte dei casi: prendi la parte utile del nuovo sistema senza rinunciare al controllo sul PHP.

Il FSE completo conviene quando il sito lo gestirà qualcuno che vuole cambiare il layout senza chiamarti. Non conviene quando il tema deve integrarsi con logica applicativa, sistemi esterni o campi personalizzati complessi: lì il PHP serve ancora, e piegare i blocchi a farlo costa più di quanto renda.

Se decidi di provare, il plugin Create Block Theme permette di generare ed esportare un block theme direttamente dall’editor: è il modo più veloce per vedere com’è fatto uno di questi temi senza costruirlo a mano.

Preparare il tema alla consegna

Che il tema vada a un cliente, su un repository o su un marketplace, i passaggi sono gli stessi. Cambia solo il livello di severità di chi lo riceve.

Pulizia e documentazione

• Elimina file inutilizzati, CSS morto, script scollegati, var_dump() e funzioni di debug dimenticate.
• Riattiva WP_DEBUG e naviga tutto il sito: nessun avviso, nessun notice, nessun deprecated. I deprecated in particolare sono il tuo preavviso di rottura al prossimo aggiornamento di WordPress.
• Scrivi un readme.txt nella root con nome del tema, versione, requisiti minimi di WordPress e PHP, dipendenze da plugin, istruzioni di installazione e changelog. Non è burocrazia: è la risposta alle domande che ti verranno fatte comunque, scritta una volta sola.
• Verifica che screenshot.png sia aggiornato e mostri il tema com’è ora, non com’era a metà lavoro.

Traduzioni

Se hai seguito la guida, ogni stringa visibile è già passata da __(), _e() o esc_html_e() con il text domain del tema. Manca il pezzo che le rende effettivamente traducibili: la cartella languages/ con il file .pot, e la dichiarazione in functions.php.

load_theme_textdomain(
    'nome-tema',
    get_template_directory() . '/languages'
);

Il file .pot si genera con Poedit o con wp i18n make-pot da WP-CLI. Ricontrolla che il text domain sia identico in tutti e tre i posti — style.css, le funzioni PHP e questa chiamata: un refuso qui non genera errori, semplicemente nessuna traduzione viene caricata.

Validazione

• Theme Check: il plugin ufficiale che verifica il tema contro le linee guida di WordPress.org. Anche se non pubblicherai lì, i controlli che fa sono buoni controlli.
• Theme Unit Test: i contenuti di prova ufficiali, con tutti i casi limite — titoli lunghissimi, immagini di ogni allineamento, commenti annidati, liste dentro le citazioni. Sono gli stessi casi che rompono il tema una settimana dopo la consegna.
• Lighthouse su una pagina reale per performance, accessibilità e SEO di base.
• Prova su browser diversi, desktop e mobile, con particolare attenzione al menu e ai moduli.

Il pacchetto ZIP, che va fatto in un modo preciso

Qui correggo un’indicazione che una versione precedente di questo articolo dava al contrario, ed è un errore che costa un’installazione fallita al primo tentativo.

Il file ZIP deve contenere la cartella del tema, non i suoi file sciolti. Aperto l’archivio devi vedere una sola cartella, nome-tema/, e dentro quella style.css, index.php e tutto il resto. È la struttura che WordPress.org richiede ed è l’unica che garantisce che la directory installata mantenga il nome che hai scelto — nome che non è cosmetico, perché coincide con il text domain e perché è quello a cui un eventuale child theme si aggancia con Template:.

nome-tema.zip
└── nome-tema/
    ├── style.css
    ├── index.php
    ├── functions.php
    └── ...

Prima di consegnare, fai la prova che conta davvero: installa lo ZIP su un’installazione WordPress pulita, come se fossi il destinatario. È l’unico modo per accorgersi di una dipendenza che avevi solo tu, di un percorso assoluto rimasto nel codice o di un file escluso per sbaglio dal .gitignore.

Un’ultima nota sulla licenza: WordPress è rilasciato sotto GPL, e un tema che ne usa le funzioni eredita quel vincolo. Se lo pubblichi, la licenza dichiarata in style.css deve essere compatibile con la GPL, e questo vale anche per font, icone e librerie che includi nel pacchetto.

La checklist prima del rilascio

Le voci su titoli, immagini e struttura hanno una controparte lato contenuto: sono gli stessi controlli della checklist SEO on-page per WordPress, che vale la pena passare sulle prime pagine pubblicate con il tema nuovo. Vale lo stesso per la riga «Accessibilità» della tabella: skip link, landmark, focus e contrasto sono quattro dei ventiquattro controlli di un audit di accessibilità, e conviene passarli sul tema prima della consegna piuttosto che sul sito del cliente dopo.

La guida è finita: cosa hai costruito

Quattro parti, da una cartella vuota a un pacchetto installabile.

• Parte 1 — File base e struttura: style.css, index.php, le prime funzioni, l’attivazione e il debug dei primi errori.
• Parte 2 — Template file e gerarchia: header, footer, sidebar, menu, e la regola con cui WordPress sceglie i file.
• Parte 3 — Template specifici e loop: single.php, page.php, archive.php, 404.php, WP_Query e pre_get_posts.
• Parte 4 — Modularizzazione e distribuzione (questa pagina): frammenti riutilizzabili, editor a blocchi, theme.json, campi personalizzati e consegna.

Quello che ti resta non è solo un tema: è sapere dove mettere le mani. Quando un sito WordPress fa qualcosa di inatteso, la differenza tra chi ha costruito un tema da zero e chi no è che il primo sa se il problema è nel tema, nella query o nel plugin — e di solito lo capisce in cinque minuti.

Domande frequenti

Se ti serve una mano sull’ultimo miglio

La parte più noiosa di un tema è sempre l’ultima: la validazione, le traduzioni, i casi limite del Theme Unit Test, il pacchetto che deve installarsi al primo colpo su una macchina che non è la tua. Se hai un tema quasi pronto e vuoi che qualcuno lo porti oltre la linea, sviluppo temi e plugin WordPress su misura: posso occuparmi della finitura, della revisione del codice o dell’intero progetto.