Theme Customizer API di WordPress

Fai Personalizzare il tuo Tema con il Customizer

Tempo fa ti avevo parlato di quanto ritengo stupido offrire dei pannelli di controllo sul tema che rilasciamo ma non tanto perché credo che sia una pratica sbagliata, piuttosto perché ritengo che l'utente finale possa confondersi maggiormente.

Oggi invece mi trovo a parlarti del pannello di modifica, il theme customizer, che ad oggi è integrato in tutte le installazioni WordPress e che permette la modifica dei temi compatibili.

Ti stai forse chiedendo il motivo di questo mio cambio d’opinione?

Beh, per prima cosa chiariamo il fatto che non stiamo parlando di un cambio d’opinione; io continuo a ritenere i pannelli di modifica dei temi proprietari una gran perdita di tempo e una sfida per l’utente medio che desidera personalizzare il proprio tema. Il fatto è che da quando, nella versione 3.4, WordPress ha introdotto il suo pannello ufficiale, dal mio punto di vista le cose sono cambiate molto.

Continuando a leggere questo articolo scoprirai che cosa è cambiato e sopratutto come rendere compatibile il tuo tema a queste nuove modifiche. Se invece sei interessato ad una conoscenza completa di queste API ti consiglio di tenere d’occhio skillsAndMore perché nei prossimi mesi apparirà una guida completa!

Perché ti consiglio l’uso del Customizer

Prima ancora di andare a scoprire come sia possibile rendere il tuo tema compatibile con questa funzionalità, lasciami introdurre le mie motivazioni.

Dato che mi ritengo uno sviluppatore WordPress a tutti gli effetti, riconoscendo la sua importanza nel mio lavoro, ho sempre preferito seguire le sue logiche nella creazione delle mie applicazioni perché in questo modo posso dormire sonni tranquilli ogni volta che un mio cliente esegue un aggiornamento.

E’ vero, molto probabilmente se avessi utilizzato del codice PHP standard avrei potuto “fare prima” ma poi mi sarei perso tutti i benefici che si ottengono nel rispettare le strutture logiche della piattaforma che stiamo utilizzando.

Ad esempio, sviluppare con del codice PHP puro (quindi senza usare le logiche, i metodi e le altre soluzioni che WordPress ci mette a disposizione), in molti casi crea dei problemi nelle ottimizzazioni lato cache dei nostri progetti mentre altre volte rende la vita difficile agli sviluppatori che verranno dopo di noi (anche se saremo noi stessi!).

Per questo motivo preferisco utilizzare gli standard WordPress, in fin dei conti sono i suoi standard e in un certo modo mi sembra anche di rispettare maggiormente questa piattaforma e le migliaia di persone che lavorano al suo interno.

Oltre a questo ci sono altri motivi, più pratici, per i quali ti consiglio di rendere il tuo tema compatibile con questa funzionalità.

Per prima cosa, renderai la vita del tuo utente ancor più semplice dato che ogni tema che si troverà a personalizzare rappresenterà la stessa grafica ed esperienza utente ma per lo sviluppatore WordPress che è in te c’è da dire che ti troverai parte del lavoro già fatto e pronto soltanto ad adattarsi alle tue personalizzazioni.

Se vogliamo dire alcune figate di questa funzionalità, posso anticiparti che con la lettura di questo articolo scoprirai come sia possibile far gestire direttamente a WordPress il salvataggio e il richiamo delle impostazioni che il nostro utente avrà modificato e nonostante questo ci sono funzionalità AJAX che permetteranno di avere un feedback diretto dalle modifiche che vogliamo applicare.

Non ti dovrai ammazzare di lavoro nella creazione delle singole chiamate AJAX, grazie alle API che ti vengono messe a disposizione potrai tranquillamente sfruttare il codice nativo per cambiare il colore, ed applicare tutte le altre modifiche che metterai a disposizione del tuo utente, senza la necessità di salvare le nuove impostazioni!

Fin ora sembra tutto bello e utile ma per poter utilizzare al meglio le Theme Customizer API bisogna per prima cosa conoscerne i concetti che ne stanno alla base, ecco quello che faremo nella nostra prossima sezione.

Come Ragionano le Theme Customizer API

Anche se non conosci ancora i vari elementi che ci permettono di creare queste funzionalità ho deciso di inserirti questa immagine per farti avere un veloce riferimento grafico rispetto a quello che ti andrò a spiegare a breve.

Caratteristiche del Theme Customizer WordPress

