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.