Guida al Customizer dei temi WordPress

Cos'è il Customizer dei temi WordPress

Il sistema di personalizzazione di WordPress noto come Theme Customizer è uno strumento integrato che consente la personalizzazione visiva dell'aspetto del sito con anteprima delle modifiche in tempo reale. Invece di modificare il codice del tema o usare pagine di impostazioni separate, il Customizer offre un'interfaccia unificata in cui vedi gli effetti di ogni modifica prima di salvarla. Vi si accede da Aspetto, Personalizza nel pannello di amministrazione. Se hai appena iniziato, consulta la nostra guida alla configurazione di WordPress. Se non hai ancora installato WordPress, leggi la nostra guida passo passo a WordPress oppure accedivi aggiungendo /wp-admin/customize.php all'URL del tuo sito.

Il Customizer è stato introdotto in WordPress 3.4 e da allora è stato continuamente migliorato a ogni nuova versione. Usa AJAX per la comunicazione con il server e JavaScript per l'anteprima in tempo reale, offrendo un'esperienza fluida senza ricaricamenti della pagina. Tutti i temi core di WordPress e la maggior parte dei temi di qualità usano il Customizer per le proprie impostazioni.

Anatomia del Customizer

Pannelli, sezioni e controlli

Il Customizer è organizzato in una struttura gerarchica a tre livelli. I pannelli sono la categoria più ampia e servono a raggruppare sezioni correlate, ad esempio un pannello Header contenente sezioni per logo, navigazione e barra superiore. Le sezioni sono gruppi di controlli correlati, ad esempio una sezione Colori contenente controlli per i colori di sfondo, testo e link. I controlli sono singoli elementi di input per le impostazioni, come selettori di colore, menu a tendina, campi di testo e controlli per il caricamento delle immagini.

Impostazioni e transport

Ogni controllo è collegato a un'impostazione (Setting) che definisce dove viene memorizzato il valore e come viene applicato. Un'impostazione può memorizzare il proprio valore nel database come theme_mod oppure come option. Il parametro Transport determina come vengono applicate le modifiche: refresh ricarica il frame dell'anteprima a ogni modifica, mentre postMessage usa JavaScript per l'applicazione istantanea senza ricaricamento. PostMessage è molto più veloce e offre un'esperienza utente migliore, ma richiede codice JavaScript aggiuntivo per ogni controllo.

Registrare sezioni e controlli

Aggiungere una sezione

Le sezioni si registrano in functions.php usando l'hook customize_register. Chiami il metodo add_section di $wp_customize con un ID univoco e un array di parametri che include title per il nome della sezione, description per il testo visualizzato in cima alla sezione, priority per l'ordine di visualizzazione, dove numeri più bassi significano posizione più alta, e panel se vuoi collocare la sezione all'interno di un pannello. Un esempio è la creazione di una sezione di impostazioni dell'header con il titolo Impostazioni Header, una descrizione della funzione e priorità 30.

Aggiungere impostazioni e controlli

Per ogni impostazione, registra prima l'impostazione con il metodo add_setting, dove specifichi il valore predefinito, il tipo di transport e la funzione sanitize_callback per la validazione dell'input. Poi aggiungi un controllo con il metodo add_control che definisce il tipo di controllo, l'etichetta, la sezione a cui appartiene e la priorità. WordPress offre tipi di controllo integrati tra cui text per campi di testo, textarea per testo su più righe, checkbox per caselle di conferma, radio per pulsanti di opzione, select per menu a tendina, dropdown-pages per la selezione delle pagine e number per campi numerici.

Controlli avanzati

WordPress dispone di controlli avanzati integrati per tipi di dati specifici. WP_Customize_Color_Control visualizza un selettore di colore con valore esadecimale, WP_Customize_Image_Control consente di caricare o selezionare un'immagine dalla libreria multimediale, WP_Customize_Cropped_Image_Control aggiunge la possibilità di ritagliare le immagini alle dimensioni desiderate e WP_Customize_Media_Control è un controllo universale per qualsiasi tipo di media. Per usare questi controlli, istanziali direttamente invece di chiamare add_control con un type, perché sono classi PHP con parametri specifici.

Anteprima in tempo reale con postMessage

Il lato PHP

Per abilitare l'anteprima in tempo reale senza ricaricamento, imposta il parametro transport su postMessage nella chiamata add_setting. Questo dice al Customizer di usare JavaScript per applicare le modifiche invece di ricaricare l'intera pagina. Nel codice di output del tema, usa la funzione get_theme_mod per leggere il valore salvato e applicarlo all'elemento appropriato tramite CSS inline o classe.

Il lato JavaScript

Crea un file JavaScript che viene caricato solo nell'anteprima del Customizer usando l'hook customize_preview_init per accodare lo script. Nello script, usa l'API wp.customize per intercettare le modifiche alle impostazioni e applicarle agli elementi dell'anteprima. Per cambiare un colore, ad esempio, intercetti le modifiche all'impostazione header_bg_color e aggiorni la proprietà CSS dell'elemento corrispondente. Per cambiare il testo, modifichi l'innerHTML dell'elemento. PostMessage offre un feedback visivo istantaneo senza ritardi, il che migliora notevolmente l'esperienza utente.

