Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Theme Development

Le Settings API di WordPress, parte 2: sezioni, campi e impostazioni

by
Difficulty:BeginnerLength:LongLanguages:
This post is part of a series called The Complete Guide to the WordPress Settings API.
The WordPress Settings API, Part 1: What It Is, Why It Matters
The WordPress Settings API, Part 3: All About Menus

Italian (Italiano) translation by Fabio Pantano (you can also view the original English article)

Quando si tratta di sviluppare temi e plugin WordPress, ci sono diversi modi in cui gli sviluppatori creano i loro menu, opzioni e funzionalità di convalida. In WordPress c'è solo un modo per farlo correttamente: con le Settings API.

Lo scopo di questa serie è diventare la guida definitiva su come sfruttare le Settings API di WordPress e un unico punto di riferimento per sviluppare correttamente temi e plugin.

Nel primo articolo di questa serie abbiamo dato un rapido sguardo alle Settings API e perché sono importanti da usare. Qui, ci tufferemo diretti nelle API e come sfruttare tutte le potenzialità.

Daremo un'occhiata agli elementi fondamentali di WordPress, sezioni, campi e opzioni, e come includerli nella Dashboard nativa.


Sezioni, campi e opzioni

Prima di iniziare a scrivere del codice, è importante capire i tre componenti principali dei Settings API di WordPress.

  1. I Campi sono singole opzioni che appaiono sulle pagine dei menu. Corrispondono agli effettivi elementi su schermo,  ossia un box di testo, un pulsante, una casella di controllo, ecc. I campi rappresentano un valore memorizzato nel database di WordPress.
  2. Le Sezioni sono un raggruppamento lineare di campi. Ogni volta che si lavora con più campi, probabilmente si vuole raggruppare una serie di opzioni correlate; le sezioni rappresentano questo raggruppamento. Inoltre, se il vostro progetto include più pagine di amministrazione, spesso ogni sezione corrisponde alla propria pagina di menu (anche se è possibile aggiungerle a sezioni esistenti).
  3. Le Opzioni vengono registrate dopo che hai definito sezioni e campi. Pensatele come una combinazione di campi e sezioni.

A questo punto, non preoccupatevi se i componenti principali sono ancora poco chiari. Andremo ad approfondire ogni componente con esempi di codice che li lega tutti insieme.


Una sandbox di testing

Prima di iniziare a programmare con le Settings API, installiamo un tema base, da utilizzare in questo articolo e per l'intera serie. L'intero codice sorgente è anche disponibile su GitHub.

Nell'installazione locale di WordPress, spostarsi nella directory "temi" e create una nuova directory vuota con nome "WordPress-Impostazioni-Sandbox". Aggiungete i seguenti tre file:

  • style.css – è il foglio di stile per il tema. Comprende tutte le meta informazioni del tema. È richiesto da WordPress
  • index.php – questo è il modello predefinito per il tema. Inizialmente si può lasciare vuoto. È richiesto da WordPress
  • functions.php – è dove faremo la maggior parte del nostro lavoro. Verrà compilato nel corso dell'esercitazione

Aggiungere il seguente codice nel file style.css:

Successivamente, aggiungere il seguente codice nel file index.php:

Come si può notare, il markup qui sopra è molto semplice; si consiglia di non usarlo come base di partenza per lo sviluppo di un nuovo tema. E' studiato appositamente per questa serie di articoli e servirà semplicemente per la lettura dei valori con le Settings API.

Nella schermata di amministrazione dei temi, aggiornate la pagina per vedere il nuovo tema Sandbox visualizzato. Attivatelo.

Theme Selection

Ora siamo pronti per iniziare.


Il nostro primo set di opzioni

Nel modello qui sopra, abbiamo definito tre specifiche aree di contenuto: header (intestazione), content (contenuto) e footer (piè di pagina). Utilizzando le Settings API, creiamo una sezione "Generale" contenente tre campi, ciascuno dei quali corrisponde a una specifica aree di contenuto che abbiamo appena definito.

Prima di scrivere qualsiasi codice, ho sempre trovato utile elencare esattamente cosa devo fare. In questo caso, abbiamo bisogno di effettuare le seguenti operazioni:

  • Definire una sezione per raggruppare ogni campo
  • Aggiungere tre campi, uno per ogni area di contenuto, alla sezione definita qui sopra
  • Registrare le opzioni con le WordPress API.

Al fine di evitare enormi blocchi di codice e per approfondire il tutto, analizzeremo ogni elemento punto per punto.

Creare la sezione

