As you can guess by the title this is another incredibly technical and specific article that’s really only of interest to WordPress developers like myself. Friends and family: please amuse yourself with this instead :)
So onto Dashboard Widgets (also referred to as “Dashboard Modules” in at least one place, though the WP code calls them Widgets so I’ll stick with that).
I wanted to add a little box to the dashboard with the currently logged-in user’s avatar and a few links to things they might want quickly. Since WP 2.7 made the dashboard super configurable (you can show/hide different sections and drag them around to reorder them) I figured that there would be some documentation on how to add new ones using plugins. Unfortunately it turned out that not only was there no page on the WordPress Codex to explain the process, but the dashboard code itself (found in /wp-admin/includes/dashboard.php ) was completely uncommented and confusing as hell. Since I spent the day figuring the whole API out I decided to write up a nice Codex page so the next person would have it easier: Voila.
At that link you’ll find an explanation of the function and hook you’ll need to use to add dashboard widgets using plugin (or functions.php in your theme) code. The process is pretty similar to adding sub-pages to the admin section if you’re familiar with that.
Some lessons I picked up along the way:
- The dashboard API needs some serious work. I might take a whack at it at some point when I’m bored but hopefully it will get cleared up eventually, especially the missing PHPDoc comments
- Right now it’s pretty much impossible to easily or effectively push your sorting preferences onto the default Dashboard Widgets. In the codex article I give an example of how to get your widget to the top of the list for people who have never sorted their widgets, but there’s no easy way to add your widget and say “make all users see this at the top of their screen unless they drag it to a different spot”. This fact is pretty annoying as blogs with many users are likely to have a lot of people who never even see the new widget because there are too many default widgets above it pushing it below the fold.
- I did figure out a way to force your widget to the top of the page but it had the unfortunate side effect of making it trapped there forever regardless of users dragging it around. I don’t recommend this method for publicly distributed plugins (as it will confuse and frustrate users that the dragging is broken) but you can see the code here (wp.pastebin.com link, apologies if it stops working at some point).
- This one is a bit obvious, but writing a Codex article (or any documentation really) is very very useful for acquainting yourself with something. I know more about this process than I would have if I’d just followed the instructions someone else wrote (I also know more about what needs fixing!). Lesson: When the docs are missing don’t just hack around till you have a half-baked solution, look through the source and figure out the best solution and share it with the world by adding to the docs yourself.
Hi there,
Just a quick note to thank you for the Codex addition, and also for the note you added about the Dashboard RSS feeds.
I’m just starting to explore WP hacking. I have experience with PHP, CSS, and XHTML, but putting all the bits together (and figuring out where to put them!) is still tricky.
Big thanks for shining the light,
Crystal
I just came across this page when searching for a custom WP 2.7 Dashboard. Thanks a lot for the Codex entry. I see you have included the info on how to remove the default widgets. Does it matter where this code is placed for it to work? Should I place it in the dashboard.php file?
@wiz: You’d want to put it in some plugin code. Either in a plugin file you create (its easy, check the codex page for the outline of creating a simple plugin) or in the functions.php file of a theme. The example code also doesn’t have a hook in it. I think when I wrote it I was assuming that you’d just add the code in that function into the rest of the dashboard related code in your plugin.
Hello!
Very Interesting post! Thank you for such interesting resource!
PS: Sorry for my bad english, I’v just started to learn this language ;)
See you!
Your, Raiul Baztepo
The gods must be smiling on me. Just read the codex article and a google search landed me here. I’m trying hide a dashboard widget to all but admins and a particular role. How could I wrap some code around the widget to do that?
I have been playing with the code below but with no luck just yet:
//Pre-check user status and roleif(is_user_logged_in) { // only if there is a user logged in
$user = wp_get_current_user();
$user_roles = $user->roles; // an array of roles
foreach($user_roles as $user_role)
{
if($user_role=='administrator' || $user_role=='intern')
}
}
//DASHBOARD CODE
function assignments_add_dashboard_widgets() {
wp_add_dashboard_widget('assignments', 'Assignment Sheet', 'assignments_dashboard_widget_function');
}
// Hoook into the dashboard
add_action('wp_dashboard_setup', 'assignments_add_dashboard_widgets');
Hey Mark. Its actually a lot easier than what you’re attempting. You should remove your is_user_logged_in() check, as its unnecessary since you’re already going to be checking for a specific role, and replace it with a check for current_user_can(), which checked logged-inness as well as for a specific role/capability. You use it like this:
if (current_user_can('publish_posts')) :
widget_stuff();
endif;
It works best with ‘capabilities’, actual things you can do, like ‘edit_users’, ‘manage_options’, ‘read’ etc, but you can also use it with role labels like ‘admin’, ‘editor’ etc. If you really want to check multiple role labels you could just have more than one clause in you IF statement ( if (current_user_can(‘editor’) OR current_user_can(‘admin’) ), but it would probably be better to just identify one capability that the roles share and check for that instead (like maybe ‘edit_others_posts’, which ‘authors’ dont’ have). If you’re not sure what capabilities are shared by certain roles I recommend the Role Manager plugin, it gives you extra control over roles in wordpress and also just helps you visualize what’s going on with the different role levels and capabilities.
Jeremy,
I want this dashboard plugin, but know that coding it myself will be a nightmare. Any plans to create a distribute this as a plugin file?
thanks,
Maraya
@Maraya not really at this point. I have other plugins that are all basically waiting on a bunch of work I need to do on my own site before I can start hosting them here. At some point I might release it and i’ll leave a comment on this post to notify you, but I wouldn’t count on it if I was you, I’m pretty busy.