I’m taking some days off on the sunny Aljezur, a small village at the south of Portugal near great beaches. Apart from all the relax, I’m also catching up with all the twitter and feedly buzz from last weeks. One of the topics that caught my attention was a tiny survey that is going on about WordPress dashboard usage, highlighted by WP Tavern. (EDIT: You may find the survey results here)
I’ve never taken much attention to dashboard until a recently project for an e-magazine website, where the backoffice was meant to be used by low-tech journalists. So, I’ve tried to simplify everything there to improve their experience with WordPress, being the dashboard one of the screens to require some attention.
The beauty of empty space
The first thing I’ve made, which is probably what most people do, was to remove all the default dashboard widgets, leaving a complete empty screen. This is the code snippet I used:
// Remove the Welcome Panel
remove_action( 'welcome_panel', 'wp_welcome_panel' );
// Remove the default dashboard widgets
add_action('wp_dashboard_setup', 'my_remove_dashboard_widgets' );
function my_remove_dashboard_widgets() {
//main:
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_incoming_links', 'dashboard', 'normal' );
remove_meta_box( 'dashboard_plugins', 'dashboard', 'normal' );
//side:
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' );
}
And the result is a simple and empty dashboard screen! Isn’t it beautiful?
Dashboard and the Settings API
One of the requirements for the e-magazine website was to allow the Editors to feature 4 articles to be displayed on a specific homepage section. Although there are several ways to do this, I was in the mood to develop a simple options page where they could manually pick 4 posts, using a drop-down select box.
It was when I realise this could be wrapped up into a nice widget to place on the infinite space of the WordPress dashboard.
After some research on google, I figured out that to develop a dashboard widget with the possibility to “submit” changes into the database, was somehow not straight forward (at least for my tiny brain). So, I’ve tried to use the famous Settings API applied to a dashboard widget…and guess what? It works!
Hereby the code I used:
<?php
// Add new dashboard widget
add_action('wp_dashboard_setup', 'my_add_dashboard_widgets');
function my_add_dashboard_widgets() {
wp_add_dashboard_widget( 'my_featured_posts', 'Homepage featured posts', 'render_featured_widget');
}
function render_featured_widget() {
?>
<form action="options.php" method="POST">
<?php settings_errors(); ?>
<?php settings_fields( 'featured-settings-group' ); ?>
<?php do_settings_sections( 'featured-settings' ); ?>
<?php submit_button(); ?>
</form>
<?php
}
?>
According to the Codex, to add a new dashboard widget we need to hook into the action wp_dashboard_setup where we’ll use the function wp_add_dashboard_widget to register the widget itself. This function takes four arguments: $widget_id, $widget_name, $callback and $control_callback (optional). The $callback is the name of a function that will display the actual contents of your widget, in our case, where the Settings API magic starts.
If you’re proficient on the Settings API you’ll notice I’ve added the settings_errors() call, which isn’t needed when using this API to build a regular options page, but in this case, it will make sure that some feedback is given after form submission.
To complete the widget you’ll need to follow the regular Settings API approach, by registering the settings and declaring the sections and fields that are part of the widget. I’m providing here the entire code snippet.
Finally, it’s time to ask if you prefer the empty dashboard or the one where suddenly you’ll have your custom widgets coded with a twist of the Settings API. So far, I’m appreciating the second.