I plugin di WordPress permettono di inserire nuove funzionalità nei blog o nei siti di e-commerce che si basano su questa tecnologia. Come già visto nell’articolo Sviluppare un plugin WordPress – creare la struttura iniziale, qualora non fosse disponibile un plugin che soddisfi a pieno le nostre esigenze, è possibile crearne la struttura in pochi clicks. Bisogna però popolarla! Un primo passo è definire una pagina di settings che gestisca le variabili che il nostro plugin utilizzerà.
In questo articolo analizzeremo dove inserire il codice per generare la pagina di settings e come salvare le impostazioni che l’utente fornirà in fase di configurazione.
Preparazione del plugin
Per chi non avesse letto ancora l’articolo Sviluppare un plugin WordPress – creare la struttura iniziale, riportiamo brevemente qui i principali passi da eseguire.
Per prima cosa dovrete collegarvi al sito del WordPress Plugin Boilerplate Generator. Compilando il form con le informazioni richieste, il software scaricherà sul vostro pc uno zip contente la struttura del nuovo plugin. Le funzioni principali per installarlo su un sito WordPress sono già incluse!
La struttura che utilizzeremo per questo tutorial è la seguente.
La struttura è alquanto articolata ma allo stesso tempo ben strutturata per inserire in modo semplice e veloce le funzioni che ci serviranno. Scopriamo come.
Definizione dei parametri
Prima ancora di sviluppare la pagina dei settings, bisogna identificare quali saranno le opzioni che potranno essere definite dall’amministratore del sito. Questo passo esula dal tutorial perchè dipende molto dal progetto su cui si sta lavorando. Ad esempio, potrebbe essere utile impostare una durata espressa in giorni per la validità di un quiz o un post fatto dagli utenti registrati. Alcuni plugins, specialmente quelli a pagamento, richiedono l’inserimento di alcune credenziali per l’attivazione di funzionalità avanzate o della fruizione di un servizio remoto. In questo caso potrebbero essere richiesti un campo di tipo testuale per l’inserimento di un token o le credenziali di accesso (username e password). Potete sicuramente ispirarvi ai plugin già disponibili per comprendere al meglio le vostre esigenze.
Una volta definiti i parametri delle impostazioni del nostro plugin, possiamo iniziare a creare la pagina che verrà utilizzata per visualizzare il form relativo. In questo esempio andremo ad inserire un paio di campi. Ovviamente, a seconda della complessità del plugin, la pagina dei settings potrebbe diventare molto più articolata.
Definiamo, quindi, i parametri del nostro plugin. Nel nostro esempio inseriremo un campo booleano e un campo numerico. Apriamo il file class-flowygo-admin.php (che trovate nella cartella admin) e aggiungiamo una variabile chiamata option_name. Il suo valore verrà utilizzato come suffisso per i parametri e le funzioni che utilizzeremo. Il consiglio è di aggiungerla subito prima della funzione __construct.
/**
* The options name to be used in this plugin
*
* @since 1.0.0
* @access private
* @var string $option_name Option name of this plugin
*/
private $option_name = 'flowygo_setting'; Creiamo una nuova funzione public per la registrazione delle variabili dei settings. Di seguito è riportato il codice della funzione denominata register_flowygo_plugin_settings.
/**
* Register the setting parameters
*
* @since 1.0.0
* @access public
*/
public function register_flowygo_plugin_settings() {
// Add a General section
add_settings_section(
$this->option_name. '_general',
__( 'General', 'flowygo' ),
array( $this, $this->option_name . '_general_cb' ),
$this->plugin_name
);
// Add a boolean field
add_settings_field(
$this->option_name . '_bool',
__( 'Boolean setting', 'flowygo' ),
array( $this, $this->option_name . '_bool_cb' ),
$this->plugin_name,
$this->option_name . '_general',
array( 'label_for' => $this->option_name . '_bool' )
);
// Add a numeric field
add_settings_field(
$this->option_name . '_number',
__( 'Number setting', 'flowygo' ),
array( $this, $this->option_name . '_number_cb' ),
$this->plugin_name,
$this->option_name . '_general',
array( 'label_for' => $this->option_name . '_number' )
);
// Register the boolean field
register_setting( $this->plugin_name, $this->option_name . '_bool', array( $this, $this->option_name . '_sanitize_bool' ) );
// Register the numeric field
register_setting( $this->plugin_name, $this->option_name . '_number', 'integer' );
} La prima funzione add_settings_section serve per inserire una descrizione generale nella pagina dei settings. Differentemente la funzione add_setting_field serve per definire un campo dei settings del nostro plugin. Nel dettaglio, il primo parametro è la concatenazione della variabile option_name con una string a nostro piacimento. In questo modo evitiamo che ci siano conflitti sui nomi delle opzioni tra il nostro plugin e quelli che utilizzeremo nel sito.
Il secondo parametro definisce il titolo che verrà mostrato nella pagina dei settings.
Il terzo parametro è la funzione di callback che verrà richiamata per visualizzare in modo opportuno il campo che dovrà essere compilato. Vedremo successivamente come scriverle.
Infine gli ultimi parametri definiscono il nome della pagina dei settings, la sezione a cui appartengono e i parametri passati per il rendering.
Al fine di visualizzarli correttamente nella pagina dei settings, dobbiamo utilizzare la funzione register_setting per ciascun campo definito in precedenza. I parametri passati a questa funzione sono il nome del plugin, il nome del campo definito in precedenza e gli argomenti che servono a determinare la tipologia del dato o la funzione per effettuare il sanitize dei valori sottomessi.
Callbacks dei settings
Come abbiamo visto nella sezione precedente, per ogni campo che definiamo bisogna inserire delle funzioni di callback adibite alla generazione del codice html relativo. Aggiungiamo quindi queste funzioni sempre nel file class-flowygo-admin.php.
Iniziamo dalla funzione per generare il testo della sezione. In questo caso la funzione stamperà un semplice messaggio. Potete ovviamente cambiare la tipologia di messaggio a vostro piacimento come anche la sua impaginazione. Il codice della funzione flowygo_setting_general_cb è riportato di seguito.
/**
* Render the text for the general section
*
* @since 1.0.0
* @access public
*/
public function flowygo_setting_general_cb() {
echo '<p>' . __( 'Please change the settings accordingly.', 'flowygo' ) . '</p>';
} Per il campo numerico, la funzione dovrà invece visualizzare un input di questa tipologia. Per mostrare anche il valore salvato in precedenza bisognerà richiamare la funzione get_option. Questa funzione permette di recuperare il valore salvato a database per l’opzione identificata dal nome passato come parametro.
/**
* Render the number input for this plugin
*
* @since 1.0.0
* @access public
*/
public function flowygo_setting_number_cb() {
$val = get_option( $this->option_name . '_number' );
echo '<input type="text" name="' . $this->option_name . '_number' . '" id="' . $this->option_name . '_number' . '" value="' . $val . '"> ' . __( '(unity of measure)', 'flowygo' );
} Un pò più complesso è il caso di valori booleani. In questo caso useremo un radio button per visualizzare le due opzioni. La prima istruzione recupererà il valore da db. Useremo poi la funzione checked, fornita da WordPress, per selezionare il valore precedentemente salvato. Di seguito il codice.
/**
* Render the radio input field for boolean option
*
* @since 1.0.0
* @access public
*/
public function flowygo_setting_bool_cb() {
$val = get_option( $this->option_name . '_bool' );
?>
<fieldset>
<label>
<input type="radio" name="<?php echo $this->option_name . '_bool' ?>" id="<?php echo $this->option_name . '_bool' ?>" value="true" <?php checked( $val, 'true' ); ?>>
<?php _e( 'True', 'flowygo' ); ?>
</label>
<br>
<label>
<input type="radio" name="<?php echo $this->option_name . '_bool' ?>" value="false" <?php checked( $val, 'false' ); ?>>
<?php _e( 'False', 'flowygo' ); ?>
</label>
</fieldset>
<?php
} L’ultima funzione che dobbiamo inserire è quella relativa al salvataggio dei valori del radio button. Inseriamo quindi una funzione chiamata flowygo_setting_sanitize_bool, che permetterà di salvare solo certi valori nel database. Questo è particolarmente utile quando si ha a che fare con opzioni che sono limitate a valori specifici. Nel nostro caso accetteremo solo due valori: true e false. La funzione verificherà se il valore passato appartiene all’insieme definito. In caso positivo il valore verrà salvato a database, diversamente sarà scartato.
Creazione della pagina dei settings
A questo punto abbiamo definito i parametri del nostro plugin e come questi devono essere visualizzati. Non resta che inserire la pagina relativa.
Come primo passo modifichiamo il file flowygo-admin-display.php che troviamo nel percorso admin/partials. Per visualizzare tutte le nostre opzioni dobbiamo semplicemente inserire la seguente porzione di codice alla fine del file.
<div class="wrap">
<h2><?php echo esc_html( get_admin_page_title() ); ?></h2>
<form action="options.php" method="post">
<?php
settings_errors();
settings_fields( $this->plugin_name );
do_settings_sections( $this->plugin_name );
submit_button(); ?>
</form>
</div> Tramite poche funzioni fornite da WordPress verranno inclusi i campi definiti in precedenza e un bottone per salvarli. In particolare, la funzione settings_errors mostrerà i messaggi informativi. Ad esempio, ci avviserà se le modifiche sono state salvate correttamente o se si è verificato un errore. Le funzioni settings_fields e do_settings_sections visualizzeranno i campi e le sezioni definite in precedenza. Infine la funzione submit_button inserirà un pulsante per salvare le opzioni inserite dall’utente.
Aggiunta del menu al pannello amministratore
L’ultimo passo è inserire la nostra pagina dei settings nel pannello dell’amministratore. Per far ciò dobbiamo inizialmente definire una variabile globale per gestire opportunamente il path. Inseriamo nel file principale flowygo.php la seguente linea di codice subito dopo la definizione della versione del plugin ( define( ‘FLOWYGO_VERSION’, ‘1.0.0’ ) ; )
!defined('FLOWYGO_PATH') && define('FLOWYGO_PATH', plugin_dir_path( __FILE__ )); Torniamo nel file class-flowygo-admin.php e aggiungiamo una funzione che includa il file flowygo-admin-display.php al momento dell’inizializzazione del plugin.
/**
* Include the setting page
*
* @since 1.0.0
* @access public
*/
function flowygo_init(){
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
include FLOWYGO_PATH . 'admin/partials/flowygo-admin-display.php' ;
} Possiamo quindi aggiungere la pagina del menù come mostrato di seguito. Per personalizzare l’icona associata nella barra laterale del pannello dell’amministratore, è sufficiente passare come ultimo parametro il nome di un’icona fornita da WordPress. Trovate la galleria delle icone disponibili nella documentazione ufficiale.
public function flowygo_plugin_setup_menu(){
add_menu_page( 'flowygo settings', 'Flowygo', 'manage_options', 'flowygo', array($this, 'flowygo_init'), 'dashicons-welcome-learn-more' );
} Non resta che istruire WordPress durante l’attivazione plugin di quali funzioni usare per aggiungere le opzioni e la pagina del menù. Apriamo il file class-flowygo.php nella cartella includes e aggiungiamo le seguenti linee di codice all’interno della funzione define_admin_hooks.
$this->loader->add_action( 'admin_init', $plugin_admin, 'register_flowygo_plugin_settings' );
$this->loader->add_action( 'admin_menu', $plugin_admin, 'flowygo_plugin_setup_menu'); Installazione del plugin
Una volta apportate tutte le modifiche descritte in precedenza non rimane che caricare il plugin. Per poterlo fare dobbiamo comprimere la cartella in uno zip. Dopodichè, basterà andare nella sezione plugin, caricare lo zip creato e attivarlo. Dopo l’attivazione vedremo comparire il menù del nostro plugin con l’icona scelta. Selezionandolo visualizzeremo la pagina dei settings dove salveremo le nostre preferenze.
