Creating a Widget with the WordPress Widget API

/ Wordpress / by Paul Robinson / 2 Comments
This post was published back on October 24, 2011 and may be outdated. Please use caution when following older tutorials or using older code. After reading be sure to check for newer procedures or updates to code.

The first thing to do is decide where this widget is going to be used. If it’s part of your theme you can just place it in your themes functions file, or you can place it in a separate file and include it into your functions file for neatness.

If it is part of a plugin you can just place it inside your plugin file. If you are just making a widget and you don’t want to alter your theme, you can always make a plugin that adds the widget. To make a plugin just create a brand new file using notepad, notepad++ or another text editor (not a word processor) with the following at the very top:

What Widget Are You Making?

Okay, now that we’ve covered the different methods of adding a widget let’s get to how to create one. I’m going to show you how to create a random image gallery widget. This widget would be good for a photography site or any website that focuses on images. It shows one random image from the media library in your sidebar. Here is what it could look like with a little bit of styling.

Showing the Example Gallery Widget in Action

Gallery image © NBC Studios. Used for illustrative purposes, no infringement intended.

Remember you can make this widget do whatever you’d like, this is just an example I’m using to show you how a widget is created.

Object Oriented Programming

The new WordPress Widget API is based around extending a class. This is part of a method of coding called OOP (Object Oriented Programming). Let’s take a look at what it looks like:

That is the basics of extending a class. WP_Widget is the class defined by WordPress and you extend it with your own widget. The last line tells WordPress to register the widget using a quick anonymous function.

Creating The Widget

Okay. Let’s take a look at the entire widget code and then we’ll go through it.

Okay. First we check the WordPress version is over 2.8 which is when the WordPress Widget API was introduced. This isn’t needed if you know the version installed will always be over 2.8, but it’s a good habit to get into.

We extend the Widget class as we mentioned earlier. The first function is also known as the constructor and is ran when the class is instanced/ran. In this case it calls the parent constructor which is the WP_Widget class we extended, it also sets the name (Human/nice Name) of our widget at the same time.

Next is the widget function. This function defines what should be output by the widget. In my case I grab an attachment from the media library. You should add in whatever you want your widget to do here. It’s important to note that it pulls in two parameters. The first contains standard parameters passed by WordPress. The second contains the options saved by the widget, if it has any.

Next up is the update function. This just passes the newly saved options on to WordPress to be saved into the database. If you want to do anything every time the widget’s options are updated feel free to add it here. Otherwise you can just leave this bit as is.

Lastly is the form function. This is where you output the form to allow options to be saved for your widget. You need to escape your options so they are safe to use in the form HTML. You can do them one by one, or you can run $opts through a foreach and then run esc_attr() on each one. There is no need to output a form as your output from this function will be placed inside one created by WordPress.

The idea is just to output form fields as you need them. Feel free to copy the way I’ve laid my fields out if you like. I’ve used a checkbox here, but you can use text fields too. here is an example:

The last line as I mentioned earlier, registers the widget with WordPress.

That’s it. You should now have a new widget on your widgets page. Drag it over to the desired sidebar & you should be able to use it as you would any other widget.

If you have any questions, or you need any help please let me know via the comments. If you would like any hands on help I’m available to hire, check out my Hire Me page for more or email me via that page for a customized quote.


Author’s gravatar

Thanks, gave me a good start. Need to find some stuff on saving the options properly now though. Perhaps ad that bit. I would think that most people would need that.

Author’s gravatar author

Hi Zack,

I’m not sure I understand? The widget API does not require any special instructions for saving the options. The options for the widget are saved by WordPress in the update() method. If you need to do anything to the data gathered by the options you can do it there before it is saved. If you just want to save it (as is the case in this tutorial) just return the array with the options contained in it.

I’ve just tried the code Widget code here in WordPress 3.5 & it is still working perfectly (and saving the options). Are you having trouble getting the options to save?

Older Comments
Newer Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

I'll keep your WordPress site up-to-date and working to its best.

Find out more