In Rete sono disponibili diversi strumenti, plugin e framework, che facilitano l'aggiunta di una o più pagine di opzioni al pannello di amministrazione in modo semiautomatico. Tuttavia, non sempre questi strumenti sono adattabili ad esigenze particolari, e implicano comunque la dipendenza da uno sviluppatore terzo.
Quindi, potrebbe rivelarsi più opportuno creare il proprio pannello di amministrazione utilizzando due set di funzioni specifiche del framework di WordPress: la Options API e la Settings API.
In questa guida si mostrerà, quindi, con un'analisi teorica e diversi esempi pratici, come utilizzare le due API (Application Programming Interface) e creare pagine di opzioni di vario tipo.
La Options API
La Options API è costituita da un insieme di funzioni, definite nel file /wp-includes/option.php, che permettono di accedere in modo sicuro alla tabella wp_options del database.
È, così, possibile creare nuove opzioni, modificarle, cancellarle o semplicemente leggerne i valori, senza doversi preoccupare di creare alcuna query. La creazione di un pannello di amministrazione avviene attraverso le seguenti fasi:
- definizione della pagina (o delle pagine) di configurazione;
- aggiunta e registrazione delle opzioni;
- accesso ai valori delle opzioni.
Per aggiungere un'opzione personalizzata, l'API fornisce la funzione add_option, la quale permette di creare una nuova opzione e di memorizzarla nel database. add_option accetta quattro argomenti, di cui i primi due obbligatori:
| Argomento | Descrizione |
|---|---|
| $option | (string) è l'identificativo univoco dell'opzione |
| $value | (string) è il valore predefinito dell'opzione |
| $deprecated | (string) deprecato |
| $autoload | (string) è una stringa i cui valori possono essere yes o no e che stabilisce se caricare automaticamente l'opzione |
La funzione non fa nulla se l'opzione esiste già nel database.
Nello sviluppo di un tema, il metodo add_option va agganciato all'action hook admin_init:
add_action( 'admin_init', 'my_theme_options' );
function my_theme_options(){
add_option(
'my_option_name', // Option name
'my_option_value' // Default value
);
register_setting(
'my_option_group_name', // Settings group name
'my_option_name' // Option name
);
}All'hook admin_init non è stato agganciato il solo metodo add_option.
Oltre all'archiviazione nel database, infatti, le opzioni vanno aggiunte ad un elenco di opzioni consentite e associate ad un gruppo di opzioni.
La funzione fornita dal framework è register_setting. Nel caso si stesse invece sviluppando un plugin, bisognerà ricorrere al metodo register_activation_hook, che registra la funzione di callback tramite la quale saranno aggiunte le opzioni:
register_activation_hook( __FILE__, 'my_plugin_add_options' );
function my_plugin_add_options(){
add_option(
'my_option_name', // Option name
'my_option_value' // Default value
);
}register_activation_hook accetta due argomenti: una stringa contenente il percorso al file principale del plugin, e la funzione di callback da eseguire alla sua attivazione. In questo momento le opzioni verranno memorizzate nel database.
La registrazione, invece, avviene, come per i temi, all'avvio del pannello di amministrazione:
add_action( 'admin_init', 'my_plugin_register_options' );
function my_plugin_register_options(){
register_setting(
'my_option_group_name', // Settings group name
'my_option_name' // Option name
);
}Effettuate le operazioni di aggiunta e registrazione, i valori delle opzioni potranno essere recuperati grazie alla funzione get_option.
Questa accetta due argomenti, entrambi obbligatori:
| Argomento | Descrizione |
|---|---|
| $option | (string) è l'identificativo univoco dell'opzione |
| $value | (string) è il valore predefinito dell'opzione |
Nel caso delle opzioni personalizzate, aggiunte quindi tramite plugin o temi, il primo argomento dovrà corrispondere ai valori passati ai metodi add_option e register_settings.
È qui opportuno sottolineare che WordPress dispone di un cospicuo numero di opzioni predefinite, i cui valori potranno essere recuperati sempre grazie al metodo get_option (per l'elenco completo delle opzioni predefinite, si legga la Option Reference del Codex).
add_option e get_option sono gli unici metodi della Options API che saranno utilizzati durante tutto il corso di questa guida. Per una descrizione dettagliata di tutte le funzionalità dell'API, si rinvia alla corposa documentazione del Codex:
Termina qui la presentazione del primo set di funzioni. Nella prossima parte della guida verrà effettuata una presentazione della Settings API.