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.
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
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
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
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.
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
The content of the stylesheet itself is the following, the remaining few styles will be added inline.
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 world scenario, this would be done with a single query, the array would be compiled based on that.
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