Reorder dashboard widgets

Clearing things up

First, there’s a slight misunderstanding. wp_dashboard_setup is an action and not a filter. If it would be a filter, it would have one or multiple arguments and would need to return the first one.

How-To #1

For an example of this action, see the following mu-plugin I use:

<?php
/**
 * Plugin Name: Remove Dashboard Widgets
 * Description: Removes all Dashboard Widgets
 */
function dashboard_widgets()
{
    remove_meta_box( 'dashboard_browser_nag',     'dashboard', 'normal' );
    remove_meta_box( 'dashboard_right_now',       'dashboard', 'normal' );
    remove_meta_box( 'dashboard_recent_comments', 'dashboard', 'normal' );
    remove_meta_box( 'dashboard_plugins',         'dashboard', 'normal' );

    remove_meta_box( 'dashboard_quick_press',     'dashboard', 'side' );
    remove_meta_box( 'dashboard_recent_drafts',   'dashboard', 'side' );
    remove_meta_box( 'dashboard_primary',         'dashboard', 'side' );
    remove_meta_box( 'dashboard_secondary',       'dashboard', 'side' );
}
add_action( 'wp_dashboard_setup', 'dashboard_widgets' );

After removing those widgets, you can add them back in using

add_dashboard_widget( $widget_id, $widget_name, $callback );

For more info consult the Codex and the Dashboard Widgets API. To see the defaults, look into /wp-admin/includes/dashboard.php -> wp_setup_dashboard(). Then simply add them back in as you like/need them.

How-To #2

There’re also different other options you got: Filters.

But first we should clear up which dashboard you’re targeting. All those will have in some cases (plugins, etc.) different dashboards and different filters

• Network Administrators (a.k.a. Super-Admins) -> wp_network_dashboard_widgets
• Site Administrator -> wp_user_dashboard_widgets
• User -> wp_dashboard_widgets

All those filters filter the $dashboard_widgets array (and should return it).

Extending the defaults

If you want to extend the default Widgets, you will want to use the 'do_meta_boxes' hook, which has three arguments (Screen ID, location like side, normal, etc. and an empty third argument.

Drawbacks and limits

You’ll have to accept the fact that users are able to reorder those widgets (or even deactivate them). This is something that should be that way and kept like this.