La Settings API di WordPress

La Settings API di WordPress permette di creare pagine di configurazione, sezioni all'interno delle pagine e campi form nelle sezioni. Lo sviluppatore può aggiungere nuove pagine di impostazioni con sezioni e campi o sezioni all'interno di pagine esistenti.

Nuove impostazioni

Ogni volta che viene creato un campo in una delle pagine del menu "Impostazioni", WordPress genera una nuovo record nella tabella wp_options del database. Una funzione di callback dovrà produrre il markup dei campi form e assegnare loro il valore corrente dell'impostazione prelevandolo dal database. Ogni nuova opzione deve essere registrata tramite la funzione add_settings_field(), per la registrazione dei dati nel database.

add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() );

Argomento	Tipo	Descrizione
$id	string	(richiesto) valore dell'attributo id del tag
$title	string	(richiesto) valore dell'attributo title
$callback	callable	(richiesto) nome della funzione che genera il campo del form. Nome e id del campo devono corrispondere al valore $id passato alla funzione di callback. Un'istallazione base dispone delle pagine general (impostazioni generali), reading (impostazioni di lettura), writing (scrittura), discussion, media e permalink.
$section	string	(opzionale) sezione della pagina in cui va inserito il campo form. L'argomento può assumere il valore default o quello di una sezione esistente o di una nuova sezione generata da add_settings_section()
$args	array	(opzionale) array di argomenti aggiuntivi passati alla funzione di callback

Nuove sezioni

Le sezioni di impostazioni sono gruppi di campi che vengono raccolti sotto uno stesso titolo. WordPress permette di aggiungere nuove sezioni a pagine esistenti o sezioni in nuove pagine, la scelta dipende dallo sviluppatore. Le sezioni vengono aggiunte tramite la funzione add_settings_section():

add_settings_section( $id, $title, $callback, $page );

Argomento	Tipo	Descrizione
$id	string	(richiesto) valore dell'attributo id del container
$title	string	(richiesto) valore dell'attributo title del container
$callback	callable	(richiesto) nome della funzione che genera e stampa il codice HTML della sezione.
$page	string	(richiesto) tipo di pagina in cui viene inserita la sezione

Registrazione delle impostazioni

Dopo aver aggiunto nuove opzioni queste vanno registrate, la registrazione/deregistrazione avviene tramite register_settings() e unregister_settings():

register_setting( $option_group, $option_name, $sanitize_callback );
unregister_setting( $option_group, $option_name, $sanitize_callback );

Argomento	Tipo	Descrizione
$option_group	string	(richiesto) nome di un gruppo di opzioni, deve corrispondere allo slug della pagina che ospita il form
$option_name	string	(richiesto) nome assegnato all'opzione
$sanitize_callback	callable	(opzionale) nome di un'eventuale funzione di callback che verifica la sicurezza dei dati

Tutte le funzioni descritte vanno agganciate all'action hook admin_init. Una volta aggiunte e registrate le opzioni, bisogna generare il codice HTML dei nuovi campi form.

Form della pagina delle impostazioni

Il form viene generato automaticamente da WordPress al momento della creazione della pagina. Quando le sezioni di impostazioni vengono aggiunte a pagine esistenti sarà necessario creare i campi associati alle nuove opzioni senza preoccuparsi del form. Al contrario, quando si crea una nuova pagina di impostazioni bisognerà creare il form e aggiungere una serie di campi specifici.

Per prima cosa bisogna preoccuparsi della sicurezza. Nelle nuove pagine va sempre invocata la funzione settings_fields() che genera i campi nonce, action e option_page del form.

settings_fields( $option_group );

Argomento	Tipo	Descrizione
$option_group	string	(richiesto) nome di un gruppo di opzioni, deve corrispondere al nome registrato con la funzione register_setting() e allo slug della pagina che ospita il form

La funzione va sempre invocata dall'interno del form. Per visualizzare l'elenco delle sezioni della pagina delle impostazioni con le relative opzioni l'API dispone della funzione do_settings_sections(). I titoli delle sezioni vengono inseriti all'interno di elementi h3 e le impostazioni in tabelle.

do_settings_sections( $page );

Argomento	Tipo	Descrizione
$page	string	(richiesto) slug della pagina di cui si vogliono visualizzare le impostazioni. Il valore inserito deve essere lo stesso di quello utilizzato in add_settings_section()

Per salvare i dati acquisiti, è necessario un pulsante di trasmissione, a questo scopo l'API fornisce la funzione submit_button() che genera l'output HTML necessario.

Aggiungere un campo in una pagina di impostazioni

Nell'esempio che segue, si vedrà come utilizzare alcune delle funzioni presentate per generare una sezione di opzioni all'interno della pagina delle impostazioni di discussione. Si aggiunga il codice che segue al file functions.php del tema Seventyone:

function seventyone_build_settings_section(){
	echo 'Seventyone setting section';
}
function seventyone_settings_field() {
 	echo '<input name="seventyone_setting_field" id="seventyone_setting_field" type="checkbox" value="1" class="code" ' . checked( 1, get_option( 'seventyone_setting_field' ), false ) . ' /> Seventyone setting field';
 }
function seventyone_custom_settings(){
	add_settings_section(
		'seventyone_settings_section',
		'Seventyone Settings',
		'seventyone_build_settings_section',
		'discussion' );
	add_settings_field(
		'seventyone_setting_field',
		'Seventyone field',
		'seventyone_settings_field',
		'discussion',
		'seventyone_settings_section' );
	register_setting( 'discussion', 'seventyone_setting_field' );
} // seventyone_custom_settings()
add_action( 'admin_init', 'seventyone_custom_settings' );

Per verificare che tutto funzioni a dovere si apra la pagina delle impostazioni "Discussione" e si salvino i dati.

La nuova opzione viene registrata nel database e il suo valore apparirà nella pagina di amministrazione "Tutte le opzioni", raggiungibile all'indirizzo http://miosito.come/wp-admin/options.php. Il valore della nuova opzione apparirà nell'elenco "Tutte le opzioni" e il suo valore sarà 1 o un campo vuoto.

Vediamo ora come utilizzare nel front-end il valore dell'opzione. Si apra il file comments.php di Seventyone e si cerchi il blocco che genera la lista dei commenti:

<ol class="comment-list">
<?php
	wp_list_comments( array(
		'style'		=> 'ol',
		'short_ping'	=> true,
		'avatar_size'	=> 34,
	) );
?>
</ol>

Si modifichi questo blocco di codice come segue:

<ol class="comment-list">
<?php
	$style = ( get_option( 'seventyone_setting_field' ) == 1 ) ? 'ol' : 'ul';
	wp_list_comments( array(
		'style'		=> $style,
		'short_ping'	=> true,
		'avatar_size'	=> 34,
	) );
?>
</ol>

Nel'ultimo frammento di codice è stata aggiunta l'istruzione che assegna il valore alla variabile $style. Questa immagazzinerà il valore dell'opzione seventyone_setting_field per il successivo utilizzo. Nel caso in cui il valore di seventyone_setting_field è pari a 1 allora i commenti vengono annidati in una lista ol. In caso contrario, si tratterà di una lista non ordinata.