Per implementare la nostra sezione "Generale" con le varie opzioni, ci serve utilizzare la funzione add_settings_section delle Settings API. Secondo il Codex di WordPress, add_settings_section richiede tre argomenti:

  • ID – è l'identificatore univoco per questa particolare sezione. Questo è il valore che verrà utilizzato per registrare ogni campo all'interno di questa sezione. Sentiti libero di nominarlo come volete, ma rendetelo chiaro per motivi di leggibilità.
  • Titolo – questo valore verrà visualizzato nella parte superiore della pagina, nella dashboard di Wordpress, quando gli utenti imposteranno le varie opzioni disponibili.
  • Callback – questo è il nome di una funzione, da definire in seguito, che eseguirà la rappresentazione del testo su schermo. Può essere utilizzata per una varietà di funzionalità. Nel caso più semplice, può essere utilizzato per fornire un insieme di istruzioni o una descrizione per la tua pagina delle opzioni.
  • Pagina – questo valore viene utilizzato per dire a WordPress su quale pagina visualizzare le opzioni. Per i prossimi articoli, lo useremo con le nostre pagine personalizzate. Per ora, lo aggiungeremo alla pagina General (Generale).

Procediamo e definiamo la nostra sezione. Esaminiamo il codice commentato qui di seguito. Aggiungiamolo al nostro file functions.php.

Un consiglio sulle porzioni di codice in questa serie: non basta copiare e incollare il codice. Prendetevi tutto il tempo per leggere ogni riga, vedere come gli argomenti corrispondono alla funzione API in analisi e seguire i relativi commenti per capire lo scopo di ogni blocco:

Ha senso? In teoria non sembra molto, ma aprite il menu Settings (impostazioni) e fate clic su General (generale). Nella parte inferiore della pagina si dovrebbe vedere la nuova sezione.

General Settings

È possibile aggiungere questa sezione in qualsiasi pagina nel menu Settings (Impostazioni). Nell'esempio precedente, abbiamo inserito "general" come ultimo parametro nella funzione add_settings_section, ma se si desidera aggiungerla a una pagina diversa, fornire un titolo di pagina diverso. Qui di seguito i riferimenti per tutte le pagine nel menu Settings (impostazioni) e la relativa "key":

  • General (Generali), "general"
  • Writing (Scrittura), "writing"
  • Reading (Lettura), "reading"
  • Discussion (Discussione), "discussion"
  • Media, "media"
  • Privacy, "privacy"
  • Permalinks (Permalink), "permalink"

Aggiungere i campi

Ora che abbiamo definito una sezione, possiamo introdurre qualche opzione. Se ricordate, nella nostra pagina index avevamo definito tre elementi contenitore: header, content e footer.

Anche se introdurremo più opzioni nel corso di questa serie, oggi implementeremo un modo per attivare e disattivare la visibilità di ciascun contenitore.

Simile a come abbiamo fatto con la sezione impostazioni, vorrei elencare esattamente quello che dobbiamo fare prima di scrivere del codice. Dato che stiamo per attivare/disattivare ciascuna delle aree...

  • Ci serviranno tre opzioni, una per ogni area.
  • Poiché stiamo modificando la visibilità, possiamo usare una casella di controllo come elemento di interfaccia

A questo punto, siamo pronti per introdurre il primo campo. Per far questo, useremo la funzione add_settings_field. Questa funzione accetta sei parametri (quattro obbligatori, due opzionali). Eccoli:

  • ID: l'ID del campo. Si utilizzerà per salvare e recuperare il valore in tutto il tema. Assegnare un nome significativo per migliorare la leggibilità del codice.
  • Titolo – nome da applicare al titolo dell'opzione sulla pagina. Dovrebbe essere chiaro, è ciò che leggeranno gli utenti finali.
  • Callback – nome della funzione utilizzata per il rendering dell'elemento con cui gli utenti interagiscono.
  • Pagina – simile alla sezione delineata, questo parametro identifica su quale pagina questa opzione deve risiedere. Se si intende introdurre solo una singola opzione, è possibile aggiungerlo a una pagina esistente, piuttosto che a una sezione definita.
  • Sezione – si riferisce alla sezione creata utilizzando la funzione add_settings_section. Questo valore è l'ID specificato durante la creazione della sezione. E' un parametro facoltativo.
  • Argomenti – si tratta di una matrice di argomenti che vengono passati alla funzione di callback. Ciò è utile se ci sono informazioni aggiuntive che si desidera includere durante il rendering dell'elemento. Si tratta di un parametro facoltativo.

Detto questo, andiamo avanti e definire il nostro primo campo. In particolare, introdurremo un'opzione per attivare o disattivare la visibilità dell'header

In primo luogo, facciamo una chiamata a add_settings_field appena sotto la funzione add_settings_section inizializzata nella prima parte del tutorial. Esaminare ogni riga e i commenti di ogni opzione:

Successivamente, definiamo la callback della funzione di cui sopra. Questo callback viene utilizzata per mostrare la casella di controllo e la descrizione nella pagina:

Per quanto riguarda la casella di controllo, fate attenzione ai commenti, ma non preoccupatevi troppo di alcuni attributi che non riconosci (ad esempio una chiamata alla funzione checked()). Più avanti in questa serie, andremo a dare un'occhiata a ogni elemento di input e le corrispondenti funzioni di supporto.

