How to Code Your Own Custom WordPress Widget

Have you ever wanted to create a custom widget for your WordPress website? While WordPress does include a built-in text widget, which you can use to display HTML along with embedded CSS and JavaScript, if you want to do anything more than that the text widget just won’t cut it.

What if you want to grab a bit of content from your website database and display it in a widget? The solution is to code up a custom sidebar widget. While that may sound like a daunting task, as long as you have basic PHP skills it is within your reach.

So follow along with this tutorial and you’ll learn how to create two different widgets:

• A simple widget that displays the widget title, site title, and site tagline.
• A slightly more complex widget that displays a list of all categories sorted alphabetically and split into two columns.

Ready to learn the basics of custom WordPress widget creation? Let’s get to it:

• Widget Building Basics
• WordPress Widgets API
• Example #1: Display the Widget Title, Site Title, and Tagline
• Example #2: Displays Categories in Two Columns
• Creating Your Own Widget

Widget Building Basics

You’ll need three things in place in order to follow along with this tutorial:

• A WordPress development environment
• Basic PHP coding skills
• Basic WordPress development experience

All it takes is a single errant comma or missing curly brace to crash a WordPress website, and if you’re relatively new to programming, your site could be down for several minutes or longer while you try to locate the offending code. For that reason, you should absolutely get your widget working using a local development environment before you try using it on a live website.

We’ve written about lots of local development environments in the past. Personally, I use XAMPP but any localhost server will do. Pick one and get it running.

If you’ve never written a line of PHP or coded up a basic WordPress plugin, then this tutorial may be a bit out of your reach. However, the good news is that you can learn everything you need to know either informally by working through our series on WordPress Development for Beginners, or formally by enrolling an upcoming course at the Academy.

If you meet those three basic requirements, you’re ready to start slinging code. Let’s get to it.

WordPress Widgets API

You create a new WordPress widget by adding code to one of two places:

• A custom plugin, which you should use if you want to use the widget with more than one theme or on more than one website.
• The functions.php file of the active theme — which should be either a child theme or a completely custom theme.

Just for the sake of example, you can find the completed code for the simple sidebar widget described in this tutorial available at GitHub. If you aren’t sure where to write your code, or just want to see the entire code at once, download a copy of that plugin.

WordPress widgets are created with a bit of object-oriented programming. The WP_Widget class is extended to create each widget. The WP_Widget class includes close to 20 different methods. However, for basic widgets, you really only need to use four of them:

• __construct(): registers basic widget information.
• widget(): contains the widget output — what you actually see on your site front end when the widget is added to a widget area.
• form(): defines the widget settings displayed in the WordPress admin area.
• update(): updates widget settings when new settings are saved in the WordPress admin area.

In addition to these four methods, the add_action function is used to tie the custom widget function to the widgets_init hook.

Example #1: Display the Widget Title, Site Title, and Tagline

The first thing to do is to extend the WP_Widget class like this:

In this case, the name of the new widget function is jpen_Example_Widget. Note that jpen is simply a prefix I add to all custom functions to avoid conflicts with any functions in other plugins, themes, or the WordPress core. You can use any name that is appropriate for your widget, and add a prefix if you want to follow best practices.

We’ll write functions using the four methods mentioned in the list above and nest all four inside of our widget function. Then, in the last step, we’ll write a function to register the widget.

Let’s start the method writing process with the __construct() method.

WP_Widget::__construct()

The __construct() method is used to assign an id, title, class name, and description to the widget. Here’s how the constructor function looks to create our first example widget:

To understand this function, start with the line that begins with parent::__construct(). What’s going on is that this line creates a new widget with the id of 'example-widget', the name 'Example Widget', and two widget options: a class name and a short description.

All of this code goes inside of jpen_Example_Widget and is used to register the widget with WordPress and then display the widget title and description in the admin area.

WP_Widget::widget()

The next step is to use the widget() method to define the widget output that will be displayed on the site front end.

What widget() does is contain the code that generates the actual content displayed by your widget. The contents of widget() could be just about anything but generally will include some PHP. Otherwise, you would just use the text widget built into WordPress.

In our case, we’re going to give users the option to display a custom widget title. So we’ll need to grab that title and then use get_bloginfo() to display the blog title and tagline. Here’s the code we’ll use to do that:

There a couple of things going on in that function that you’ll want to take the time to understand:

• $args[]: this variable loads an array of arguments which can be used when building widget output. The values contained in $args are set by the active theme when the sidebar region is registered.
• $instance[]: this variable loads values associated with the current instance of the widget. If you added a widget to the sidebar twice, each $instance would hold the values specific to each instance of the widget.
• widget_title filter: returns the title of the current widget instance.
• get_bloginfo(): a function that can be used to return all sorts of meta data about a WordPress website including the site name and tagline.

