How to Create a Custom Author List Widget in WordPress

For many websites good authors are the most important asset they have. Showcasing them properly can be an important concern and WordPress doesn’t really have anything powerful out-of-the-box. Most of the widgets in the WordPress Plugin Directory are a little basic so I thought it would be a good idea to create something really powerful myself.

In this Weekend WordPress Project I’ll show you how you can create your own – simpler – widget, and then I’ll show you the actual plugin I adopted in the directory and how I added versatile features to make it as flexible as possible for others.

Let’s get started.

Creating Our Own Widget

Let’s start by doing things on our own. This requires creating a plugin and – within it – creating a widget. Here’s the nutshell version of the two linked articles:

  1. Create a folder in your wp-content/plugins folder – name it my-author-list
  2. Within this folder create a file named my-author-list.php, this will be your main plugin file
  3. Paste the following code within it (feel free to replace the author info in there)

At this stage, you have made a fully functional plugin, although it doesn’t do anything yet apart from show up in the backend. Go ahead and activate it now.

Next, let’s paste the skeleton code we’ll need to make a widget. Add the following to the file:

To create a widget you need to extend the WP_Widget with your own sub-class. Within this sub-class you need to define a few functions, which govern how the widgets work. Don’t worry if you don’t know what classes are, the syntax is pretty simple.

All you need to know is what those four functions in there do and you can code within them throughout this exercise. The __construct() function basically adds our widget to WordPress. It contains the name, description and a few other details of the widget.

The form() function governs the backend form, which shows up when you add the widget to a widget area. This is where you can create inputs for additional options, like how many authors to show, the widget title, and so on.

The widget() function takes care of the front-end display. Any code in there will be shown where the widget is supposed to be on our page.

The update() function will not necessarily be needed, in fact, in this example we can discard it. This function can process data that is submitted when the widget is saved in the backend. This is great for retrieving API data based on the user input or perhaps transforming the input itself. I’ll discard this for now since we don’t need it.

Adding Widget Options

Let’s stick to the basics for now. A simple widget title, author count, order by and order direction field should do. I like to take the following steps for each.

  1. Determine the current value for each field
  2. Determine the possible values for dropdowns, radio or checkboxes
  3. Output the field

Here’s the code I would use for the three fields we discussed:

The $instance variable holds the current value of the fields, ie: the values the user has saved. In the first block I check those values. If they are empty I set a default for each field. Next up are field options.

For each field where I have a pre-set number of options I create an array for them. This may seem a little redundant for the order field but it makes the field output code more modular and it is also easier to handle the currently selected value.

Next up are the fields. They are perfectly normal HTML fields, the only two things you need to remember are to use the $this->get_field_name() and $this->get_field_id() methods. These are needed for WordPress to be able to save our data to the correct widget. Other than that, all the code is simple HTML and PHP loops.

At this stage you should be able to drag the widget into any widget area and save its data.

Displaying Our Widget

When displaying a widget you should always be mindful of its surroundings. When a widget are is defined using the reregister_sidebar() function a number of parameters can be defined such as before_title and before_widgets. These are passed as the first parameter for our widget() function, the second parameter holds the widget’s instance variables, the saved data for the widget.

This is why almost all widget display functions should use the following skeleton code:

This code will display any code that is supposed to precede and succeed the widget as well as any code that should be added before the title, the title itself and any code after the title.

Getting Authors

We’ll be using the get_users() function to retrieve our authors, all we need to do is pass our parameters to it. Here’s the code, which should be pasted inside the widget display skeleton where it says “// Main Widget Code Here”:

The $users variable should contain an array of user objects. We now need to cycle through them using a simple loop and display any information we want. Here’s an example which shows the avatar and the user’s name, each linking to the user’s url. Paste the code right below the call to the get_users function.

Now you should see a list of users, which you can control using the settings defined in the widget. It won’t look super awesome, but we can fix that by adding some styling.

Adding Some Style

To add styles the WordPress way we need to enqueue a stylesheet. The best way to do accomplish this is in two steps.

  1. First we register it with WordPress, then, within the widget() function we enqueue it. This ensures that WordPress is aware of the existence of our stylesheet but only actually adds it to the page when it is needed.

To register the stylesheet add the following within the __construct() method of our class:

  1. Then, create a widget_styles() function within the class. Don’t worry about the name being generic, that’s why it is great to work inside the class, your function names won’t clash with anyone else’s.

Finally, at the top of the widget() function add the following to make sure the stylesheet is added whenever the widget is displayed:

Add any style you like within the stylesheet, it will be applied to your widget. It may be a good idea to wrap your widget in a specific class so you can target it effectively and many before_widget code sections will also include your widget’s class.

Using The Top Authors Plugin

The Top Authors widget settings.
The Top Authors widget settings.

I’m working on a large website rebuild at the moment and one of our key decisions was to either use existing plugins for everything we need, or to code our own general-use plugins if needed. We created a couple of plugins due to this policy.

We broke our policy and used Top Authors for two reasons: It already existed and its developer Seb Van Dijk generously donated the plugin to us, which we’ve adopted and taken over. We recoded it a bit, added some new features and released the update to the WordPress Plugin Directory.

This is what the Top Authors widget looks like on the front-end.
This is what the Top Authors widget looks like on the front-end.

Top Authors went beyond the simple uncustomizable text or text/Gravatar list. It allowed us to add our own custom template to be used in the widget front-end. We kept this great feature, adding some defaults in the process, and extended it with a number of hooks.

The widget options give you the option to include/exclude roles, choose which post types to take into consideration and select a display from a preset list, or create your own. We’ve also added an additional ID you can pass to each widget which allows you to use the ta/post_query hook to modify the authors you want to display for each widget.

Extending Top Authors

Top Authors already gives you control over the display but you can do a lot more with the hooks, especially the one I mentioned earlier, – ta/post_query. This hook allows you to modify the query that looks up the posts based on which the authors are listed.

Let’s back up a bit and figure out how top authors works. Instead of retrieving users directly, we first retrieve posts, and then look at the authors for those posts. The reasoning behind this is that it allows for a much more flexible listing of authors because it allows for the list to be narrowed down based on any criteria.

For example, say you want to list your top authors, but only for posts published on weekends that are assigned the featured category. You could restrict the Top Authors widget like this:

You can use any parameters that WP_Query usually takes since they are passed directly to it. Since the second parameter of the function (the $instance variable) contains the widget’s details you can even narrow the use of this function down to a specific single widget using the widget’s id.

Conclusion

While there are a bunch of simple author widgets around, I didn’t really find any of them to be flexible enough for my own needs. If you need a simple list, a lot of them will do. But if you need something more customizable I think Top Authors is a great choice, or just go full coder and do it yourself!

If you have any questions or tips for listing authors let us know in the comments below.