Adding Configurable Options to a WordPress Dashboard Metabox
In a previous tutorial, we learned how to add a custom RSS dashboard metabox to the WordPress administration. In this tutorial, we will take it a step further and show you how to add configurable options to this dashboard metabox.
The most important function in this tutorial is wp_add_dashboard_widget(). This WordPress function registers a dashboard widget. We have already seen that registering the widget and the function that outputs the widget on the dashboard is pretty easy, but we had not covered the last parameter of this function. Basically, wp_add_dashboard_widget() has four parameters:
$widget_id(integer) (required) – an identifying slug for your widget. This will be used as its CSS class and its key in the array of widgets. Default: None
$widget_name(string) (required) – this is the name your widget will display in its heading. Default: None
$callback(string) (required) – The name of a function you create that will display the actual contents of your widget. Default: None
$control_callback(string) (optional) – The name of a function you create that will handle submission of widget options (configuration) forms, and will also display the form elements. Default: None
As you can see, the fourth parameter is the one responsible for the “configure” options. When filling this parameter, you tell WordPress to load a specific function to configure the widget. It automatically creates a “configure” link in the metabox title when you place the cursor over it.
Step 1: Register The Configure Options Function
The first step is to modify the wp_add_dashboard_widget() call and add the name of the configure options functions in the last parameter. Your rc_mdm_register_widgets() function should become:
/**
* 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’);
We simply added “rc_mdm_configure_my_rss_box” to the last parameter.
Step 2: Create The Configure Options Function
This step isn’t complicated. All we have to do is to create form fields stored into an array. To do so, we’ll use the update_option(). We don’t need to create a full form as WordPress creates it for us. We just need to register the fields. A very good point to mention is that WordPress automatically adds to the form a nonce that makes the form secure and avoids potential security problems. Here is the code of our rc_mdm_configure_my_rss_box() function:
/**
* 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’]; ?>
}
You can now reload your dashboard, and if you place your cursor on the widget metabox, you’ll see a “configure” link appearing on the top right. When you click on it, the options form is loaded. And when filling the fields and saving, the feed URLs are stored in our options SQL table.
Step 3: Retrieving Options
The last step is to replace the feed URLs we hard-coded in the first part of the tutorial. From line 14 to 18 in rc_mdm_create_my_rss_box(), we added two URLs. Simply replace it by:
// My feeds list
if ( !$my_feeds = get_option( ‘rc_mdm_dashboard_widget_options’ ) )
$my_feeds = array();
And that’s it! We managed to add custom options to a dashboard widget quite easily.
