Rusty's Blog

Wordpress 2.8 introduces a new object-oriented Widget API (based on Alex Tingle’s MultiWidget class) which is an improvement over the procedural API for Wordpress 2.7 and before. It’s not a revolutionary leap, but it does make coding widgets which need to appear multiple times on a page easier, automates some administrative form handling, and makes code better-organized and easier to follow.

The bad news is the new API isn’t backwards compatible without a little work. So here is the first part of a multi-part guide for porting a Wordpress 2.7 widget over to the new Wordpress 2.8 API.

Why widgets?

I’ll pause a second here. You know what a Wordpress widget is, right? No?

A widget is a block of content that usually goes in the sidebar. Wordpress has a system for creating and managing these blocks of content. There is a page in the administration section for organizing these widgets, and a programming API for developers to quickly create them and make them available to users.

Why is this a good thing? Back in the dark pre-Wordpress 2.2 days, most everything in the sidebar of a Wordpress blog was coded inside a template, which meant you had to know some HTML and PHP and have access to the templates to make any changes to the content that appeared there.

This was nice for developers like me because clients had to come to me anytime they wanted anything in the sidebar changed or even moved around. It was not so great for end users who wanted to focus on content instead of code, and who would rather spend their development budget on new features instead of mundane content updates.

An example Wordpress 2.7 widget

This simple example of a Wordpress 2.7 widget prints a customized blogroll like the one in my sidebar. There are no user configuration options, so no forms to code or data processing to worry about.

function widget_rt_blogroll($args) {
	extract($args);
	echo $before_widget;
	wp_list_bookmarks('category=2&category_before=&category_after=');
	wp_list_bookmarks('category=55&category_before=&category_after=&title_before=<h2 class="blogroll-old-blogs-head">');
	echo $after_widget;
}
function rt_blogroll_init() {
	register_sidebar_widget('rustytanton.com Blogroll', 'widget_rt_blogroll');
}
add_action('plugins_loaded','rt_blogroll_init');

You could drop that code into the functions.php file in your theme or into a plug-in, and then a widget would be available in the widget admin section to place in your sidebar. Wherever you placed the widget, a customized blogroll would print out. Here’s what was happening with that code:

1. After Wordpress loaded all its plugins, it called rt_blogroll_init, which registered widget_rt_blogroll with the widget API.
2. When Wordpress was ready to display all registered widgets, the widget API passed widget_rt_blogroll an array of theme settings (called $args here) which would look something like this if you printed it out:

Array (
	[after_title] => '</h2>',
	[after_widget] => '</li>',
	[before_title] => '<h2>',
	[before_widget] => '<li>'
)

3. The extract function converted the keyed array into variables which were used in the rest of the function
4. The remaining code within widget_rt_blogroll executed and printed a widget on the page.

This is a very simple example. Most widgets worked like this in 2.7.

The same widget coded with the Wordpress 2.8 API

class RT_Blogroll extends WP_Widget {
	function RT_Blogroll() {
		parent::WP_Widget(false, $name = 'rustytanton.com Blogroll');
	}

	function widget($args, $instance) {
		extract($args);
		echo $before_widget;
		wp_list_bookmarks('category=2&category_before=&category_after=');
		wp_list_bookmarks('category=55&category_before=&category_after=&title_before=<h2 class="blogroll-old-blogs-head">');
		echo $after_widget;
	}
}
add_action('widgets_init', create_function('', 'return register_widget("RT_Blogroll");'));

The most obvious difference is all the widget functions are now contained within a single class. I called mine RT_Blogroll in this example. You can call yours anything you want, but note that you need to include a constructor function with the same name which calls parent::WP_Widget like I did in the example. This function is necessary in all Wordpress 2.8 widgets to provide a display name for the widget in the admin section. In 2.7, the name was passed as the first argument in register_sidebar_widget.

You’ll also notice a function called widget within the class. This is one of three functions from the parent WP_Widget object you can extend. Briefly, here are their names and what they do:

• widget – prints out your widget on the page when an end user views your blog
• form – outputs an editing form in the admin section
• update – processes updates from the form in the admin section

The minimum effort necessary to have a functional widget object is to write a widget function and to specify a name through the constructor function, and we’ve done that here.

The widget function has the same $args parameter that a widget display function in 2.7 had, and also adds the $instance parameter. We’ll talk more about $instance, which contains data stored by the widget, in part 2.

The last part is the call to add_action at the bottom. You won’t really notice the benefit in this 2.8 example since we only made one add_action call in the 2.7 version of the widget, but a more complex 2.7 widget has to call this hook three or more times. In the 2.8 API, you only make one such call no matter how complex your widget gets. It saves room and makes the code less ugly.

The move to an object-oriented widget API also means all widgets can appear as many times on a page as you’d like, and you don’t have to account for that in your code. Trying to code widgets which could appear multiple times on a page in Wordpress 2.7 was a nightmare.

In the next post, I’ll talk about extending the form and update functions so you can have configurable settings on the admin page. Stay tuned.

This entry was posted on Sunday, June 14th, 2009 at 10:09 pm. It was tagged php, tutorial, Tutorials, Web Development, widget, widgets, wordpress, wordpress 2.7, wordpress 2.8, wordpress development, wordpress widget api. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.