What I Think

WordPress 2.8 and the new Widget API

WordPress 2.8 is due sometime this month, and one of the major changes is the new Widget API.

Hand in hand comes the new Widget Panel which uses AJAX to update your sidebars. The latest beta has the new Widget Panel included:

WordPress 2.8 Widget Panel

Still very much a work in progress, the Panel doesn’t fully work yet and there’s a bit of work to be doen on the presentation side.

Multi Widgets

The biggest change is going to be for plugin writers. The new Widget API is designed to make the process of writing widgets, especially multi widgets easier.

As anyone who has ever written a multi-widget will tell you, the documentation is virtually non-existent and what tutorials are available are cryptic.^[1]

The Widget API

As 2.8 will be released in the near future, now is the time to start thinking about updating your widgets to take advantage of the new API. As the Widget API isn’t fully documented yet, I decided to have a look at the source files to see what’s involved in writing a widget using the API.

The relevant files are:

• /wp-includes/widgets.php
• /wp-includes/default-widgets

Using the Widget API

The new Widget API provides a WP_Widget class and it’s by extending this class that you create your own widget. Your widget then over-rides 3 three methods within WP_Widget:

1. widget()
2. update()
3. form()

The easiest way to demonstrate this is by creating a basic text widget. So we’ll build a WordPress 2.8 Text Widget.

Building Your Widget

As with the current version of WordPress, your widget needs to contain the some basic information so that WordPress will recognise it as a plugin:


<?php
/*
Plugin Name: New Widget API
Plugin URI: http://www.paulmc.org/whatithink/
Description: Demonstration of the WordPress 2.8 Widget API
Version: 1.0
Author: Paul McCarthy
Author URI: http://www.paulmc.org/whatithink
*/


The first step is to create your widget class by extending WP_Widget:


class WP_My_Widget extends WP_Widget {


Your widget needs a constructor, that is, a function that will be called when the widget is loaded. Your constructor must have the same name as your widget. Within the constructor, specify an array to hold your widget options, control options and call the WP_Widget constructor.


function WP_My_Widget() {

}


Once you’ve created your constructor, it’s time to over-ride the methods needed to make your widget work. The first method to over-ride is widget().

The widget() method is where your widget does it’s work. The widget() method takes two parameters. The first provides you with access to the widget display settings and the second provides access to that particular instance settings.

As this is a simple text widget, we’ll use just two settings – title and text.


function widget($args, $instance) {

echo $before_widget . $before_title . $title . $after_title;
echo $text;
echo $after_widget;
}


The next method that we’ll over-ride is the update() method. This method provides us with the means to update and save our widget settings. It takes two parameters, the first is an array that contains the settings provided by the user via the widget form, and the second is an array containing the old settings for the widget.


function update ($new_instance, $old_instance) {

return $instance;
}


That’s it. All the method does is store the old settings in an array, update the array with the new settings and then pass the new settings back to the WP_Widget class. The WP_Widget class handles the actual updating and saving.

Our next method to over-ride is form(). This method is used to display the widget control form. It takes one parameter, an array with the current settings.


function form ($instance) {

<?php
}
}


That’s it. A simple text widget written using the WordPress 2.8 Widget API.

If you’d like to review the full code, with comments, then you can download it here:

New Widget API Plugin File

1. I’ve been looking into transforming one of my widgets into a multi-widget, but given the hassle involved, I’m just going to hold off until 2.8 is released. [↩]