How to create WordPress dashboard widgets

By default WordPress comes with some great tools to get you started, such as a ‘Quick draft’ form and a ‘Recent Comments’ feed. Despite this, the Dashboard is catered heavily towards blogging, which is rightly so seeing as WordPress started off as a blogging platform. However, these days WordPress is used for much more than just blogging, so how can we modify the Dashboard to meet our client's needs?

This post will take a look at how we can utilise the Dashboard Widgets API (added to WordPress in 2.7) to provide our clients with a little more control when working with the Admin interface. To do so, we'll create a 'User Status Widget' that will provide an overview of who’s currently logged into the admin area; a very useful stat to have when you have multiple people working on a website at once.

Ready, set, go!

Setup

First things first, as we're looking to modify WordPress, everything will be added to the functions.php file of your theme. However, we're not going to add all our logic into one file as things will start to become a nightmare to maintain in the long run, so lets separate this out into multiple files.

If you don't have a functions.php file in the root of your theme then create one and add the following. If you do have a functions.php then you can add the following to the bottom of that file.

If you're unfamiliar with the concept of require in PHP its essentially saying, "Go grab this file and run whatever's in it before you go any further". You can get a full run down on the ins and outs of it over on Stack Overflow, where it goes into the differences between require, require_once, include and include_once.

Now lets create each of those files within a folder called inc. Goes without saying but we're working with PHP so each of the files will need an opening <?php tag. In addition, throughout this tutorial you'll notice I prefix my files and functions with asrt, you can read why on my FAQ page.

Registration

To register a widget on the WordPress dashboard we can use the aptly named wp_add_dashboard_widget() function, which takes the following parameters:

$widget_id - Despite the confusing label, this is an identifying string (series of characters within quotes) that WordPress will use for class names, IDs, etc.

$widget_name - The title of the Widget, which will predominantly be displayed in it's header.

$callback - The name of the function that will display the widget’s contents. More on this later.

$control_callback - Similar to the first $callback, however, this is the name of a separate function which will setup any form elements and functionality you’re looking to create in your Widget (if any). In our case we will not require this argument for today’s tutorial, but this would have been instrumental in creating the default 'Quick Draft' widget.

$callback_args - Provides you to pass through any values to your callback function. As we're not calling the function in the traditional sense, WordPress does that for us.

Open up your newly created inc/asrt-user-widget-setup.php and create a function that calls wp_add_dashboard_widget().

To activate this function we need to use a WordPress hook. Think of these as checkpoints that allow you to run a function at the exact point this checkpoint is situated. For this one, we will need to use the wp_dashboard_setup hook, as this is a checkpoint for when the dashboard's widgets are being created.

Underneath your function, we're going to call another called add_action(), where it's first parameter will be the name of the hook and it's second being the name of the function that you want to run at this checkpoint.

If you navigate to your dashboard you'll see your newly created Widget with the echo'ed text from above.

Fig 1: Example of a successfully registered Dashboard Widget

Moving back to our code, remove the echo statement. We're going to populate this widget with a table of our WordPress users. To do so, we can call a new instance of the WP_User_Query class within our function.

Great, we've now got all the users that have been assigned the roles of administrator, editor, or author (default WordPress roles) and we have checked whether any actually exist in the first place. Now, lets use this to create our table.

Within our if statement, remove the comment which says Table to be created here, we're going to loop through the users we have and output their data. To do this we'll use a method of WP_User_Query called get_results() which results an array of users to us.

Its not exactly the sexiest thing in the world, but it'll do! Bare in mind the indentation of code does nothing here, it makes it a little more legible. Complete personal preference though!

Creating 'last online' functionality

Admittedly, I've got a slight confession. By default WordPress doesn't provide its own 'last online' entry to the Database, so we'll have to create our own.

Within inc/asrt-user-widget-setup.php lets add a function to the init hook which will be used to setup the functionality we're looking for.

add_action('init', 'asrt_set_user_last_online');

Underneath it we'd better create that function too. To do so we'll get the current date and time in the U format, which is described as: 'Seconds since the Unix Epoch'. More on that later. Next, we'll get the current user and add/update (depending on if its already set for that user) a new record to the wp_usermeta table for our asrt_last_online stat.

Stylisation

So functionality-wise, we're set. We now have a quick overview of all our users and whether or not they're currently logged into the website (albeit rudimentary). However, it looks like a dog's dinner... lets change that.

Within inc/asrt-user-widget-appearance.php create a new function to be executed on the admin_enqueue_scripts hook. It pretty much does what it says on the tin, allows you to run something when all other admin scripts/stylesheets are being loaded.

Within this new function, we can use the wp_enqueue_style function to register a new stylesheet. This function takes 5 parameters:

$handle - An identifying name of the stylesheet we're looking to create. Generally speaking I'll mimic the name of the file itself where appropriate.

$src - The absolute path to the stylesheet or a URL if external (read: not hosted in the same place as your WordPress project).

$deps - An optional array of dependencies that should be executed before this stylesheet. The names will correlate to the $handle argument of already called stylesheets.

$ver - The current version of the stylesheet if appropriate. This will be appended to the URL as a query string for cache busting purposes.

$media - Optionally set the different media this stylesheet should be used for. This will create inline media queries for the <link> element it creates. For example, you might put screen and (min-width: 768px).

This time though, we'll only need to define the $handle and $src parameters.

Taking things a step further

There are still many things we can do to improve this widget, however, I hope this gives you a quick introduction to the WordPress dashboard API and how we can use it to provide a little more information for our clients up front.

If you'd like to take this to the next level then have a think about how you could:

Compile your CSS from a [series of] Sass file(s) to provide further styling control to our widgets.