Opzioni di un plugin di WordPress

Le opzioni per un plugin di WordPress sono un modo per permettere agli utenti di configurare il plugin secondo i propri bisogni. Le pagine delle opzioni sono pagine all’interno della sezione amministrativa di WordPress che contengono uno o più form dove si possono salvare dei valori.

Un’opzione viene salvata nella tabella wp_options con un nome e un valore. Per reperire il valore di un’opzione si usa la funzione get_option():

$value = get_option( 'my_test' );

In questo caso avremo il valore dell’opzione my_test.

Per impostare il valore di un’opzione, il metodo più usato è quello di utilizzare la funzione update_option():

$value = 'Hello world';
update_option( 'my_test', $value );

In questo caso il valore dell’opzione my_test sarà "Hello world".

Per cancellare definitivamente un’opzione si usa la funzione delete_option():

delete_option( 'my_test' );

Le settings API vs pagine custom

Le settings API di WordPress sono il metodo raccomandato per generare le opzioni di un plugin. Si tratta di un set di funzioni che automatizza la creazione dei form e il salvataggio dei dati. Contrapposte alle API ci sono le pagine amministrative custom che presentano il form per il salvataggio delle opzioni. Da un punto di vista strettamente pragmatico, entrambe le soluzioni assolvono il compito di salvare le opzioni nel database.

Tuttavia se con le API un form si presenta così:

<form method="post" action="options.php">
<?php settings_fields( 'my-settings-page' );
do_settings_sections( 'my-settings-page' );
submit_button(); ?>
</form>

Con una soluzione custom avremo invece:

<div id="message" class="update"><?php _e( ’Saved’, 'my-plugin' ); ?></div>
<?php } ?>
<form method="post" action="">
<p><p>
<input type="submit" value="Save" />
<input type="hidden" name="update_settings" value="Y" /></p>
</form>

Con una soluzione custom dobbiamo in pratica scrivere manualmente tutto quello che le API gestiscono in maniera molto più organizzata ed efficace. Ad esempio con le API il codice precedente può essere riscritto nel modo seguente:

function my_settings_api_init() {
        add_settings_section(
					'my_setting_section', // ID per la sezione e i campi
					’Titolo pagina opzioni’,
					'my_setting_section_callback_function',
					'reading' // Sezione sotto "Settings/Impostazioni" dove inserirla
				);
        // Aggiunge il campo il cui codice HTML verrà definito nel callback
        add_settings_field(
		'my_test',
		’Test’,
		'my_setting_callback_function',
		'reading',
		'my_setting_section'
	);
        register_setting( 'reading', 'my_test' );
        // Registra l’opzione my_test in modo che $_POST venga gestito automaticamente
    }
    add_action( 'admin_init', 'my_settings_api_init' );

A questo punto possiamo definire il codice HTML da usare all’inizio della sezione di opzioni:

function my_setting_section_callback_function() {
 	    _e( ’Test’, 'my-plugin' );
 }

Infine creiamo il codice HTML per il campo di input della nostra opzione:

function my_setting_callback_function() {
        echo '<input type="text" name="my_test" value="<?php echo get_option( 'my_test' ); ?>" />';
}

L’unico svantaggio delle Settings API è che ci costringe a creare le nostre opzioni in una delle pagine predefinite delle "Impostazioni" di WordPress. Per questo motivo in genere si preferisce utilizzare pagine custom da inserire nel menu laterale del backend di WordPress.

Creare pagine di opzioni custom

Seguendo la filosofia OOP usata sinora, possiamo creare una classe per gestire le opzioni dei nostri plugin:

<?php
    class My_Settings {
	public function __construct() {
		// Aggiungo la pagina al menu di amministrazione
		add_action( 'admin_menu', array( &$this, 'setupAdminMenus' ) );
	}
	public function setupAdminMenus() {
		add_menu_page( 'My Settings', 'Titolo della voce di menu', 'manage_options','my_settings', array( &$this, 'settingsPage' ) );
	}
	public function settingsPage() {
		// Output della pagina
?>
		 <?php // Il form è stato inviato?
		  if( isset( $_POST['update_settings'] ) ) {
			$my_test = esc_attr( $_POST['dcv_test'] ); // Valido l’input
			update_option( 'my_test', $my_test ); // Salvo l’opzione
?>
		<div id="message" class="updated">Settings saved</div>
		<?php } ?>
		<form method="post" action="">
		<p><input type="text" name="my_test" value="<?php echo get_option( 'my_test' ); ?>" />
		<input type="submit" value="Save" />
		<input type="hidden" name="update_settings" value="Y" /></p>
		</form>
<?php
}
}

Quindi nel file principale del nostro plugin non dobbiamo far altro che richiamare la classe e istanziarla:

require_once( 'My_Settings.php' );
    $my_plugin_settings = new My_Settings();

Come usare le opzioni

In linea di massima le opzioni di un plugin si dividono in due grandi categorie:

1. opzioni per il funzionamento;
2. opzioni per il comportamento.

Alla prima categoria appartengono quelle opzioni senza le quali il plugin non può funzionare, come ad esempio le chiavi per l’accesso alle API dei social network o dei Web services.

Alla seconda invece appartengono quelle opzioni che servono a modificare l’output fornito nel frontend, come ad esempio la scelta di un tema CSS o l’uso di un particolare plugin JavaScript.

La funzione get_option() per impostazione predefinita restituisce false se l’opzione specificata non esiste. Per questo motivo il nostro plugin dovrà avere sempre dei valori di fallback nel caso l’utente non modifichi le opzioni di base:

$default_theme = ( get_option( 'my_theme' ) ) ? get_option( 'my_theme' ) : 'default.css';

Ovviamente se l’utente deve specificare dei valori fondamentali per il funzionamento del plugin non possiamo far affidamento ai valori di fallback, come ad esempio nel caso delle chiavi delle API. In questo caso tutto il nostro codice sarà vincolato a tali valori:

if( !get_option( 'my_api_key' ) ) {
    // messaggio di errore nele backend
}

Riferimenti

1. get_option()
2. delete_option()
3. update_option()