Il Theme Customizer di WordPress

Per migliorare l’esperienza utente nella gestione del tema e per evitare problemi di sicurezza a causa di codice non ottimizzato, da qualche anno è disponibile una nuova funzionalità, il Theme Customizer di WordPress, per permettere di gestire facilmente l’aspetto grafico del sito.

Da questa sezione, infatti, sarà possibile cambiare il layout del sito, abilitare alcune sezioni, caricare un logo oppure modificare i colori, a seconda del tema scelto.

Gli sviluppatori del tema possono utilizzare la Theme Customization API per integrare, al proprio tema, un pannello per la personalizzazione.

A partire dalla versione 3.4 di WordPress l’implementazione di un pannello per la personalizzazione dovrà avvenire esclusivamente utilizzando le API fornite dal CMS, nel caso desideri pubblicare il tema nella directory ufficiale di WordPress.org.

Le Theme Customization API di WordPress

L’interfaccia di gestione è composta da un pannello principale con, al suo interno, una serie di sezioni che, a loro volta, conterranno i controlli, ognuno di questi controlli permette la gestione di ogni opzione che si vuole definire e che verrà quindi memorizzata nel database.

La gestione di sezioni, impostazioni e controlli all’interno di quest’area avviene agganciando una funzione all’azione customize_register.

All’interno di questa funzione, bisogna definire ogni nuovo pannello, sezione, controllo ed impostazione da aggiungere utilizzando:

1. Il metodo $wp_customize->add_panel() per definire un nuovo pannello
2. Il metodo $wp_customize->add_section() per definire una nuova sezione
3. Il metodo $wp_customize->add_setting() per definire una nuova impostazione
4. Il metodo $wp_customize->add_control() per definire un nuovo controllo

I primi due metodi sono facoltativi,questo significa che potrai aggiungere i controlli e le impostazioni anche all’interno di sezioni già attive.

Ti consiglio di agire in questo modo solamente quando strettamente necessario e di utilizzare le sezioni di default, se possibile.

Ad esempio, per la gestione di un colore, puoi aggiungere questa impostazione all’interno della sezione colors.

Di seguito trovi la lista delle sezioni di default presenti in WordPress

1. title_tagline, ti permetterà di aggiungere una o più campi all’interno della sezione Denominazione del sito
2. colors, ti permetterà di aggiungere una o più campi all’interno della sezione Colori
3. header_image, ti permetterà di aggiungere una o più campi all’interno della sezione Immagine dell’header
4. background_image, ti permetterà di aggiungere una o più campi all’interno della sezione Immagine di sfondo
5. static_front_page, ti permetterà di aggiungere una o più campi all’interno della sezione Impostazioni Homepage

Per quanto riguarda i metodi add_setting() e add_control(), dovrai utilizzarli insieme per ogni nuovo campo che intendi aggiungere.

Come personalizzare il theme customizer di WordPress

Nell’esempio che segue, verrà definito un campo testuale dove inserire la partita iva insieme ad una textarea, per permettere la gestione del testo del copyright del sito.

Apri il file functions.php ed aggiungi:

function il_mio_tema_customize_register( $wp_customize ) {

  $wp_customize->add_panel('il_mio_tema_pannello', array(
    'title' => esc_html__( ' Il Mio Tema', 'il-mio-tema' ),
  ));
  
  $wp_customize->add_section('il_mio_tema_impostazioni_footer', array(
    'title' => esc_html__( 'Impostazioni footer', 'il-mio-tema' ),
    'panel' => 'il_mio_tema_pannello',
  ));

  $wp_customize->add_setting( 'il_mio_tema_piva', array(
    'default' => '',
    'sanitize_callback' => 'sanitize_text_field',
  ));

  $wp_customize->add_control( 'il_mio_tema_piva', array(
    'type' => 'text',
    'section' => 'il_mio_tema_impostazioni_footer',
    'label' => esc_html__('Partita IVA.', 'il-mio-tema'),
    'description' => esc_html__('Inserisci qui la tua partita iva.', 'il-mio-tema'),
  ));

  $wp_customize->add_setting( 'il_mio_tema_copyright', array(
    'default' => '',
    'sanitize_callback' => 'sanitize_textarea_field',
  ));

  $wp_customize->add_control( 'il_mio_tema_copyright', array(
    'type' => 'textarea',
    'section' => 'il_mio_tema_impostazioni_footer',
    'label' => esc_html__('Testo del footer.', 'il-mio-tema'),
    'description' => esc_html__('Inserisci qui il testo del footer.', 'il-mio-tema'),
  ));

}

add_action( 'customize_register', 'il_mio_tema_customize_register' );

I parametri che sono stati passati ai quattro metodi appena visti sono abbastanza intuitivi:

$wp_customize->add_panel('id_pannello', array(
 'title' => 'Titolo pannello',
));
  
$wp_customize->add_section('id_sezione', array(
 'title' => 'Titolo sezione',
 'panel' => 'id_pannello',
));

$wp_customize->add_setting( 'id_impostazione', array(
 'default' => 'Eventuale valore predefinito',
 'sanitize_callback' => 'Funzione di sanificazione',
));

$wp_customize->add_control( 'id_controllo', array(
 'type' => 'tipo di campo',
 'section' => 'id_sezione',
 'label' => 'Etichetta del campo',
 'description' => 'Descrizione del campo',
));

Per recuperare dal database il valore memorizzato, hai bisogno di utilizzare la funzione get_theme_mod() all’interno del footer, nel punto in cui vuoi visualizzare questi due valori.

Per visualizzare la partita iva nel footer aggiungi:

echo esc_html(get_theme_mod('il_mio_tema_piva'));

Per visualizzare il testo del copyright invece:

echo esc_html(get_theme_mod('il_mio_tema_copyright'));

Conclusione

Questi è un semplice esempio che potrai personalizzare come meglio credi e che potrà tornarti utile per aggiungere un campo per la gestione del tuo tema.

Se desideri approfondire questo argomento, puoi trovare un intero capitolo all’interno del corso Sviluppare con WordPress, disponibile su WPinProgress.

Registrandoti alla newsletter, potrai scaricare un estratto e troverai un coupon per ottenere uno sconto del 10%.

All’interno di questo corso, sono presenti esempi per i campi più comuni (input, campi numerici, url, campi per l’upload di immagini) e su come sanificare correttamente i valori prima di memorizzarli nel database.