Per comprendere al meglio le Theme Customizer API per prima cosa bisogna capire che esiste un ordine e un’armonia che dobbiamo rispettare se vogliamo ottenere il meglio da questa funzionalità. Ebbene diciamo subito che per aggiungere una nostra impostazione abbiamo bisogno di inserire i seguenti elementi:

  • Section la sezione ci permette di creare una nuova voce all’interno della colonna del nostro customizer. Grazie a questo elemento potremo inserire le varie impostazioni che vogliamo rendere personalizzabili da parte dell’utente;
  • Setting le impostazioni invece sono quelle funzionalità che ci permettono di valutare il dato inserito da parte dell’utente. Tieni bene a mente che questo elemento non si mostrerà fintanto che non creiamo un controllo;
  • Control ovvero il codice che ci permetterà di dire a WordPress quale tipo di elemento possiamo creare e come questo dovrà essere visualizzato all’interno della sezione che stiamo creando.

A questa lista manca soltanto il concetto di Panel che al momento non voglio trattare perché è semplicemente un wrapper delle sezioni che andremo a creare. Per capire meglio di che cosa sto parlando ecco un esempio di codice che voglio mostrarti:

Come dovresti comprendere da questo codice, tutte le impostazioni che vogliamo inserire all’interno del nuovo Customizer dovranno essere presenti all’interno di un’unica funzione PHP che dovrà essere richiamata grazie all’action Hook customize_register; questo è il codice che sta alla base per inserire nuove impostazioni grazie al Theme Customizer API.

Ora conosci la logica generale e hai scoperto che i vari metodi add-*() richiedono lo stesso numero di parametri, uno che ne identifica l’id mentre l’altro permette di inserire una serie di impostazioni. Prima di tuffarci nella creazione di settings & controls ho bisogno di mostrarti come sia possibile creare una sezione e quali opzioni questa accetta.

La Creazione di una Sezione

Come ti dicevo prima, le sezioni sono quegli elementi che ci permettono di fornire uno spazio alle opzioni che vogliamo inserire nel nostro tema e per questo motivo possiamo impostare diverse opzioni.

Come visto precedentemente questa è la funzione base che ci permette di creare una nuova sezione all’interno del Customizer offerto da WordPress. Ti ho già spiegato che l’$id è un parametro stringa che ci permette di identificare in maniera univoca questo campo, quello sul quale ho leggermente sorvolato è il parametro $args

Questo è stato fatto perché all’interno di questo parametro è contenuto un array dal quale possiamo impostare diverse soluzioni, andiamo a vedere assieme la tabella descrittiva dei valori che possiamo passare.

  • title string – Imposta il titolo per la sezione delle impostazioni.
  • description string(Opzionale) Aggiunge la descrizione per la sezione. Questa viene mostrata soltanto come tooltip quando il mouse si trova sopra al titolo della sezione.
  • priority integer(Opzionale) Permette di impostare l’ordine nel quale la sezione dovrà essere mostrata, più piccolo è il numero prima verrà mostrato. Default: 10.
  • capability string(Opzionale) Mostra o nasconde la sezione in base alle capability dell’utente.
  • theme_supports string(Opzionale) Mostra o nasconde la sezione in base al supporto o meno di una particolare feature da parte del tema.

Con questa piccola lista spero di averti fatto capire nel dettaglio quali sono i valori che dobbiamo inserire all’interno dell’array di configurazione ma dato che siamo tutti sviluppatori sono convinto che un blocco di codice è molto più esplicativo.

Adesso che hai inserito il tuo codice hai creato la tua prima sezione, il posto all’interno del quale potrai inserire controlli e impostazioni che permetteranno sia a te che al tuo utente finale di inserire le personalizzazioni CSS che potranno rendere unico il tema WordPress che stai utilizzando.

Ma come dicevo proprio prima, la creazione di una sezione è qualcosa di veramente limitato dato che al momento non fornisce neanche un feedback, in fin dei conti senza controlli e impostazioni non saremo in grado di modificare un bel niente! Sarà il caso di scoprire come creare questi elementi?

Come Inserire i Campi per i nuovi Valori

Lavorare con le Theme Customizer API è un lavoro che ci permette di inserire delle opzioni di personalizzazione in modo molto semplice e divertente, ma al tempo stesso nasconde alcuni concetti un po’ oscuri.

Uno di quelli che mi sono rimasti un po’ più difficili da digerire è la collaborazione instaurata tra i controlli e le impostazioni. Generalmente quando si impara qualcosa di nuovo si procede un passo alla volta, si conosce per prima una determinata caratteristica per procedere alla successiva che la integra e potenzia allo stesso tempo.