Selective Refresh

Il Selective Refresh è un approccio ibrido introdotto in WordPress 4.5 che aggiorna solo una parte della pagina invece dell'intera pagina. Registri una partial con il metodo add_partial, dove specifichi un selettore, ovvero il selettore CSS dell'elemento da aggiornare, e una funzione PHP render_callback che genera nuovo HTML per quell'elemento. Questo è ideale per elementi complessi il cui aspetto dipende da più impostazioni, perché è più semplice che scrivere JavaScript per ogni possibile combinazione di modifiche e più veloce di un ricaricamento completo della pagina.

Validazione e sanificazione

Sanitize callback

Ogni impostazione deve avere una funzione sanitize_callback che pulisce e valida l'input dell'utente prima di salvarlo nel database. WordPress offre funzioni integrate per i casi più comuni tra cui sanitize_text_field per i campi di testo, sanitize_email per gli indirizzi email, sanitize_hex_color per i colori esadecimali, absint per gli interi positivi, esc_url_raw per gli URL e wp_kses_post per i contenuti HTML con tag consentiti. Non memorizzare mai l'input dell'utente senza sanificazione, perché ciò espone il sito ad attacchi XSS e di altro tipo.

Validation callback

Da WordPress 4.6 esiste validate_callback, che può restituire un oggetto WP_Error con un messaggio di errore mostrato all'utente nell'interfaccia del Customizer. A differenza di sanitize_callback, che corregge silenziosamente i valori non validi, validate_callback notifica esplicitamente all'utente che l'input non è valido. Puoi ad esempio verificare che un URL sia valido, che un numero rientri nell'intervallo consentito o che il testo non superi la lunghezza massima e mostrare un messaggio di errore appropriato.

Pannelli e controlli personalizzati

Creare un controllo personalizzato

Per esigenze che i controlli integrati non coprono, puoi creare un controllo personalizzato estendendo la classe WP_Customize_Control. Esegui l'override del metodo render_content per definire l'HTML del controllo e del metodo enqueue per includere CSS e JavaScript specifici del controllo. Esempi di controlli personalizzati sono uno slider con range e visualizzazione del valore corrente, un interruttore toggle al posto di una checkbox, un selettore di Google Fonts con anteprima del font, un controllo di ordinamento degli elementi tramite drag-and-drop e un controllo per la configurazione del layout con visualizzazione grafica delle opzioni.

Creare un pannello

I pannelli si registrano con il metodo add_panel e sono utili per organizzare molte sezioni in gruppi logici. Un tema con molte impostazioni potrebbe avere pannelli per header, footer, blog, colori, tipografia e layout. Ogni pannello contiene più sezioni e ogni sezione più controlli. Non esagerare con la profondità della gerarchia, perché agli utenti non piace cliccare attraverso troppi livelli per raggiungere l'impostazione desiderata.

Impostazioni condizionali

Il parametro active_callback in sezioni e controlli consente di mostrare i controlli solo quando determinate condizioni sono soddisfatte. Ad esempio, il controllo del colore dell'header viene mostrato solo se l'opzione mostra header è abilitata, le impostazioni del blog vengono mostrate solo nella pagina del blog nell'anteprima e le opzioni dello slider vengono mostrate solo nella home page. Questo rende l'interfaccia più pulita e meno confusa, perché gli utenti vedono solo le impostazioni rilevanti per il contesto attuale.

Integrazione con i temi a blocchi

Con l'introduzione del Full Site Editing in WordPress 5.9, il Customizer ha ottenuto un'alternativa sotto forma di Site Editor. I temi a blocchi usano un file theme.json per definire le impostazioni invece della Customizer API. Tuttavia, i temi classici e i temi ibridi continuano a usare attivamente il Customizer, che rimane una parte importante dell'ecosistema WordPress. Se stai sviluppando un tema classico, il Customizer è ancora il modo consigliato per implementare le impostazioni del tema con anteprima in tempo reale.

Buone pratiche

• Usa il transport postMessage quando possibile per l'anteprima istantanea delle modifiche
• Implementa sempre sanitize_callback per ogni impostazione senza eccezioni
• Organizza le impostazioni in modo logico in sezioni e pannelli per facilitare la navigazione
• Usa valori predefiniti sensati in modo che il sito appaia bene senza alcuna personalizzazione
• Aggiungi descrizioni a sezioni e controlli affinché gli utenti capiscano cosa fa ciascuna impostazione
• Testa l'anteprima in tempo reale su pagine diverse, perché il comportamento può variare
• Usa active_callback per mostrare i controlli solo quando sono rilevanti
• Non aggiungere troppe impostazioni, perché confonde gli utenti e complica la manutenzione

Conclusione

Il Customizer dei temi WordPress è uno strumento potente per creare un'interfaccia intuitiva di personalizzazione del tema con anteprima in tempo reale. La gerarchia di pannelli, sezioni e controlli consente una visualizzazione organizzata delle impostazioni, il transport postMessage offre feedback visivo istantaneo e la sanificazione e la validazione garantiscono la sicurezza dei dati. Su hosting WordPress ottimizzato, tutte le funzionalità del Customizer sono supportate con un server ottimizzato per l'applicazione rapida delle modifiche e il funzionamento affidabile del sito.