WordPress.org

Dashboard Widgets API

With the release of WordPress 2.7 a new Dashboard Widgets API was introduced that makes it very simple to add new widgets to the administration dashboard. Doing so requires working knowledge of PHP and the WordPress Plugin API, but to plugin or theme authors familiar with hooking actions and filters it only takes a few minutes and can be a great way to make your plugin even more useful.

Overview

The Function

The main tool needed to add Dashboard Widgets is the wp_add_dashboard_widget() function:

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback = null)

$widget_id - an identifying slug for your widget. This will be used as its css class and its key in the array of widgets.
$widget_name - this is the name your widget will display in its heading
$callback - The name of a function you create that will display the actual contents of your widget.
$control_callback - (Optional) The name of a function you create that will handle submission of widget options forms, and will also display the form elements.

The Action

To run the function you will need to hook into the correct action, in this case, 'wp_dashboard_setup'. Here's how it looks in the core code:

do_action( 'wp_dashboard_setup' );

Examples

Add an Example Widget

Here's the most bare outline of a widget I could come up with.

// Create the function to output the contents of our Dashboard Widget

function example_dashboard_widget_function() {
	// Display whatever it is you want to show
	echo "Hello World, I'm a great Dashboard Widget";
} 

// Create the function use in the action hook

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');	
} 

// Hook into the 'wp_dashboard_setup' action to register our other functions

add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

Advanced: Forcing your widget to the top

Normally you should just let the users of your plugin put your Dashboard Widget wherever they want by dragging it around. There currently isn't an easy API way to pre-sort the default widgets, meaning your new widget will always be at the bottom of the list. Until sorting is added to the API its a bit complicated to get around this problem.

Below is an example hooking function that will try to put your widget before the default ones. It does so by manually altering the internal array of metaboxes (of which dashboard widgets are one type) and putting your widget at the top of the list so it shows first.

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');
	
	// Globalize the metaboxes array, this holds all the widgets for wp-admin

	global $wp_meta_boxes;
	
	// Get the regular dashboard widgets array 
	// (which has our new widget already but at the end)

	$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
	
	// Backup and delete our new dashbaord widget from the end of the array

	$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
	unset($normal_dashboard['example_dashboard_widget']);

	// Merge the two arrays together so our widget is at the beginning

	$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);

	// Save the sorted array back into the original metaboxes 

	$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}

Unfortunately this only works for people who have never re-ordered their widgets. Once a user has done so their existing preferences will override this and they will have to move your widget to the top for it to stay there.

Advanced: Removing Dashboard Widgets

In some situations, especially on multi-user blogs, it may be useful to completely remove widgets from the interface. Each individual user can, by default, turn off any given widget using the "Screen Options" tab at the top, but if you have a lot of non-technical users it might be nicer for them to not see it at all.

At this point (2.7.0) there is no function to easily remove the default dashboard widgets. To remove them you need to manually unset() their items from the general $wp_meta_box array. You can do so inside the wp_dashboard_setup action similar to how we added widgets.

Here are the names of the meta boxes on the dashboard:
Main column
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']

Side Column
$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']

To print the list of names in either the normal or side columns, you can use this code (subbing in normal or core for the second position in the array):

foreach (array_keys($wp_meta_boxes['dashboard']['normal']['core']) as $name){
		echo ("<p>");
		echo ($name);
		echo("</p>");
		
	}

Here is an example function that removes the quickpress and incomming_links widgets by unsetting their array items.

// Create the function to use in the action hook

function example_remove_dashboard_widgets() {
	// Globalize the metaboxes array, this holds all the widgets for wp-admin

	global $wp_meta_boxes;

	// Remove the quickpress widget

	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']);

	// Remove the incomming links widget

	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']);	
} 

// Hoook into the 'wp_dashboard_setup' action to register our function

add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );

Aggregating RSS feeds in the dashboard

Because so many of the default dashboard widgets are designed to aggregate RSS feeds about WordPress development and plugins there is already a lot of work done to make this easier. I don't have time to figure out a full example, but if you need to aggregate RSS in your widget I recommend looking at the way the existing plugins are set up with caching in /wp-admin/includes/dashboard.php.