WordPress permette di aggiungere opzioni a pagine già esistenti del menu di amministrazione, oppure di creare nuove pagine, collegate a menu di primo livello o a uno dei vari sotto-menu. La prima alternativa, preferibile quando bisogna creare solo poche opzioni, è quella di aggiungerle ad una pagina già esistente, come la pagina "General" del menu "Settings".
Quando si sviluppa un tema, le opzioni vanno create all'interno del file functions.php.
Per rendere più ordinato e comprensibile il codice, potrebbe essere però opportuno non appesantire lo script, ma creare e includere un file dedicato esclusivamente alle opzioni. Quindi nel file functions.php si potrà semplicemente aggiungere la seguente istruzione:
require( get_template_directory() . '/inc/theme-options.php' );Il file theme-options.php ospita il primo esempio di questo articolo. Qui sarà verificato innanzi tutto che lo script venga eseguito solo nel pannello di amministrazione, e che l'utente abbia il privilegio di modificare le impostazioni dei temi:
if( is_admin() && !function_exists( 'seventyone_register_settings' ) ){
/**
* If user can't edit theme options, exit
*/
if ( !current_user_can( 'edit_theme_options' ) )
return;
...
}is_admin() è un conditional tag che verifica che l'utente acceda allo script dal pannello di amministrazione. current_user_can(), invece, verifica che l'utente abbia un dato livello di privilegio.
L'argomento è costituito da una stringa che individua il privilegio da testare (l'elenco dei privilegi è disponibile nella pagina Roles and Capabilities del Codex). Una volta effettuato il controllo sull'utente, si può dare accesso allo script e creare, quindi, le opzioni programmate. Il primo step è quello di individuare la pagina in cui inserire i campi di opzione: in questo primo esempio, si tratta della pagina delle impostazioni generali di WordPress.
Si ipotizzi di chiamare il tema "Seventyone", e si supponga che sia necessario aggiungere solo poche opzioni. Ad esempio, si potrebbe ritenere utile permettere all'utente admin di inserire i valori di alcuni meta tag nell'head del documento.
La creazione di un gruppo di opzioni nella pagina delle impostazioni generali con la Settings API segue le seguenti fasi:
- Creazione del gruppo di opzioni (o "Settings section");
- Creazione dei singoli campi;
- Registrazione delle singole opzioni.
All'interno del blocco condizionale descritto in precedenza, si definisce la funzione seventyone_register_settings() e la si aggancia all'hook admin_init.
All'interno di seventyone_register_settings() andranno invocate le funzioni con cui si creano i gruppi di opzioni, si aggiungono le singole opzioni e, infine, le si registrano nel database:
add_action( 'admin_init', 'seventyone_register_settings' );
function seventyone_register_settings(){
add_settings_section( ... );
add_settings_field( ... );
add_settings_field( ... );
register_setting( ... );
}I gruppi di opzioni vengono creati dalla funzione add_settings_section(). Questa accetta quattro argomenti, tutti obbligatori: l'ID del gruppo, il titolo, una funzione di callback che deve mandare a video un output, e, infine, lo slug della pagina dove il gruppo sarà visualizzato (in questo esempio, nella scheda "Generali" del menu "Impostazioni"). Ecco la funzione nel dettaglio:
function seventyone_register_settings(){
add_settings_section(
'seventyone_meta', // Identificativo univoco
__( 'Meta tags', 'seventyone' ),// title
'seventyone_options_callback', // callback
'general' // pagina di menu
);
...
}Quella che segue è la funzione di callback che aggiunge un markup personalizzato al gruppo di opzioni prima che questo venga mandato a video:
function seventyone_options_callback(){
echo "<p>Insert the values of meta tags</p>";
}Una volta aggiunto il gruppo, bisognerà creare le singole opzioni. Queste vanno prima di tutto registrate con la funzione register_settings():
function seventyone_register_settings(){
...
register_setting(
'general',
'meta_viewport'
);
...Quest'ultima funzione provvede a memorizzare in modo sicuro i dati relativi alle singole opzioni all'interno del database, e accetta tre argomenti, di cui i primi due obbligatori:
| Argomento | Descrizione |
|---|---|
| $option_group | (string) è l'identificativo del gruppo di opzioni. |
| $option_name | (string) è l'identificativo della singola opzione. |
| $callback | (string) è una funzione di callback che provvede alla messa in sicurezza dei dati prima della registrazione nel database. |
Sempre all'interno di seventyone_register_settings() si aggiungerà il codice che genera i singoli campi:
function seventyone_register_settings(){
...
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>'
)
);
...La funzione add_settings_field() aggiunge un campo ad uno specifico gruppo di opzioni di una data pagina del pannello di amministrazione. La funzione accetta sei argomenti, di cui i primi quattro obbligatori:
| Argomento | Descrizione |
|---|---|
| $id | (string) è l'identificativo del campo (nell'esempio meta_viewport). |
| $title | (string) il nome del campo (Viewport). |
| $callback | (string) è il nome della funzione di callback che genera il codice HTML del campo (seventyone_input_text). |
| $page | (string) è l'identificativo della pagina di menu su cui verrà visualizzato il campo (general). |
| $section | (string) è il gruppo di opzioni (o sezione della pagina) cui viene associato il campo (seventyone_meta). |
| $args | (string) è un array di argomenti arbitrari passati alla funzione di callback. |
Come anticipato, la funzione di callback genera il codice HTML del campo del form. Eccolo nel dettaglio:
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
}In questo caso la funzione di callback genera un semplice campo di testo. L'argomento della funzione è costituito dall'array inizializzato in add_settings_field().
Gli elementi dell'array assegnano i valori agli attributi dell'elemento input. Passando un array con questi dati, sarà possibile invocare la stessa funzione per generare più campi di testo.
Per generare il valore dell'attributo value, si è fatto ricorso ad un operatore ternario e alla funzione get_option() della Options API. La condizione verifica che la funzione get_option recuperi dal database un valore utile per l'opzione corrente.
In caso negativo, viene utilizzato il valore predefinito, memorizzato in $args['default']:
<?php echo ( !empty( get_option( $args['id'] ) ) ) ? get_option( $args['id'] ) : ( $args['default'] ); ?>Quello che segue sarà l'output della funzione:
<input id="meta_viewport" class="regular-text" type="text" name="meta_viewport" value="width=device-width, initial-scale=1.0">Quando l'amministratore trasmette i dati del form, questi vengono memorizzati nella tabella wp_options del database. Termina, così, il lavoro dal lato admin: bisogna ora visualizzare i dati nel front-end. Si ricorre di nuovo alla funzione get_option() che, come detto in precedenza, permette di accedere al database in modo sicuro. Grazie a get_option è possibile recuperare qualunque opzione, sia quelle predefinite (di cui all'elenco del Codex), sia quelle personalizzate.
La funzione restituisce una stringa di testo con il valore dell'opzione, oppure FALSE nel caso in cui non esista un valore corrispondente. L'opzione creata in questo esempio servirà, quindi, a creare il meta tag viewport. Nel file header.php, all'interno dell'elemento head, si aggiungerà la seguente istruzione:
if (true == get_option('meta_viewport'))
echo '<meta name="viewport" content="' . get_option("meta_viewport", "width=device-width, initial-scale=1.0") . '" />';get_option() accetta due argomenti: l'ID dell'opzione di cui si vuole recuperare il valore (obbligatorio), ed un eventuale valore predefinito da assegnare nel caso in cui la condizione non sia verificata. Se nella tabella wp_options non esiste un'opzione meta_viewport, allora get_option() restituisce TRUE e un valore corrispondente al secondo argomento.
Dopo che l'utente admin avrà salvato i dati delle opzioni, get_option() restituirà la stringa inserita in fase di trasmissione. Ma attenzione: se l'utente admin elimina il contenuto del campo meta_viewport, dal database viene recuperata una stringa vuota: in questo caso get_option() restituisce FALSE e il meta tag non viene generato: in questo modo l'amministratore può anche decidere di non inserire affatto il tag meta.
Poche opzioni possono, quindi, essere gestite in una pagina di configurazione già esistente.
Se però il tema si presenta ricco di impostazioni, bisognerà creare un sistema di amministrazione più complesso.
Nella prossima parte della guida verrà analizzata la procedura necessaria per creare menu e sottomenu nel pannello di amministrazione di WordPress.