Add WordPress Dashboard Widgets

Monday October 27th, 2008 by Frank • WordPress Hacks • 8 Comments

Finally WordPress 2.7 is coming along with widgets in the dashboard area, so it will be possible to adjust your dashboard as you like.

For plugin or theme authors it's even more interesting, since they can give the users additional value to their plugins. They can offer information from their plugin directly on the dashboard. The user can decide if he likes to display them or not.

It's easy to integrate and can be controlled like Meta Boxes (explained in detail). The following example shows how you can integrate a widget in a dashboard.

WP 2.7 with new Widget in Dashboard

The above screenshot shows that I addes the widget Test My Dashboard. Also you can see the possibility to deactivate the widget in the menu.

/**
 * Content of Dashboard-Widget
 */
function my_wp_dashboard_test() {
	echo 'Test Add Dashboard-Widget';
}
 
/**
 * add Dashboard Widget via function wp_add_dashboard_widget()
 */
function my_wp_dashboard_setup() {
	wp_add_dashboard_widget( 'my_wp_dashboard_test', __( 'Test My Dashboard' ), 'my_wp_dashboard_test' );
}
 
/**
 * use hook, to integrate new widget
 */
add_action('wp_dashboard_setup', 'my_wp_dashboard_setup');

The function wp_add_dashboard_widget() is the key, which delivers the new widget; via hook wp_dashboard_setup it will be activated on the dashboard.

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

The function needs 3 parameters and an additional one is optional.

1. The ID, first parameter,will be used to deactivate the widget via JavaScript. In the Menu:

   <label for="my_wp_dashboard_test-hide"><input class="hide-postbox-tog" name="my_wp_dashboard_test-hide" type="checkbox" id="my_wp_dashboard_test-hide" value="my_wp_dashboard_test" checked="checked" />Test My Dashboard</label>

   and also in the widget:

   <div id="my_wp_dashboard_test" class="postbox " >
   <h3 class='hndle'><span>Test My Dashboard</span></h3>
   <div class="inside">Test Add Dashboard-Widget</div>
   </div>

2. The second parameter delivers the name, which will be displayed, wrapped in an h3-tag.

   <h3 class='hndle'><span>Test My Dashboard</span></h3>

3. With the help of the third parameter the third function gets delivered, it contains the content of the widget. The echo does not take place, you have to use it explicitly. Therefore not only the content can be displayed, which makes it more flexible.

Hint

The hook activity_box_end, which is available since version 2.3, still exists. It adds the content in widget „Right Now“.