Tag Archives: api

WordPress 2.8 – New Widget API

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

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 APIPlugin URI: http://www.paulmc.org/whatithink/Description: Demonstration of the WordPress 2.8 Widget APIVersion: 1.0Author: Paul McCarthyAuthor 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() {$widget_ops = array ('classname' => 'my_widget', 'description' => __('The description for your Widget') );$control_ops = array ('width' => '300', 'height' => '400');$this->WP_Widget('my_widget', __('My Widget'), $widget_ops, $control_ops);}

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) {extract ($args);$title = empty($instance['title']) ? __('My Widget Title') : apply_filters('widget_title', $instance['title']);$text = apply_filters('widget_text', $instant['text']);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) {$instance = $old_instance;$instance['title'] = strip_tags($new_instance['title']);$instance['text'] = $new_instance['text'];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) {$instance = wp_parse_args( (array) $instance, array('title' => '', 'text' => ''));$title = strip_tags($instance['title']);$text = format_to_edit($instance['text']);?><p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?><input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo attribute_escape($title); ?>" /></label><textarea class="widefat" rows="16" cols="20" id="<?php echo $this->get_field_id('text'); ?>" name="<?php echo $this->get_field_name('text'); ?>"><?php echo $text ?></textarea></p><?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. []

Updating Your WordPress Theme to Use More Than One Sidebar

Since I started working on my own themes, I’ve learnt a lot about how WordPress works. I’m still not at the level where I can write a theme from scratch, but I’m learning to modify themes for my own use. My first themes were based on either Public Domain or GPL themes, and I mainly stuck to modifying the CSS stylesheet.

My latest theme now uses five different sidebars to display information. There are four on the homepage (home.php) and one on the single post page (single.php). Most themes that I’ve come across implement one sidebar, or at most two. So how do you add more sidebars?

The first step is to edit your themes function.php file. Search the file for the following code:

if ( function_exists('register_sidebar') )

Some themes might also use the following code instead:

if ( !function_exists('register_sidebars') )

Within this section you’ll need to locate the code that tells WordPress how many sidebars you are using. Themes using a single sidebar will generally use this WordPress API function:

register_sidebar();

Themes using more than one sidebar, will use the following API function:

register_sidebars();

Both API functions take an array as a parameter. This array specifies the HTML code that appears before and after each widget that will appear in the sidebar. register_sidebars(); takes an additional parameter that allows you to specify how many sidebars should be used.

In either case, you’ll need to change this code to the following:

register_sidebars(x, array);

Replace x with the number of sidebars that you want in your theme. The array part of the code can be left as is.

The next step is to add the actual sidebars to the theme files that you want to contain the new sidebars. (Usually these would be either index.php, home.php, single.php, orarchives.php.)

Add the following code to the appropriate theme file:

<div class="sidebar_css_class"><ul class="sidebar_list_class"><?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar(x) ) : ?><?php endif; ?></ul></div>

The class names used in this code example can be anything that you want, and will have to be added to your theme’s style.css file. Replace x with the specific number of the sidebar that you want to insert, e.g., if you want to insert a second sidebar into the theme, then your code will look like this:

<div class="sidebar_css_class"><ul class="sidebar_list_class"><?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar(2) ) : ?><?php endif; ?></ul></div>

Upload the files to your theme directory, overwriting the original files if prompted. (To be extra safe, you should already have backed up the original files.) To configure the new sidebar, go to the Widgets sub-page under the Design page in your WordPress Admin and select your sidebar from the drop-down list.

Footnote: register_sidebar(); does allow more than one sidebar to be specified. It’s used in cases where each sidebar needs a different name and allows the theme designer to specify different layouts/ appearances for each sidebar. More information can be found on the relevant WordPress codex pages: register_sidebar(); and register_sidebars();.