Add WordPress Dashboard Widgets

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

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“.

Update

Nice to read: a update of this post to include options in the dashboard widget: How add options to your WordPress 2.7 dashboard widgets

Comments are closed.

36 comments

  1. weston deboer

    Thanks so much for this!

    Works perfectly.

  2. Alex

    Excellent bit of information

  3. Alex

    We are happy it's working out for you just perfectly :)

  4. seeeb17

    hi, I've got a plugin like WP e-commerce that create a widget on dasboard, but it doesn't work with 2.7...

    In fact, widget is integrated in the "right now" widget.

    I'm french, I don't know if I'm understood, so I made a print screen :

    http://img392.imageshack.us/img392/9097/tableau03ya4.gif

    Can you help me?

  5. Rick

    Great info!

    Just one question: How can we add the 'Configure widget' feature?

    Thanks!

  6. Adegans

    Rick, have the widget use a function with your stuff ofcourse and put the settings for it in the settings panel

  7. Alex

    Rick, you can add a link directly in the h3-tag to your settings. That should work.

  8. Rick

    I mean the feature, not the link :)

    Involves a 4th(and optional) argument in the wp_add_dashboard_widget(), but I'm still investigating :)

  9. AdamB

    Rick is correct. The 4th parameter calls a function to display configuration options. WP will automatically add the link in the corner to pull this up.

  10. AdamB

    I traced it back to this function:
    s/wp-admin/includes/dashboard.php

    function _wp_dashboard_control_callback( $dashboard, $meta_box ) {
    echo '';
    wp_dashboard_trigger_widget_control( $meta_box['id'] );
    echo "";

    echo '';
    }

    then get a bit lost when it gets to here:

    wp_dashboard_trigger_widget_control( $meta_box['id'] );

    Any help? I just want to give a couple of options to set. I'd rather not create a page under settings for this when the option to set it right there is available.

    Thanks in Advance...
    Adam

  11. Rick

    Adam, check this:

    http://rick.jinlabs.com/2009/02/01/how-add-options-to-your-wordpress-27-dashboard-widgets/

  12. ckd

    I am trying to create a simple widget with a control panel. Everything is working except for when user enters website address in control panel, when link is clicked on in the theme it just refreshes the page instead of taking user to the website. I have created my widgets in a file called 'widgets.php' and all work fine, just need to figure out how to get user enetered links to work. You can see the code below:

    ` function twitterWidget()
    {
    $settings = get_option("widget_twitterwidget");

    $title = $settings['title'];
    $twiturl = $settings['twiturl'];

    ?>

    <img src="" height="16" width="16" alt=""/> <a href="">

    <?php
    }

    // Twitter Widget
    function twitterWidgetAdmin() {

    $settings = get_option("widget_twitterwidget");

    // check if anything's been sent
    if (isset($_POST['update_twitter'])) {
    $settings['title'] = strip_tags(stripslashes($_POST['twitter_title']));
    $settings['twiturl'] = strip_tags(stripslashes($_POST['twitter_twiturl']));
    update_option("widget_twitterwidget",$settings);
    }

    echo '
    Title:
    ';
    echo '
    Twitter URL:
    ';
    echo '';

    }

    register_sidebar_widget('Twitter', 'twitterWidget');
    register_widget_control('Twitter', 'twitterWidgetAdmin', 400, 200);`

    Any help would be greatly appreciated.

    Thanks

  13. AdamB

    How could i even over look the obvious. Damn, musta been asleep that day.

    Thanks!!

    Adam

  14. Shagshag

    Thanks so much for this!

  15. Mark

    Can anyone provide a snippet for hiding/showing a dashboard widget based on user roles?

    Thanks.

  16. Frank

    @Mark: small snippet with example, i hope you understand this.

    // 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
    	// use the ID of the widget
    	// Example: dashboard_quick_press
    	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']);	
    } 
    
    // check user role
    // if NOT (!) admin: don't see the widgets
    // @link:http://codex.wordpress.org/Roles_and_Capabilities
    if ( !current_user_can('administrator') ) {
    	// Hoook into the 'wp_dashboard_setup' action to register our function
    	add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );
    }
    

  17. Mark

    Thanks Frank. I separated out the widget into an include and used the following code within the plugin. Maybe I should explain what I was doing. I found a plugin to create a To-Do list and wanted the list shown in the dashboard when users with particular roles logged in. This is what I ended up with:

    // --------------------------------------------------------------------
    // Dashboard widget
    // --------------------------------------------------------------------
    //Pre-check user status and role and show only to allowed roles
    function hide_show_assignboard(){
    if(is_user_logged_in) { // only if there is a user logged in
    require (ABSPATH . WPINC . '/pluggable.php');
    $logged_user = wp_get_current_user();
    $user_roles = $logged_user->roles; // an array of roles
    foreach($user_roles as $user_role)
    {
    if($user_role=='administrator' || $user_role=='intern' ||$user_role=='editor')
    include('dashboard.php');}
    }
    }
    hide_show_assignboard();

    I discovered late last night that I had to use this line to prevent an error that had me pulling out my hair:
    require (ABSPATH . WPINC . '/pluggable.php');

    Would your code be placed in the widget? I could send you an archive of the modified plugin.

  18. Hassan

    Hi how can I login to wordpress dashboard and to Design-> Widgets on my computer? I want to transfer a donate button code to my website To create a donate button but I don't how. Could you tell me how.
    Thanks

  19. Mark

    There's Paypal donate plugin at http://wordpress.org/extend/plugins/wordpress-paypal-donations-plugin/

    You could search the WP plugins and widgets databases for others. Why reinvent the wheel?

    If you want to create a sidebar widget with a donate button, you could use the example widget code at WP and insert your Paypal button code.

  20. Basilakis

    Seems that, i do not get any "visible" options at the Screen option menu... Seems that it does not pass there... And i have had just copy pasted the code :?

  21. php trivandrum

    Really Great..

    I was searching for 'wordpress dashboard widget', and found your post. This saved me a lot.

  22. Alex McFarlane

    I have been looking at removing the dashboard widgets in WP 2.8.4. This is my plugin code, you should just be able to add the id of the widget you want to remove.

    add_action('do_meta_boxes', array(&$this, 'do_meta_boxes'),10,3);

    function do_meta_boxes($type, $context, $post)
    {
    remove_meta_box('dashboard_quick_press', $type, $context);
    }

  23. Samuel

    This code works perfectly for WordPress single installation, but if you activate it site wide on WPMU it only adds the new dashboard widget in the main blog dashboard... :(

    Anyone knows to make the widget to add on every blog dashboard of a WPMU installation?

  24. Alex

    Hey Samuel, moving the plugin to mu-plugins solves the problem.

  25. sebastien

    Hi Alex,

    Do you know if i can choose the place of my widget with this function wp_add_dashboard_widget ?
    Is it possible to specify that the widget must be in fisrt position to the top of the first column for example ?

  26. marujo

    with this hack is possible to put a widget text (that configured in appearance) in the dashboard? thanks

  27. marujo

    im trying to add a text widget of widgets sidebar in dashboard. how can i do it? anyone can help me, please!!

  28. sebastien

    Marujo > paste this in function.php

    <?php
    if (!function_exists('text_widget')) {

    function text_widget() {

    echo 'Text widget by ARCHIparmentier | wordpressdesigner';

    }

    function archi_setup() {
    wp_add_dashboard_widget( 'text_widget' , 'text widget' , 'text_widget');
    }

    add_action('wp_dashboard_setup', 'archi_setup');
    }

    ?>

  29. marujo

    hi sebastien. i try but only appears a blank widget. i need to show the editable content in the text widget also in dashboard. it is possible? i notice that the theme im usiong the sidebar as named as 'right', and the name of my text widget is 'Cotação Câmbio". if you can help me, i thank you a lot. thanks!

  30. sebastien

    If you use my code, a widget appears in the dashboard.
    In this widget you can read "Text widget by ARCHIparmentier | wordpressdesigner'". This text is product by the function text_widget()
    You can change this function to product another result.

  31. Artem

    Is there a way to add a new widget to the dashboard with ajax? After the dashboard finished loading?

  32. Brent Shepherd

    Hi Frank,

    Thanks for a good article.

    Do you know of a built in function to add a widget to the side dashboard? The wp_add_dashboard_widget function seems to only allow adding it to the 'normal' area.

    I can add the fields directly to the $wp_meta_boxes array, but a built in function would be much more robust. :)

  33. Owen Hoskins

    I'd like to echo marujo's question about adding text widgets to the dashboard.

    I've tried blending these snippets and those from Rick's follow up article (http://rick.jinlabs.com/2009/02/01/how-add-options-to-your-wordpress-27-dashboard-widgets/) with snippets from the default-widgets.php or dashboard.php or posts like (http://justintadlock.com/archives/2009/05/26/the-complete-guide-to-creating-widgets-in-wordpress-28) but can't seem to manage any output to my sidebar.

    This should be possible yes? Any ideas?

    I think this could be very interesting for providing easier-to-use widgets for the user client.

    Thanks for sharing your expertise.

    Best,
    Owen

  34. DavidM

    Great post and it's still applicable after all this time.

    For anyone interested, I just posted this article and ensuing form to automatically create dashboard widgets. It's a javascripted form that creates all the necessary plugin code from the input parameters. I've tested it myself and it's worked fine for including a Google Gadget, which I think has great potential. Anyway, it's at the following.

    http://thehacked.com/wordpress-dashboard-widget-plugin-maker/

    Enjoy,
    DavidM

2 pingbacks

  1. Rick's HideOut
  2. Frank MacDonald » Add custom widgets to the WordPress dashboard