Aggiungere un nuovo menu al pannello di amministrazione

Il framework di WordPress permette di creare menu di primo livello e sottomenu all'interno del pannello di amministrazione, offrendo quindi maggiore rilevanza alla configurazione del software aggiuntivo.

Nello specifico, la funzione add_menu_page() crea una nuova voce nel menu di amministrazione, questa va agganciata all'hook admin_menu, altrimenti WordPress restituirà un messaggio di errore. L'uso corretto della funzione, quindi, è il seguente:

add_action( 'admin_menu', 'seventyone_add_menus' );
function seventyone_add_menus(){
	add_menu_page(
		__('Seventyone settings', 'seventyone'),
		'Seventyone',
		'edit_theme_options',
		'seventyone_menu',
		'seventyone_menu_settings_page',
		'',
		61
	 );
}

add_menu_page() accetta sette argomenti, di cui quattro obbligatori e tre facoltativi:

Argomento	Descrizione
$page_title	(string) è il titolo della pagina come appare nel pannello di amministrazione (Seventyone settings).
$menu_title	(string) è il titolo che appare nella pagina del menu (Seventyone).
$capability	(string) è il livello di privilegio che l'utente deve avere per accedere al menu (edit_theme_options).
$menu_slug	(string) è l'identificativo del menu (seventyone_menu).
$function	(string) è la funzione che genera la pagina di configurazione.
$icon_url	(string) è l'indirizzo di una eventuale icona da associare al menu.
$position	(int) è la posizione del menu nel pannello di amministrazione. Il valore "61" colloca il menu subito al di sotto del menu "Appearence"; ma se due plugin utilizzano lo stesso valore solo uno dei due menu sarà visualizzato.

Potrebbe essere più prudente, quindi, non utilizzare quest'ultimo parametro (si legga il codex per maggiori informazioni).

La funzione seventyone_menu_settings_page() genera il markup della pagina delle impostazioni:

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

Prima di completare il codice della funzione seventyone_menu_settings_page(), già descritta in precedenza, bisognerà definire uno o più gruppi di opzioni con i rispettivi campi; si aggiungano quindi l'hook admin_init e la funzione di callback seventyone_register_settings():

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

Dal punto di vista strutturale, il codice è identico all'esempio precedente; cambiano, però, i valori di alcuni degli argomenti passati alle funzioni. Si aggiunga, quindi, un nuovo gruppo di opzioni:

add_settings_section(
	'seventyone_meta',
	__( 'Meta tags', 'seventyone' ),
	'seventyone_options_callback',
	'seventyone_menu'
);

Non cambia nulla se non il quarto argomento, che in questo caso corrisponde allo slug del nuovo menu Seventyone. La funzione di callback, invece, rimane invariata:

function seventyone_options_callback(){
	echo "<p>Insert the values of meta tags</p>";
}

Si aggiunge, poi, il campo di opzione:

add_settings_field(
	'meta_viewport',
	__( 'Viewport', 'seventyone' ),
	'seventyone_input_text',
	'general',
	'seventyone_meta',
	array(
		'id' => 'meta_viewport',
		'type' => 'text',
		'class' => 'regular-text',
		'default' => 'width=device-width, initial-scale=1.0',
		'description' => '<p class="description">Are you sure?</p>'
	)
);

Infine, si registrano le opzioni:

register_setting(
	'seventyone_meta',
	'meta_viewport'
);

Quindi si definisce la funzione di callback, che rimane invariata rispetto a quella illustrata in precedenza:

function seventyone_input_text( $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
}

La figura mostra il risultato di questo esempio. Nella prossima parte si metteranno a confronto le due API e si creerà un menu strutturato su più livelli.