Widgets and dynamic sidebars allow WordPress to be one of the most flexible CMS’s on the planet. In WordPress 2.8 a new way of creating widgets was introduced. In this tutorial we’re going to cover creating WordPress widgets. We’ll also touch on the WP HTTP API and transients.
The mission: create a widget that displays our most recent tweet.
1. Outline Your Widget
You create a new WordPress widget by doing two things: (1) creating a class that extends WP_Widget and (2) registering that widget with the
In you class you have to implement four methods (functions): a PHP4 style constructor with the same name as the class, update, form, and widget. The constructor is what sets up your options like the widget html class name and ID base – it’s also where you define the widget name.
update takes care of cleaning the widgets data on save, and
form contains the actual HTML input form for the widget. The
widget function is where the magic happens: it contains all your display logic.
So your basic widget class might look something like this…
2. Set Up Some Widget Options
In your constructor, you define an associative array containing a
description. Classname is the HTML class that will get passed into the widget’s container. This is useful if your widget also includes styling elements. The
description is shown on the widgets screen.
After defining the options array, you’ll pass it in the WP_Widget constructor, which takes three arguments: the id base of the widget, the widget title, and the options array.
3. Build the Widget’s Form
Our widget is going to have to fields: a title and a twitter user name. We’ll create the form in the
form function, which is going to receive an array of the options. Throughout this tutorial, we refer to this as
$instance. Behind the scenes, WordPress is going to look for the options for a given widget in the database. Those options are passed as what we call
Of course, if this is a brand new widget, with no saved options, the array with be empty. So we can set up an array of defaults then use
wp_parse_args to make sure those defaults are used. After that, it’s just a matter of some basic HTML form stuff. The only catch is that will use two
WP_Widget methods to get field IDs and names:
get_field_id. Both return “safe” names that don’t conflict with other widgets on the WordPress admin widget screen.
4. Clean Stuff Up
update method receives two arguments: the old instance and the new (which contains the updated settings). This is your typical data validation stuff.
5. The Fun Part: Displaying the Widget
widget handles the display of the widget. The first argument it receives the array of arguments for the sidebar (including the before and after widget tags and all that). It also receives the
$instance which contains the options for the specific widget.
So, first off, let’s extract the general sidebar arguments, and echo out the
$before_widget variable. Then we’ll see if we have a widget title. If we do, we can echo out the
Next up, we’ll avoid the question of getting the tweet and call another method,
get_tweet, that we’ll implement later (see below). Then we can echo out the
6. Fetch the Tweet
What we don’t want to do on every page load is hit the Twitter API. So, instead, we’re going to save our tweet as a transient, WordPress’ method for storing data that expires. In our method, we’ll see if we can get the transient first. If we can, then we’ll just return that. Otherwise, we’ll have to go to the API.
To fetch our tweet, we’ll use wp_remote_get. Which will either return an array of a whole bunch of stuff or a WP_Error object. The array will contain header and status code information, so we can make sure we actually got a response. If we didn’t, just return an empty string. Maybe better luck next time.
Twitter will give us a JSON, which can decode with PHP’s
json_decode After that, we’ll see if our status is set, grab it, and make any links clickable with WordPress’
The final piece of the puzzle is setting our transient, so we don’t have to do this whole API call over and over again. After that, we can return the tweet.
That’s the twitter function is reusable anywhere you’d like.
7. Finally, Register the Widget
The very last step is to register the widget. Hook a function in
widget_init. Inside it, you can call
register_widget, which takes one argument: the class name we’ve been working on above.
That’s it! All the code for this tutorial is available as a plugin, so check it out!