Adding Custom Widgets to the WordPress Admin Dashboard

Have you ever wished that your WordPress dashboard was a more useful place?

Sure, there are plugins that add modules there but there are countless metrics and shortcuts you may want to add yourself. In this post I’ll show you how you can add your own – completely customized – dashboard widgets easily.

WordPress Dashboard
Create your own dashboard widget.

A Basic Dashboard Widget

The anatomy of a dashboard widget is extremely simple. First you need to use the wp_add_dashboard_widget() function to register it with WordPress. Then you create a function which handles the content display. Here’s the template code you can use to create one quickly.

Before I break that down, don’t forget that this should be placed in a plugin. If you want to test this real quick you can also get away with adding it to your theme’s functions.php file.

The first step is to hook a function into wp_dashboard_setup. The contents of this function is a simple call to wp_add_dashboard_widget() with three parameters:

  • Widget slug
  • Widget title
  • Display function

The second step is creating the display function my_dashboard_widget_display() and filling it with content.

Forcing Widgets to the Top

In some situations you may want to show important information or functionality at the top of your dashboard. WordPress doesn’t have a great API for handling this, but with some fiddling around you can get it done. We’ll need to add some extra code into our registration function, here’s the full code for an example widget.

Seven additional lines for a simple rearranging is a bit much but since no other method is available, this will have to do. The first step is to globalize the $wp_meta_boxes variable which contains information about all registered widgets. To make things easier on the eyes I’ve separated out the widgets which are displayed on the dashboard into the $dashboard variable.

The next step is to grab our registered widget from the array of widgets. This is stored in the $my_widget variable because we need to unset it in the next line and then re-add it.

The next step is to merge the contents of $my_widget and $dashboard. The array_merge() function appends the second array to the first so our widget will now be the first one in the new $sorted_dashboard array. The last step is to replace the original dashboard array with our new sorted one.

Adding Functionality

The main way you can enhance dashboard widgets is by creating some nice styles or applying some Javascript functionality. Let’s create a widget which shows the number of comments our website has received each week for the past five weeks. This will be a simplified example, a proof of concept if you will.

The end result of our efforts
The end result of our efforts

HTML Structure

We’ll be building the example above with CSS only, no Javascript required. To get it done we will use the following HTML structure:

It will be styled using a CSS file and also some inline CSS which will take care of the heights and widths for us.

Styling the Bars

The height of the whole container (.comment-stat-bars) is a fixed 120px high. The bars themselves are actually also 120px hight. The seemingly different heights are achieved by adding a top border height. This ensures that the bars start from the bottom and by setting the overflow:hidden on the container we can hide the unwanted bits.

The stylesheet is added in the usual fashion, by enqueueing it:

Note that we check the value of the $hook variable to make sure the style is only used on the dashboard page, there really is no need for it anywhere else. If you’re adding the code to your theme’s functions file you’ll want to use get_template_directory_uri() instead of plugins_uri().

The content of the stylesheet itself is the following, the remaining few styles will be added inline.

Calculating Heights

Instead of grabbing comment counts, let’s work with an array of numbers similar to what we will end up with in the end:

$comment_counts = array( 20, 29, 40, 33, 17 );

This array represents the comments we received each week for the past 5 weeks. So based on this, how do we figure out the bar dimensions. Let’s start with width since it’s easier.

In the stylesheet we’ve added a 1% margin to each side of the bars. This means that for each bar we have, we have 2% less space available to divide between the bars. So if we use 100% as the total width we can figure out the percentage width of one bar like this:

// ( 100 / number of bars ) - 2
$data_points = count( $comment_counts );
$bar_width = 100 / $data_points - 2

On to the height! The bar with the highest value will always be set to fill out the whole height of the container. In our example, the third bar (with the value of 40) is the largest so it will be the maximum height of 120px. Whenever a bar is smaller we add a top margin to it.

Exactly how much top margin is added depends on ratio between the size of a bar and the largest bar in the set. In our example the first bar is exactly half the size of the third bar. Therefore we would need to add a 60px top margin, exactly half of the maximum 120px. Here’s how this looks in code:

$highest_value = max( $comment_counts );
foreach( $comment_counts as $count ) :
	$count_percentage = $count/$highest_value;
	$bar_height = $total_height * $count_percentage;
	$border_width = $total_height - $bar_height;
}

Displaying A Static Graph

If we put everything we’ve done together we’ll end up with a nice little bar chart, although the numbers are hard coded in. Let’s take a look!

Pulling Comment Counts

The last step is grabbing the comment counts dynamically. Unfortunately WordPress does not have a function for this so we’ll need to write our own little query. The version below is quick and dirty but will work. Simply replace the array with the following:

All that is going on is we’re pulling the number of comments from the database 5 times. In each iteration of the loop we’re going back one week. In the first iteration we’re pulling comments between now and 7 days ago. In the second iteration we’re pilling comments between 7 and 14 days ago, and so on.

In a real word scenario this would be done with a single query, the array would be compiled based on that.

Conclusion

In conclusion, dashboard widgets offer us a great way to communicate things to ourselves and our website’s staff. Aside from static content we can spice things up with CSS and add great functionality using Javascript.

In addition to pulling data from WordPress we can look to third party API’s for data as well. You can grab customized stats from providers like Mailchimp, Google Analytics, Twitter, and so on.

Let us know in the comments if you’ve built any great dashboard widgets or if you have any ideas for some useful ones!

Image credit: Nissan Note 2014 image by Kārlis Dambrāns