Come creare una pagina delle impostazioni in WordPress

Se stai creando un plugin per WordPress, ti starai chiedendo come creare una pagina delle impostazioni per esso. WordPress offre una sorta di meccanismo "standard" per questo? Esistono nuovi strumenti o framework con cui creare pagine di impostazioni moderne? È una buona idea creare una pagina delle impostazioni? Bene, oggi parleremo di tutto questo e risponderò alle tue domande.

Decisioni, non Opzioni

WordPress è una piattaforma che mira a democratizzare il web. Questa affermazione, che suona molto bene ma allo stesso tempo è molto astratta, è un modo per dire "vogliamo che chiunque sia in grado di utilizzare WordPress". E, che tu ci creda o no, le pagine delle impostazioni possono essere, e in effetti in molti casi lo sono, un ostacolo . Non mi credi? Ebbene, lo stesso WordPress lo dice:

Quando prendiamo decisioni, questi sono gli utenti che consideriamo per primi. Un ottimo esempio di questa considerazione sono le opzioni software. Ogni volta che dai un'opzione a un utente, chiedi loro di prendere una decisione. Quando a un utente non interessa o non comprende l'opzione, ciò alla fine porta alla frustrazione. Come sviluppatori, a volte riteniamo che fornire opzioni per tutto sia una buona cosa, non puoi mai avere troppe scelte, giusto? Alla fine queste scelte finiscono per essere tecniche, scelte a cui l'utente finale medio non ha alcun interesse. È nostro dovere come sviluppatori prendere decisioni di progettazione intelligenti ed evitare di imporre il peso delle scelte tecniche sui nostri utenti finali.

Filosofia WordPress

Quindi, prima di creare una pagina delle impostazioni, pensa attentamente alle opzioni che vuoi offrire ai tuoi utenti, perché vuoi che abbiano accesso a tali opzioni e se è necessario o utile farlo.

Filtri come alternativa

Anche se so che non dovrei offrire troppe opzioni ai miei utenti, devo confessare che, come sviluppatore, non è sempre facile per me prendere una decisione invece di offrire un'opzione. Ci sono momenti in cui voglio che i miei utenti abbiano la possibilità di scegliere , anche se sono consapevole che le opzioni che sto esponendo sono complesse. Allora cosa devo fare in questi casi? Seguo la raccomandazione di WordPress e limito i miei utenti avanzati?

Fortunatamente, WordPress offre una soluzione perfetta a questo dilemma: filtri . Quando progetti un plug-in e desideri che i tuoi utenti (avanzati) siano in grado di regolarne il comportamento, non creare una pagina delle impostazioni o qualcosa del genere. Invece, rendi il tuo plug-in personalizzabile attraverso il meccanismo di filtro di WordPress.

Se utilizzi i filtri, la maggior parte dei tuoi utenti godrà di un comportamento predefinito ("decisioni", ricordi?), perché utilizzeranno il plug-in con i valori predefiniti impostati nei tuoi filtri, mentre gli utenti avanzati avranno la possibilità di modificarli decisioni tramite hook (e quindi hai anche "opzioni"). Il meglio dei due mondi!

Impostazioni di WordPress

Ok, ora che siamo consapevoli dell'importanza di prendere decisioni per i nostri utenti e abbiamo visto come aggirare questa limitazione (se necessario) attraverso i filtri, è tempo di vedere come possiamo creare una pagina delle impostazioni in WordPress. Perché, sì: ci sono momenti in cui abbiamo davvero bisogno di dare ai nostri utenti la possibilità di prendere decisioni in base alle loro preferenze.

API delle impostazioni in WordPress

L'API delle impostazioni è stata aggiunta nella versione 2.7 di WordPress. Si tratta di un insieme di funzioni che standardizzano la creazione delle pagine delle impostazioni, consentendo di definire quali opzioni sono disponibili, quale sarà l'interfaccia utente per modificare ciascuna di tali opzioni (essenzialmente, i campi di un modulo) e come convalidare, salvare e recuperarne i valori.

Penso che il modo migliore per imparare sia attraverso gli esempi, quindi creiamo la nostra prima pagina delle impostazioni usando l'API delle impostazioni passo dopo passo.

Creazione di una nuova pagina delle impostazioni

La prima cosa che devi fare per creare una pagina delle impostazioni è (sorpresa, sorpresa!) Creare una pagina per visualizzare le impostazioni. Per fare ciò, usa semplicemente la funzione add_options_page durante l'azione admin_menu e registra la pagina:

 function nelio_add_settings_page() { add_options_page( 'Nelio Plugin Settings', 'Nelio', 'manage_options', 'nelio-example-plugin', 'nelio_render_settings_page' ); } add_action( 'admin_menu', 'nelio_add_settings_page' );