A questo punto, il tuo file functions.php dovrebbe assomigliare a questo:

Aggiornate la pagina delle impostazioni generali. Si dovrebbe vedere la casella di controllo con l'etichetta "Header" e una descrizione accanto.

First Option

Purtroppo, non salva ancora il valore nel database.

Registrare le impostazioni

Per salvare effettivamente i nostri campi nel database, abbiamo bisogno di registrarli con WordPress. Questa operazione è relativamente facile, abbiamo solo bisogno di sfruttare la funzione register_setting.

Questa funzione accetta tre argomenti (due obbligatori, una facoltativa):

  • Gruppo di opzioni – è in realtà il nome del gruppo di opzioni. Può trattarsi di un gruppo esistente di opzioni fornito da WordPress o un ID che abbiamo specificato durante la creazione di una nostra sezione. Questo argomento è obbligatorio.
  • Nome dell'opzione – questo è l'ID del campo che registriamo. Nel nostro caso, registriamo solo un singolo campo, ma se stavamo registrando più campi, sarebbe stato necessario chiamare questa funzione per ogni campo da registriare. Tra un attimo vedremo ulteriori informazioni. Questo argomento è obbligatorio.
  • Callback – questo argomento richiede il nome di una funzione che verrà chiamata prima del salvataggio dei dati nel database. Questo argomento non rientra nell'ambito di questo articolo, ma verrà analizzata prima della fine della serie. Questo argomento è facoltativo.

A questo punto, registriamo le impostazione che abbiamo appena creato. Esaminiamo il codice riportato di seguito. Aggiungere questa porzione di codice direttamente sotto la chiamata a add_settings_field nella funzione definita in precedenza nell'articolo. È probabilmente il più facile da esaminare fra tutte le porzioni di codici in questo articolo:

Proviamolo. Selezionare la casella di controllo, fare clic su "Save changes" e notare che quando la pagina viene aggiornata, l'opzione viene modificata. Deselezionare la casella di controllo, salvare e osservare il risultato.

Saved Option

Abbastanza facile, no?

Aggiungere le due opzioni finali

Ora vediamo di introdurre le due opzioni per visualizzare o meno l'area content e footer. Il procedimento è pressoché identico a come abbiamo impostato l'attivazione dell'header. 

Per prima cosa, definiamo il campo per la visualizzazione dell'area content. Inseriamolo sotto la funzione add_settings_field:

Poi impostiamo la funzione di chiamata:

Definiamo il campo per la visualizzazione dell'area footer:

E anche la rispettiva chiamata:

Infine, registriamo entrambi i campi con WordPress. Queste due funzioni vanno inserite sotto la funzione inizializzata a inizio articolo.

Il file functions.php completo risulterà così:

Ora aggiorniamo la pagina General per visualizzare tutte e tre le caselle di controllo.

Final Options

Leggere le API

Che opzioni sarebbero se non le sfruttiamo all'interno del nostro tema o plugin? Dobbiamo poter accedere a queste opzioni per poterle gestire correttamente.

Per far ciò, si usa la funzione get_option. Questa funzione accetta due argomenti (una obbligatoria, una facoltativa):

  • Option ID – è l'ID del campo da cui richiamare il valore. Questo argomento è richiesto.
  • Default Option – è il dato che la funzione rimanderà in caso di valore nullo (per esempio se l'opzione non si trova nel database). Questo argomento è opzionale.

Innanzitutto vediamo di attivare la visibilità dell'header. Nel file index creato in precedenza, individuare l'elemento con l'ID dell'header. Eccolo qua:

Ora implementiamo una condizione con una chiamata get_option. Se la condizione risulta vera (cioè che l'opzione sulla pagina General è spuntata), allora visualizziamo l'elemento. In caso contrario non appare.

Spostiamoci con ottimismo sulla pagina General, deselezionate l'elemento header e fate un refresh dell'homepage. L'elemento header non dovrebbe apparire.

A questo punto, ripetiamo semplicemente lo stesso procedimento per l'elemento content e footer. Inseriamo entrambi gli elementi in forma condizionale per valutare il loro risultato con le chiamate get_option.

Ecco qua:

Rivisitate la pagina General, attivate e disattivate ogni casella di controllo e aggiornate la pagina del tema. Gli elementi dovrebbero cambiare singolarmente il proprio stato, indipendentemente dagli altri.


Nel prossimo articolo: pagine di menu

Questo è tutto per ora! Abbiamo esaminato tutte le funzioni richieste per introdurre nuove sezioni, campi e opzioni in WordPress. Ovviamente, c'è molto altro da scoprire.

Nel prossimo articolo analizzeremo come aggiungere elementi di menu personalizzati nel menu di WordPress, e aggiungere le nostre pagine nella dashboard di WordPress.


Risorse correlate

Molti argomenti sono stati affrontati in questo articolo. Ecco un riepilogo generale con i rispettivi riferimenti.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.