La Settings API di WordPress

Se la Options API permette di creare, modificare, eliminare e leggere le opzioni di temi e plugin, la Settings API consente di gestirle in modo semi-automatico. Quando si decide per la Settings API, gli step da seguire per costruire una pagina di opzioni sono nell'ordine:

1. Definizione della pagina (o delle pagine) di configurazione.
2. Definizione dei gruppi di opzioni (che nel codex vengono definiti alternativamente come settings sections e option groups).
3. Definizione delle singole opzioni.
4. Accesso ai valori delle opzioni.

Una settings section è un gruppo di opzioni visualizzato all'interno di una stessa pagina di amministrazione, al di sotto di un unico titolo. Più gruppi di opzioni possono essere visualizzati nella stessa pagina, anche organizzati in schede (o "tabs"). La creazione di un gruppo di opzioni avviene grazie alla funzione add_settings_section, definita come segue:

add_settings_section(
	$id,		// Unique identifier for the settings section
	$title,		// Section title
	$callback,	// Section callback
	$page		// The menu page on which to display the section
);

I quattro argomenti sono tutti obbligatori:

Argomento	Descrizione
$id	(string) è lo slug che identifica univocamente il gruppo di opzioni.
$title	(string) è il nome del gruppo di opzioni, visualizzato come sotto-titolo all'interno della pagina di amministrazione.
$callback	(string) è il nome della funzione di callback che “deve” mandare a video un output HTML.
$page	(string) è lo slug della pagina del pannello di amministrazione in cui verrà visualizzato il gruppo di opzioni.

Il metodo add_settings_section va agganciato all'hook admin_init, come nel codice che segue:

add_action( 'admin_init', 'my_theme_register_settings' );
function my_theme_register_settings(){
	add_settings_section( ... );
}

Dopo la creazione di un nuovo gruppo, vanno create le singole opzioni, ricorrendo alla funzione add_settings_field. Quest'ultima crea una nuova opzione ed esegue una funzione di callback che genera il markup del corrispondente elemento input. Anche add_settings_field va agganciata all'hook admin_init, e accetta sei argomenti, di cui i primi quattro obbligatori:

Argomento	Descrizione
$id	(string) è una stringa che identifica univocamente l'opzione e che viene utilizzata per generare il valore dell'attributo id dell'elemento input corrispondente.
$title	(string) è il titolo del campo.
$callback	(string) è il nome della funzione di callback che genera l'elemento input.
$page	(string) è lo slug che identifica la pagina del menu di amministrazione in cui compare il campo associato all'opzione.
$section	(string) è l'id della settings section di cui fa parte l'opzione.
$args	(array) è un array di paramentri che viene passato come argomento della funzione di callback.

add_action( 'admin_init', 'my_theme_register_settings' );
function my_theme_register_settings(){
	add_settings_section( ... );
	add_settings_field( ... );
}

Una volta aggiunte, le opzioni vanno registrate, esattamente come nel caso della Options API.
Dunque, se si sta lavorando ad un tema, la funzione register_setting viene agganciata all'hook admin_init e si avrà il seguente codice:

add_action( 'admin_init', 'my_theme_register_settings' );
function my_theme_register_settings(){
	add_settings_section(
		'my_settings_section',
		__( 'My Settings section title', 'my_theme' ),
		'my_settings_section_callback',
		'my_settings_page'
	);
	add_settings_field(
		'my_settings_field',
		__( 'My Settings field title', 'my_theme' ),
		'my_settings_field_callback',
		'my_settings_page',
		'my_settings_section',
		array( 'param', 'param', ... )
	);
	register_setting(
		'my_settings_section',
		'my_settings_field'
	);
}

Vanno quindi definite le due funzioni di callback. La prima manderà a video l'output HTML associato al gruppo di opzioni:

function my_settings_section_callback(){
	echo "<p>Insert or edit settings values</p>";
}

La seconda funzione di callback genera il markup dell'elemento input corrispondente all'opzione.
Quella che segue è una funzione di esempio, in cui i valori degli attributi dell'elemento input sono generati grazie alla funzione get_option:

function my_settings_field_callback( $args ){
	?>
	<input
		id="<?php echo $args['id']; ?>"
		type="<?php echo $args['type']; ?>"
		class="<?php echo $args['class']; ?>"
		value="<?php echo ( !empty( get_option( $args['id'] ) ) ) ? get_option( $args['id'] ) : ( $args['value'] ); ?>"
		name="<?php echo $args['id']; ?>" />
	<?php
}

I valori degli attributi vengono assegnati grazie all'array $args. All'attributo value, invece, viene assegnato il valore dell'opzione memorizzato nel database, grazie alla funzione get_option. Se quest'ultima non fornisce un valore utile, allora viene assegnato un valore predefinito, passato anche questo come elemento dell'array $args. L'ultimo step è la resa a video del gruppo di opzioni. Prima di procedere, però, è necessario stabilire su quale pagina del pannello di amministrazione dovranno essere visualizzati i campi di opzione.

Le alternative sono diverse: WordPress, infatti, permette di aggiungere opzioni ad una pagina già esistente, oppure di creare nuove voci nel menu di amministrazione. Le diverse alternative andranno valutate di volta in volta, in base alla complessità del tema o del plugin e al rilievo che si vorrà all'interno del pannello di amministrazione.

Se il gruppo di opzioni viene aggiunto ad una nuova pagina di opzioni, bisognerà creare una nuova funzione di callback da eseguire nel momento in cui WordPress genera il markup della pagina. Più avanti si vedrà come e quando eseguire la funzione, che comunque va strutturata come segue:

function my_menu_settings_page_callback(){
	?>
	<div class="wrap">
		<h2><?php echo wp_get_theme(); ?> <?php _e('Theme options', 'my_theme' ) ?></h2>
		<?php settings_errors(); ?>
		<form method="post" action="options.php">
		<?php
			settings_fields( 'my_settings_section' );
			do_settings_sections( 'my_menu_settings_page' );
			submit_button();
		?>
		</form>
	</div><!-- .wrap -->
	<?
}

Il template tag wp_get_theme() restituisce un'istanza dell'oggetto WP_Theme: accedendovi come nell'esempio appena proposto, la funzione manda a video il nome del tema corrente. La funzione settings_fields genera alcuni campi nascosti che permettono di archiviare in modo sicuro i dati: si tratta di un campo nonce, un campo action e un campo option_page.

Infine, do_settings_sections genera i campi del form, mentre submit_button genera il pulsante per la trasmissione dei dati.

Termina qui l'introduzione alle API, d'ora in poi il discorso sarà guidato da esempi concreti, a partire dalla procedura necessaria per la creazione di un gruppo di opzioni nel menu "Impostazioni generali" di WordPress.