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 option groups
3. Definizione delle singole opzioni.
4. Accesso ai valori delle opzioni.

Una settings section add_settings_section

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
$title	(string
$callback	(string
$page	(string

Il metodo add_settings_section admin_init

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 add_settings_field admin_init

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 admin_init

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 value get_option $args

Le alternative sono diverse: WordPress, infatti, permette di aggiungere opzioni ad una pagina già esistente

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() WP_Theme settings_fields nonce action ption_page

Infine, do_settings_sections submit_button

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.

Ti consigliamo anche

CMS

WordPress: 5 alternative "light" a Yoast SEO e Rank Math

CMS

I migliori CMS per e-commerce a confronto

CMS

Ottimizzare il database di WordPress, guida pratica

CMS

WordPress: pagina Contatti personalizzata con Elementor

Argomento	Descrizione
$id	(string id input
$title	(string
$callback	(string input
$page	(string
$section	(string id settings section
$args	(array