The simpliest way of creating a widget in WordPress 2.8+

And dis­sec­ted at that

If you have even a tini­est bit of ambi­tions, you will want to have some spe­cial inform­a­tion in your blog’s side­bar, be it a link to your RSS feed or links to your co-authors’ social pro­files. Plu­gins are a nice way to get what you want, but they don’t always match your needs. For some pur­poses you will want to have your own wid­get, and cre­at­ing one in Word­Press higher than 2.8 is pretty damned easy, which I will demon­strate you in this not-anime-related-at-all post.

You have two places where you can put your widget’s code in: your theme’s functions.php or into a plu­gin. It’s pretty equal where you put it.

The Base

The whole wid­get, as gladly imple­men­ted in Word­Press 2.8, is situ­ated in a PHP class. Gladly because it’s much, much sim­pler to do basic actions like giv­ing the user options and sav­ing them like that. Let’s begin the class:

These are some nice three lines of code. Let’s cre­ate a con­structor func­tion now. Basic­ally, it means we write a func­tion that will tell Word­Press the widget’s unique ID, its name and its descrip­tion. Be care­ful choos­ing the ID, because for one it should be unique to not con­flict with other wid­gets, and for the other if you want to pre­serve your widget’s pos­i­tion in the side­bar as well as its set­tings you will have to bear with that same ID for ever.

Who are you, widget-chan?

The $ops array con­tains the options for the wid­get. ‘Class­name’ defines what class attrib­ute the widget’s con­tainer will have. And ‘descrip­tion’ is what help text will be shown to the user on the Wid­gets page. The first param of the WP_Widget call is the unique ID I talked about before, the $name is the title that will be shown to the user on the Wid­gets page, and $ops is the call to the options above.

Giv­ing the user a choice

But don’t you think the user should have some voice too? If you want your wid­get to have cus­tom­iz­able options, you will need this function:

This is a bit more dif­fi­cult to explain since it’s a lot of code, but prac­tic­ally, to add new text fields you just have to copy the <p></p> sequence and change ‘title’ to whatever you want. Also, to secure your/user’s data­base, run the options val­ues through the esc_attribute func­tion like with the $title above.

Sav­ing the customizations

To save the updated options into the data­base, we need this little function:

The wid­get itself

That allows some fil­ter­ing in case you want to. But hell, we’ve gone through all these func­tions, but where’s the actual wid­get?! This in its most basic form simple func­tion does the magic:

The two argu­ments the func­tion takes are the theme-specific set­tings and the user-customized options from the Wid­gets page. To sim­plify their use and refrain from writ­ing e.g. $args[’before_title’], we extract the former, which makes the array access­ible via e.g. $before_title. Everything yours must be wrapped inside $before_widget and $after_widget, and the widget’s (in our case the cus­tom­ized) title must be wrapped inside $before_title and $after_title if you don’t want to screw up the side­bar and the theme in gen­eral. In our vari­ant of the func­tion, it prints the cus­tom­ized title in case it’s set and our pre-defined one in case not, after what it prints some Hello World text (‘The con­tents’). Instead of the lat­ter you can do whatever you want. That’s all. Simple, didn’t I say that?

The wid­get, it exists!

The only thing that’s left to do to have this wid­get on your Wid­gets page is to tell Word­Press it exists. For that pur­pose, we have to call an action hook out­side of the class like this:

There are many vari­ants of that last piece of code in dif­fer­ent tutori­als, and the most dif­fer in what action hook is actu­ally to be called, but this is the best and right one.

Sum­mary

Now, the code as it should look complete:

You can change the name of the new_widget class and the new_widget func­tion, but don’t for­get to change ‘new_widget’ inside the last action hook call then.