Il Customizer di WordPress fornisce un'interfaccia di anteprima dal vivo per personalizzare le impostazioni del tema. A differenza delle vecchie pagine Opzioni del Tema che richiedevano il ricaricamento della pagina per vedere le modifiche, il Customizer consente agli utenti di vedere le modifiche in tempo reale. Per gli sviluppatori di temi e plugin, l'API del Customizer fornisce un modo standardizzato per aggiungere opzioni di configurazione.
Questa guida copre come aggiungere opzioni personalizzate al Customizer di WordPress, dalle impostazioni di base ai controlli avanzati con anteprima live.
Struttura del Customizer
Il Customizer ha tre livelli: pannelli (sezioni principali), sezioni (gruppi di impostazioni all'interno di un pannello) e controlli (impostazioni individuali). I pannelli organizzano le sezioni, le sezioni organizzano i controlli e i controlli consentono agli utenti di modificare le impostazioni. Ogni impostazione deve avere un controllo registrato per apparire nel Customizer.
Aggiungi tutto il codice del Customizer durante l'hook di azione customize_register. L'hook fornisce un oggetto $wp_customize che è l'API principale per aggiungere pannelli, sezioni, impostazioni e controlli.
Aggiungere Sezioni e Pannelli
Usa $wp_customize->add_panel() per creare un raggruppamento principale e $wp_customize->add_section() per creare sottogruppi all'interno dei pannelli. Ognuno accetta un ID e un array di argomenti che includono titolo, descrizione, priorità e capability. Le sezioni possono essere aggiunte senza un pannello genitore per strutture più semplici.
Usa titoli e descrizioni descrittivi e facili da usare. La descrizione appare come testo di suggerimento sotto il titolo della sezione nell'interfaccia del Customizer. Dai priorità alle tue sezioni in modo che le più importanti appaiano per prime.
Aggiungere Impostazioni e Controlli
Usa $wp_customize->add_setting() per registrare una modifica del tema. I parametri includono valore di default, tipo di trasporto ('refresh' o 'postMessage'), sanitize_callback e capability. Usa $wp_customize->add_control() per creare l'elemento UI per l'impostazione. WordPress fornisce tipi di controllo integrati: text, textarea, checkbox, select, radio, color, image e cropped_image.
Usa il parametro 'transport' per controllare come vengono applicate le modifiche. 'refresh' ricarica l'intera anteprima. 'postMessage' aggiorna l'anteprima tramite JavaScript, che è più veloce e fluido ma richiede JavaScript personalizzato per applicare le modifiche.
Anteprima Live con JavaScript
Per un'esperienza di anteprima live fluida, registra un file JavaScript di anteprima del customizer sull'hook customize_preview_init. Usa l'API wp.customize in questo file per ascoltare le modifiche alle impostazioni e applicarle all'anteprima in tempo reale. Collega le modifiche alle impostazioni con wp.customize(setting_id, function(value) { value.bind(function(to) { … }); }).
Aggiorna le proprietà CSS tramite jQuery o manipolazione diretta del DOM per un feedback immediato. Per le impostazioni di colore, imposta css(). Per le impostazioni di testo, aggiorna text(). Per i toggle di visibilità, usa show()/hide().
Tipi di Controllo Personalizzati
Quando i tipi di controllo integrati non sono sufficienti, crea tipi di controllo personalizzati estendendo WP_Customize_Control. Sovrascrivi il metodo render_content() per generare HTML personalizzato per il tuo controllo. WordPress fornisce diverse classi di controllo di base: WP_Customize_Color_Control, WP_Customize_Image_Control, WP_Customize_Upload_Control e WP_Customize_Cropped_Image_Control.
Registra la tua classe di controllo personalizzata con $wp_customize->register_control_type(). Questo dice al JavaScript del Customizer come gestire il tuo controllo personalizzato durante l'anteprima live.
Il punto fondamentale
L'API del Personalizzatore è il modo consigliato per aggiungere opzioni del tema in WordPress. Usa l'hook customize_register per aggiungere pannelli, sezioni, impostazioni e controlli. Usa postMessage per un'esperienza di anteprima live fluida. Crea tipi di controllo personalizzati per input specializzati. Il Personalizzatore fornisce un'interfaccia coerente e intuitiva che è familiare a tutti gli utenti WordPress.
