Dashboard widgets are the boxes that show up on the homepage of your WordPress admin dashboard.
By default, WordPress includes a few different dashboard widgets. By adding and removing widgets from the dashboard using the Dashboard Widgets API, you can make your WordPress app more useful by placing the information and tools most required by your app right there on the dashboard homepage. It’s a nice touch that should be done by all WordPress apps with users who will be accessing the WordPress admin.
Removing Dashboard Widgets
The dashboard widgets are really just meta boxes assigned to the dashboard page of the admin. The WordPress Codex page on the Dashboard Widgets API has a list of the default widgets shown on the WordPress dashboard:
There are a different set of widgets added to the multisite network dashboard, and a different hook must be used to remove the network dashboard widgets. The following code hooks on wp_network_dashboard_setup and removes the meta boxes added to the “dashboard-network” $page:
You could use similar code to remove default meta boxes from other dashboard pages, like the edit page and edit post pages. The $page value to use when removing meta boxes there are page and post, respectively.
Adding Your Own Dashboard Widget
The wp_add_dashboard_widget() function is a wrapper to add_meta_box() that will add a widget to your admin dashboard page. The wp_add_dashboard_widget() function takes four parameters:
$widget_id—An ID for your widgets that is added as a CSS class name to the wrapper for the widget and also used as the array key for the dashboard widgets array.
$widget_name—Name of the widget displayed in the widget heading.
$callback—Callback function that renders the widget.
$control_callback—Optional. Defaults to NULL. Callback function to handle the display and processing of a configuration page for the widget.
The flowing codes adds a dashboard widget to show the status of current assignments. The code includes the call to wp_add_dashboard_widget() to register the dashboard widget and also includes the callback function to display that actual widget and another callback function to handle the configuration view of that widget.
Note that we hook into wp_dashboard_setup for the function that adds our widget. If we wanted our widget to show up on the network dashboard, we would need to use the wp_network_dashboard_setup hook.
The sp_assignments_dashboard_widget() function draws the actual widget shown on the dashboard page. This is where we would add our code to loop through assignments and show stats on what percentage of assignments have been turned in.
The sp_assignments_dashboard_widget_configuration() function draws the configuration form and also includes code to process the form submission and update the option we use to store the configuration.