After defining a few variables using the information in the list above, the code then goes on to produce the actual output which consists of information from $args, the title, and the site name and tagline.

Note that virtually every widget should include the 'before_widget', 'after_widget', 'before_title', and 'after_title' arguments. They are necessary to ensure each widget is nested inside the theme-specific HTML tags.

The entire widget() method should be nested inside of jpen_Example_Widget.

WP_Widget::form()

The form() method is used to add setting fields to the widget which will be displayed in the WordPress admin area.

Widgets that include a lot of options will be quite complex in this department. However, in the case of our example widget, all we want to do is allow users to assign the widget a custom title. So things are pretty simple.

This function returns the current values of this particular instance of the widget by calling the $instance parameter. We then check the current instance information to see if the title is empty. If it isn’t, we display the current title.

Next, the label and input elements nested inside of paragraph tags create a labeled input field for the user to add a new title.

With this bit of code added to jpen_Example_Widget, widget settings will look like this:

WP_Widget::update()

The next step is to update the information in the WordPress database using the update() method.

This method takes two parameters: $new_instance and $old_instance. The first contains the values added to the widget settings form. The second contains the existing settings — if any exist.

The update() method should validate the new settings as appropriate and then assign them to the $instance variable and return that updated variable. If that sounds a bit complex, the following example should clarify things.

In the case of our example widget, all we’re doing is updating the title. So all we need to do is:

1. 1. Grab the title from the new instance,
   2. Strip away any HTML or PHP tags that may have added to the widget title,
   3. Assign that title to the instance, and
   4. Return the updated instance.

Register the Widget

The final step in the process is to register the widget using the add_action function and the widget_init hook. Here’s how to do it:

First, we create a function to register the widget and use the widget object name to identify it. Next, we tie the registration function to WordPress using the widgets_init hook and the name of our registration function.

This bit of code is added outside of jpen_Example_Widget. When it is called it will pull up the widget with the appropriate name, jpen_Example_Widget in this case, and run all of the code contained in the widget.

With this final bit of code in place we can add our widget to a sidebar, configure it to our liking, and display our site title and tagline in the sidebar, like this:

Example #2: Displays Categories in Two Columns

A little while back I wrote a tutorial explaining how you can turn any HTML5 template into a WordPress theme. However, what I didn’t do in that tutorial is recreate any of the sidebar widgets included in the template. So our second example widget will be the category list sidebar widget from the Blog Post HTML5 template by Start Bootstrap.

Here’s how the sidebar widget looks in the original HTML5 template:

Recreating this widget requires a bit more code than our simple example widget, but in reality it isn’t very complex. As a matter of fact, the _construct(), form(), and update() functions are basically unchanged. The only real difference between this widget and our previous example is that the widget() output method includes quite a bit more code.

The reason for this is that to create the widget content we need to generate a list of all the categories, sort the list into alphabetical order, and then arrange the categories into two columns. While there are a variety of ways this could be accomplished, here’s one way to get the job done.

For starters, I created the widget() function:

Next, I created a few variables:

The title and category variables are pretty self-explanatory. They hold the widget title and a list of all categories.

The $cat_count variable will be used to keep track of the total number of categories so that we can sort them into two lists. The two column variables, $cat_col_one and $cat_col_two will be used to divide the categories into two columns.

Next comes the function that iterates through all the categories and splits them into two columns.

For each category, the $cat_count variable iterates and a $category_link is created. Then, based on the current $cat_count — whether it’s even or odd — the $category_variable is added either to the column one or column two variable.

In addition, this code also nests each category into a list item with a class of "list-unstyled" to match the classes and HTML used in the original template.

Finally, we need to actually print out $cat_col_one and $cat_col_two to render the list of categories:

That code iterates through each of the category column variables and prints out each list of categories into a div. The classes and HTML structure assigned to the widget mirror the classes and structure included in the original template to ensure that the styling included in the original template CSS resources is properly applied to the new widget.

Here’s how the sidebar widget looked upon completion. If you take a look back at the original version in the template in the image above, you’ll see that it’s a perfect match!

If you’d like to see the full code that creates this sidebar widget, look for the jpen_Category_List_Widget instance of the WP_Widget class in the functions.php file of the Simple Blog Theme at GitHub.

Creating Your Own Widget

Creating a custom sidebar widget involves working with the rather complex WP_Widget class. While it may seem a bit daunting, the good news is that you can boil down the process to five steps:

1. 1. 1. Use __construct() to define the basic widget information.
      2. Use widget() to define the widget output.
      3. Use form() to create the admin settings menu.
      4. Use update() to update widget settings.
      5. Use add_action() to tie the widget object to the proper hook.

While creating a custom widget may be a bit complex, there’s a relatively narrow body of knowledge you need to master to create powerful custom widgets. Wrap your head around those five functions and you’ll be able to turn just about any idea you can dream up into a WordPress widget.