Ho terminato la sezione precedente parlando di controlli e impostazioni, questo perché sono la traduzione degli elementi che possiamo aggiungere rispettivamente con $wp_customize->add_control() e $wp_customize->add_setting(). Questi due metodi funzionano in modo molto simile a quello che abbiamo visto precedentemente ma come già detto, lavorano insieme per creare i singoli elementi che ci permetteranno di personalizzare il proprio tema.

Giusto per non andare a complicarci la vita cerchiamo di capire uno per uno come funzionano questi elementi.

Grazie ai controlli è possibile creare l’interfaccia grafica per inserire i dati che verranno passati dal nostro utente. Ad esempio, in questo articolo voglio mostrarti come sia possibile far inserire delle regole CSS che permetteranno di modificare la grandezza del carattere del corpo dei nostri articoli.

Prima di poter fare questo, è necessario scoprire come sia possibile creare un controllo:

Se salvi il tuo codice, che dovrà essere inserito all’interno del tuo functions.php anche se ancora non te l’avevo ancora detto non vedrai a cora niente, sarà presente soltanto la sezione. Questo perché, come ti dicevo precedentemente, questa funzione lavora con add_setting() e da sola non ci permette di salvare niente, piuttosto crea un controllo che permette al nostro utente di inserire dei dati.

Come puoi vedere alcuni dei valori che possiamo impostare per questo metodo sono gli stessi di quelli già visti quando abbiamo analizzato add_section() e per questo non ho intenzione di andarmi a ripetere; però ce ne sono alcuni curiosi dei quali vorrei parlarti in modo specifico:

  • type string(Opzionale) permette di specificare il tipo di input che vogliamo creare. Dato che il controllo che stiamo creando ci permetterà di inserire un valore numerico che indica la grandezza del carattere in questo contesto ho preferito dichiarare questo tipo ma ci sono moltissimi altri valori che ti consiglio di approfondire;
  • section string – grazie a questo parametro siamo in grado di indicare dove vogliamo inserire questo controllo e permetterà a WordPress di sapere la posizione corretta dove restare in ascolto per gli inserimenti degli utenti. Mi raccomando, non dimenticarti questo valore perché è obbligatorio e senza di questo non sarebbe possibile posizionare il controllo nella sezione adatta;
  • input_attrs array – (Opzionale) passando un array ci viene fornita la possibilità di specificare delle informazioni aggiuntive riguardo al controllo che stiamo creando. In questo esempio ho inserito i valori min e max all’interno dei quali dovrà essere impostata la grandezza del carattere (giusto per non “sballare” il mio layout), ma è possibile inserirne molti altri come ad esempio il valore di default;
  • active_callback string – (Opzionale) ultimo ma non per importanza, troviamo questo interessantissimo valore che ci permette di selezionare per quali pagine il nostro controllo dovrà essere visualizzato.

Adesso che abbiamo creato il controllo siamo già a buon punto, quello che ci resta da fare è creare una impostazione che ci permetterà di valutare se il codice inserito dal nostro utente è valido e di salvarlo all’interno del nostro database. Vediamo come poter configurare il metodo add_setting() che ci viene messo a disposizione:

Come puoi vedere con i tuoi stessi occhi, il comportamento del metodo add-setting() è molto simile ai precedenti, si prende un id che dovrà essere lo stesso utilizzato per il controllo appena creato (nel nostro caso quindi sostituiremo id_unico con font_size) e successivamente andiamo ad inserire tramite un array una serie di impostazioni che ci permettono di personalizzare il comportamento di questa impostazione.

Tutti i valori che vedi inseriti sono opzionali e ti consiglio di andare a consultare direttamente la pagina del Codex per scoprire le tipologie di valori che questo accetta, come prima, quello che in questo contesto mi interessa mostrarti sono quelli che ritengo più interessanti.

Ad esempio, con il parametro type possiamo scegliere se salvare il dato che ci verrà passato dall’utente attraverso le theme_mod (valore di default) oppure se utilizzare le option che ci permetteranno di salvare il valore direttamente all’interno della tabella wp_options presente nel database. Come il nome specifica, i valori che andremo a salvare con theme_mod verranno utilizzati soltanto all’interno del tema attivo; con questo intendo dire che se andrai a cambiare tema inevitabilmente perderai queste impostazioni.

Se invece stai costruendo un plugin che ha un lato front end che vuoi far personalizzare da parte del tuo utente con il Customizer, salvando i valori attraverso il tipo option potrai tranquillamente cambiare tema a tuo piacimento perché tanto i valori salvati all’interno di wp_options verranno caricate indipendentemente dal tuo tema.

