Rendre un widget de tableau de bord configurable

Il y a quelques semaines, nous avons vu comment ajouter une métabox de tableau de bord RSS personnalisée à l'administration. Aujourd'hui, j'aimerais vous montrer comment ajouter des options configurables à cette métabox de tableau de bord.

Voici le résultat de ce que nous allons faire :

La fonction la plus importante de ce didacticiel est wp_add_dashboard_widget(). C'est la fonction WordPress qui enregistre un widget de tableau de bord. Nous avons déjà vu qu'enregistrer le widget et la fonction qui affiche le widget sur le tableau de bord est assez simple, mais nous n'avions pas abordé le dernier paramètre de cette fonction. Fondamentalement, wp_add_dashboard_widget() a 4 paramètres :

$widget_id
(entier) (obligatoire) un slug d'identification pour votre widget. Celle-ci sera utilisée comme classe CSS et comme clé dans le tableau des widgets.
Par défaut : Aucun

$widget_name
(string) (obligatoire) c'est le nom que votre widget affichera dans son en-tête.
Par défaut : Aucun

$rappel
(string) (obligatoire) Le nom d'une fonction que vous créez qui affichera le contenu réel de votre widget.
Par défaut : Aucun

$control_callback
(string) (facultatif) Le nom d'une fonction que vous créez qui gérera la soumission des formulaires d'options de widget (configuration) et affichera également les éléments du formulaire.
Par défaut : Aucun

Comme vous pouvez le voir, le quatrième paramètre est celui responsable des options « configurer ». En remplissant ce paramètre vous indiquez à WordPress de charger une fonction spécifique pour configurer le widget. Il crée automatiquement un lien « configurer » dans le titre de la métabox lorsque vous placez le curseur dessus.

Étape 1 : Enregistrez la fonction de configuration des options

Ainsi, la première étape consiste à modifier l'appel wp_add_dashboard_widget() et à ajouter le nom des fonctions de configuration des options dans le dernier paramètre. Vos fonctions rc_mdm_register_widgets() devraient devenir :

/**
 * Register all dashboard metaboxes
 *
 * @access      public
 * @since       1.0 
 * @return      void
*/

function rc_mdm_register_widgets() {
	global $wp_meta_boxes;
	
	wp_add_dashboard_widget('widget_custom_rss', __('My RSS Feeds', 'rc_mdm'), 'rc_mdm_create_my_rss_box', 'rc_mdm_configure_my_rss_box');
}
add_action('wp_dashboard_setup', 'rc_mdm_register_widgets');

Nous avons simplement ajouté « rc_mdm_configure_my_rss_box » au dernier paramètre.

Étape 2 : Créer la fonction de configuration des options

Cette étape n’est pas compliquée. Tout ce que nous avons à faire est de créer des champs de formulaire stockés dans un tableau. Pour ce faire, nous utiliserons update_option(). Nous n’avons pas besoin de créer un formulaire complet puisque WordPress le crée pour nous. Il nous suffit d'enregistrer les champs. Un très bon point à mentionner est que WordPress ajoute automatiquement au formulaire une valeur occasionnelle qui sécurise le formulaire et évite d’éventuels problèmes de sécurité. Voici le code de notre fonction rc_mdm_configure_my_rss_box() (vous vous souvenez ? C'est le 4ème paramètre que nous avons défini dans wp_add_dashboard_widget() ).

/**
 * Creates the RSS metabox configuration settings
 *
 * @access      public
 * @since       1.0 
 * @return      void
*/
function rc_mdm_configure_my_rss_box( $widget_id ) {

	// Get widget options
	if ( !$rc_mdm_widget_options = get_option( 'rc_mdm_dashboard_widget_options' ) )
		$rc_mdm_widget_options = array();

	// Update widget options
	if ( 'POST' == $_SERVER['REQUEST_METHOD'] && isset($_POST['rc_mdm_widget_post']) ) {
		update_option( 'rc_mdm_dashboard_widget_options', $_POST['rc_mdm_widget'] );
	}
	
	// Retrieve feed URLs
	$url_1 = $rc_mdm_widget_options['url_1'];
	$url_2 = $rc_mdm_widget_options['url_2'];
	$url_3 = $rc_mdm_widget_options['url_3']; ?>

	<p>
		<label for="rc_mdm_url_1-"><?php _e('Enter the RSS feed URL #1:', 'rc_mdm'); ?></label>
		<input class="widefat" id="rc_mdm_url_1" name="rc_mdm_widget[url_1]" type="text" value="<?php if( isset($url_1) ) echo $url_1; ?>" />
	</p>
	
	<p>
		<label for="rc_mdm_url_2"><?php _e('Enter the RSS feed URL #2:', 'rc_mdm'); ?></label>
		<input class="widefat" id="rc_mdm_url_2" name="rc_mdm_widget[url_2]" type="text" value="<?php if( isset($url_2) ) echo $url_2; ?>" />
	</p>
	
	<p>
		<label for="rc_mdm_url_3"><?php _e('Enter the RSS feed URL #3:', 'rc_mdm'); ?></label>
		<input class="widefat" id="rc_mdm_url_3" name="rc_mdm_widget[url_3]" type="text" value="<?php if( isset($url_3) ) echo $url_3; ?>" />
	</p>
	
	<input name="rc_mdm_widget_post" type="hidden" value="1" />
	<?php
} ?>

Vous pouvez maintenant recharger votre tableau de bord, et si vous placez votre curseur sur la métabox du widget, vous verrez un lien « configurer » apparaître en haut à droite. Lorsque vous cliquez dessus, le formulaire d'options est chargé. Et lors du remplissage des champs et de l'enregistrement des URL du flux, les URL sont stockées dans notre table SQL d'options.

Étape 3 : Récupération des options

La dernière étape consiste à remplacer les URL de flux que nous avons codées en dur dans la première partie du didacticiel. De la ligne 14 à 18 dans rc_mdm_create_my_rss_box(), nous avons ajouté deux URL. Remplacez-le simplement par :

// My feeds list
if ( !$my_feeds = get_option( 'rc_mdm_dashboard_widget_options' ) )
    $my_feeds = array();

Et c'est tout! Nous avons réussi à ajouter facilement des options personnalisées à un widget de tableau de bord.