soulless software

Habari Plugin Development: Dashboard Modules

Published 2008-10-04, tagged dashboard, development, habari and modules

Habari has a pluggable dashboard, which allows plugins to create dashboard modules that the user can select to personalize what they see. The default Habari installation provides a plugin, Core Dashboard Modules, that makes three dashboard modules available: Latest Entries shows a list of recently published items, Latest Log Activity shows a list of recent log entries, and Latest Comments shows the most recent approved comments by post. It's easy for plugins to add new dashboard modules, too!

For example, my Habari Backup plugin adds a new dashboard module to show the status of the 5 most recent backup attempts. If all goes well, it will report the time of the backup, and who received the backup file. If something goes wrong, the specific error messages should be displayed so that you can investigate and correct the problem. I decided to show this stuff in a separate dashboard module to ease troubleshooting when things go wrong, but also to allow a site operator to confirm at a glance that things are working correctly, without having to sort through potentially hundreds of log items. The rest of this post will show you how easy it is to add a dashboard module to your plugin!

The first thing to do is add a method to your plugin named filter_dash_modules. This method accepts a single argument, which is an array of dashboard modules, to which you'll add your own element. Here's the method you need to add, in its entirety:

public function filter_dash_modules( $modules )
{
     array_push( $modules. 'My Module' );
     return $modules;
}

The name you define for your module in the filter_dash_modules method is used in the name of the method that will actually construct your module: make it all lowercase, replace spaces with dashes, and append it to filter_dash_module_. So, for the "My Module" module defined above, use filter_dash_module_my_module as the method to build your module.

public function filter_dash_module_my_module( $module, $module_id, $theme )
{
     $module['title']= 'My Module';
     $module['content']= 'This is the content of my module';
     return $module;
}

As you can see, constructing your module's contents is pretty straightforward: simply add the title and content elements to the $module array passed to your method. Your method will also get the module's numeric ID and the complete admin theme object, if you should have a need to use them in any way.

Obviously this example is trivial, and a real dashboard module would likely do quite a bit more: fetch specific log entries out as my Habari Backup plugin does, fetch data from external sources as the FeedBurner plugin does, etc. You could even create a module to display a random photo, to spruce up your dashboard.

The Habari Dashboard belongs to the user, so you shouldn't add your module to the dashboard automatically: the user should enable the module only if they want it. There exists a method, Modules::add, that allows you to automatically add your module to the dashboard. I'm telling you about it so that I can unequivocably state that you'd better have a really, really good reason to use it. Remember: the dashboard belongs to the user.