Altro parametro interessante che vorrei farti approfondire è transport che ci permette di gestire come si deve comportare la nostra Anteprima man mano che andiamo a personalizzare le varie impostazioni. Ovviamente quando modifichiamo il colore di sfondo, la grandezza del carattere o altre impostazioni del genere avere un feedback semi-immediato è una cosa molto utile; voglio dire che il tuo utente dovrà soltanto attendere il refresh della pagina per vedere la modifica applicata.

In questo contesto andremo ad utilizzare il valore di default (refresh) ma potrai comunque modificarne il comportamento aggiungendo postMessage e scrivendo del JavaScript dedicato per gestire il live preview (cosa che accade ad esempio con CSS Hero).

Ma torniamo al nostro esercizio e guardiamo di costruire l’impostazione necessaria per far salvare la grandezza del carattere. Anzi facciamo qualcosa di meglio, dato che adesso dovresti conoscere la struttura di configurazione di tutte le funzioni ho deciso di mostrarti il codice completo e funzionante che abbiamo sviluppato fino ad ora.

In fin dei conti ho scritto un sacco di parole nel tentativo di farti capire al meglio come si comporta questa nuova funzionalità ma il codice necessario non ha superato le 30 righe, quando si dice che si fa prima a sviluppare che a spiegare 😉

Se tutto è andato a buon fine, entrando nella modalità di personalizzazione del tema per il quale hai modificato il file functions.php a questo punto dovresti ottenere qualcosa di questo tipo:

Modifica la dimensione del carattere con le Theme Customizer API

A questo punto puoi tranquillamente iniziare a modificare i numeri che si trovano all’interno del campo input che hai selezionato e vedrai che appena finisci le tue modifiche il tema che si trova sulla destra si prenderà qualche istante per aggiornarsi automaticamente; purtroppo non succede ancora nulla…

Come richiamare le Modifiche

Il nostro tema non è in grado di applicare la nuova grandezza del carattere perché, anche se è in grado di salvare queste informazioni, purtroppo non è in grado di richiamarle… Prima ancora di andare a vedere come questo sia possibile dobbiamo scovare il nostro selettore CSS che ci permetterà di applicare queste modifiche.

Dato che io sto utilizzando Genesis che implementa le classi standard di post_class() introdotte da WordPress posso immaginarmi che la classe che dovrò disturbare prende il nome di .post e se voglio modificare la grandezza dei caratteri presenti all’interno dei suoi paragrafi il selettore corretto è .post p.

Mi raccomando, presta molta attenzione al tipo di selettore che andrai ad utilizzare perché se non utilizzi quello corretto le tue modifiche verranno perse all’interno delle impostazioni e questo non è assolutamente qualcosa che vogliamo 😀

Questo codice dovrà essere inserito all’interno del functions.php presente nel tuo tema, magari sotto al blocco di codice che ti ho mostrato precedentemente, e come puoi notare non farà altro che andare ad inserire delle regole CSS che ti permetteranno di modificare la grandezza del carattere impostata attraverso il controllo font_size.

L’unica funzione che ancora non conosci è get_theme_mod() che grazie al primo parametro ci permette di richiamare il valore che viene automaticamente salvato da WordPress e di utilizzarlo all’interno della schermata di personalizzazione; il secondo parametro invece permette di impostare un valore di default (cosa alquanto inutile dato che lo abbiamo già inserito all’interno della dichiarazione del nostro elemento) che ti ho voluto mostrare soltanto per ragioni di completezza.

Conclusioni

Ebbene siamo giunti al termine di un altro lungo e, spero, interessante articolo all’interno del quale hai avuto un assaggio delle potenzialità messe a disposizione dalle Theme Customization API. Spero veramente di averti incuriosito e spinto a voler approfondire questo argomento dato che rappresenta un elemento essenziale nello sviluppo dei futuri temi WordPress.

Ti ricordo che ad oggi è essenziale utilizzare queste API se hai intenzione di pubblicare il tuo tema all’interno del repository ufficiale di WordPress.org e che noi del network AndMore abbiamo intenzione di approfondire questi argomenti anche nel futuro.

Quindi, se ti sono rimasti aperti dei dubbi o ti interessa approfondire questi argomenti non esitare a farcelo sapere! I nostri commenti, profili sociali e adesso anche il forum di skillsAndMore sono tutti posti perfetti dove poter approfondire questi aspetti e chiedere dei chiarimenti a riguardo; se ti senti timido sappi che questo sentimento sta rallentando la tua formazione perché è soltanto con il confronto che siamo in grado di crescere più velocemente 😀

Lascia il tuo Pensiero