Come puoi vedere, l'unica cosa che facciamo con questa funzione è registrare una nuova pagina che apparirà nel menu Impostazioni di WordPress, con il suo titolo, il nome nel menu, i permessi che l'utente deve avere per potervi accedere , e così via. L'ultimo argomento, nelio_render_settings_page , è il nome della funzione che si occuperà del rendering di detta pagina:

 <?php function nelio_render_settings_page() { ?> <h2>Nelio Plugin Settings</h2> <form action="options.php" method="post"> <?php settings_fields( 'nelio_example_plugin_settings' ); do_settings_sections( 'nelio_example_plugin' ); ?> <input type="submit" name="submit" class="button button-primary" value="<?php esc_attr_e( 'Save' ); ?>" /> </form> <?php }

La stessa pagina delle impostazioni è relativamente facile da creare. Dobbiamo semplicemente aggiungere un form il cui contenuto sarà generato in modo semiautomatico da WordPress. Da un lato, invochiamo la funzione settings_fields , che fondamentalmente aggiunge un nonce nel modulo per renderlo "sicuro". Successivamente, chiediamo a WordPress di eseguire il rendering di tutte le impostazioni che abbiamo creato per il nostro plug-in utilizzando la funzione do_settings_sections . E, infine, aggiungiamo semplicemente il pulsante Invia il modulo.

Impostazioni effettive nella nostra pagina delle impostazioni

Successivamente, dobbiamo registrare ciascuna delle opzioni che faranno parte della nostra pagina delle impostazioni. Per fare ciò utilizzeremo due funzioni: register_setting , che ci permette di indicare il nome con cui salveremo le impostazioni nel database, e add_settings_field , che aggiunge ogni singola opzione:

 function nelio_register_settings() { register_setting( 'nelio_example_plugin_settings', 'nelio_example_plugin_settings', 'nelio_validate_example_plugin_settings' ); add_settings_section( 'section_one', 'Section One', 'nelio_section_one_text', 'nelio_example_plugin' ); add_settings_field( 'some_text_field', 'Some Text Field', 'nelio_render_some_text_field', 'nelio_example_plugin', 'section_one' ); add_settings_field( 'another_number_field', 'Another Number Field', 'nelio_render_another_number_field', 'nelio_example_plugin', 'section_one' ); } add_action( 'admin_init', 'nelio_register_settings' );

Il frammento di codice precedente ha un paio di cose che meritano un'attenzione speciale. Da un lato, si noti che la funzione register_setting ha come terzo argomento: nelio_validate_example_plugin_settings . Questo è il nome della funzione di callback che verrà chiamata per validare i valori che l'utente ha selezionato (ricorda che devi sempre validare e sanificare i campi del form). Questa funzione è qualcosa del genere:

 function nelio_validate_example_plugin_settings( $input ) { $output['some_text_field'] = sanitize_text_field( $input['some_text_field'] ); $output['another_number_field'] = absint( $input['another_number_field'] ); // ... return $output; }

dove recuperiamo ogni campo inviato da $input e lo sanifichiamo in $output in modo da sapere per certo che, qualunque cosa finiamo per salvare nel database, è valida e corretta.

La seconda cosa su cui volevo concentrarti è il fatto che ciascuno dei campi che definiamo include anche un riferimento a una funzione che dice a WordPress come deve essere visualizzato ogni campo. Ad esempio, i callback dei campi nel nostro esempio potrebbero essere qualcosa del genere:

 function nelio_section_one_text() { echo '<p>This is the first (and only) section in my settings.</p>'; } function nelio_render_some_text_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="text" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[some_text_field]' ), esc_attr( $options['some_text_field'] ) ); } function nelio_render_another_number_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="number" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[another_number_field]' ), esc_attr( $options['another_number_field'] ) ); }

In sostanza, tutto ciò che fanno questi callback è recuperare il valore corrente del campo che dovrebbero visualizzare (con get_option ) e visualizzare l'HTML che consentirà all'utente di impostare un valore o l'altro (in questo esempio, un campo di input di digitare text o number ).

Qual è il risultato finale, stai chiedendo? Questo:

Pensieri finali

Come puoi vedere, creare una pagina delle impostazioni è relativamente semplice. Personalmente non mi piace molto l'intero processo, poiché è abbastanza ripetitivo e dobbiamo scrivere più e più volte lo stesso codice standard... ma è comunque facile.

Per semplificare ulteriormente questo processo, però, esistono dei generatori di codice online con i quali, tramite una semplice interfaccia utente, puoi definire i diversi campi che desideri nella pagina delle impostazioni. Un paio di esempi sono:

• API Impostazioni WP
• Generatore di pagine WordPressOption

E, naturalmente, c'è sempre la possibilità di creare una pagina delle impostazioni utilizzando tecnologie come React... ma questa è una storia di un'altra epoca, non trovate?

Immagine in primo piano di Rima Kruciene su Unsplash.