Richard Shepherd

So how do you put together your own WordPress widget? All you need is to know your way around PHP. If you can program your application in PHP the chances are it can be turned into a Widget.

I’m first going to go through the structure of a Widget, and then we’re going to get our hands dirty with some code.

A basic Widget has four main components:

1. The Widget Information
2. The Widget Itself
3. Any options for the Widget
4. Initialising/Registering the Widget

Widget Header
The Widget Information is just a bit of information at the top of the file which WordPress uses to describe the Widget. It might look like this…

/*
Plugin Name: A Simple WordPress Widget Tutorial
Plugin URI: http://www.richardshepherd.com
Description: Simple Widget Tutorial from RichardShepherd.com
Author: Richard Shepherd
Version: v1.0
Author URI: http://www.richardshepherd.com
*/

Everything there is fairly self explanatory. The URI (Uniform Resource Identifier) is just a fancy (and more correct) way of describing the URL. Don’t worry too much about that for now.

Widget Functions
After that header, we have three functions to write.

function widgetTutorial() {}
function widgetTutorial_control() {}
function widgetTutorial_init() {}

The first function is the Widget itself, the second is where we set and store the options, and the third kicks the whole thing off.

So, what can be in a Widget? Well anything you can write in PHP. Perhaps is a fun new application you’ve been tinkering with, or maybe just a way of displaying random photos. Whatever it is, we need to write the code and pop it in the WidgetTutorial() function.

Writing the Widget
For our purposes we are going to display a header and some text. Both items can be edited from the Manage > Widgets page in your wp-admin. This is a pretty pointless Widget, but hopefully it’ll open the doors to some fun development for you.

Our Widget function could simply be…

function widgetTutorial($args) {
  extract($args);
  echo $before_widget;
  echo $before_title;
  echo 'Hello World!'; // Our Title
  echo $after_title;
  echo 'This is the main Widget text.'; // The text.
  echo $after_widget;
}

You should be familiar with things like echo ‘Hello World’; but what are all those other bits and bobs?

Well, imagine that WordPress has hundreds upon hundreds of Themes. We need to make sure that your Widget will integrate properly with each and every one of them. When some talented designer puts together their theme, they include CSS definitions for Sidebar Widgets and, thanks to the magic of WordPress, we can access them easily. In fact, we don’t even have to see them. All we need is to drop in

extract($args);

and then we’ll grab the relevant variables from the $args array. In our case, there are four variables we’re interested in:

$before_widget, $before_title, $after_title, $after_widget;

You can even see that their order mirrors HTML tags. You could almost imagine them written as:

<widget>
 <title>
 </title>
</widget>

although of course that wouldn’t work at all!! So, we extract those variables which go on to define the layout and then start to put together the Widget using echo commands. It really is that simple.

Dynamic = Interesting
But that’s a static Widget which is, quite frankly, boring. What we’re interested in is setting up some options to make this puppy a bit more dynamic. Start introducing a bit of randomness, and you have a truly dynamic page – no two views are the same. So let’s have a look at how that Widget function changes to accommodate our new options:

function widget_widgetTutorial($args) {
// First we grab the Wordpress theme arguements,
// which we'll use to display the widget.
extract($args);
 
// Now we sniff around to see if there are
// any preset options
$options = get_option("widget_widgetTutorial");
 
// If no options have been set, we need to set them
if (!is_array( $options )) {
$options = array(
'title' => 'Widget Title',
'text' => 'Widget Text'
);
}
 
// Display the widget!
echo $before_widget;
echo $before_title;
echo $options['title'];
echo $after_title;
//Our Widget Content
echo $options['text'];
echo $after_widget;
}

It’s really not that different. All we’ve added is

$options = get_option("widgetTutorial");
if (!is_array( $options )) {
$options = array(
'title' => 'Widget Title',
'text' => 'Widget Text'
);
}

and

echo $options['title'];
echo $options['text'];

First we create an array called $options, and populate with our Widget options (we’ll learn how to set these later). get_option() is a WordPress function which returns all the options into our array.

Next we test to see if the array $options is empty. If it is, it means no options have been set and we have to make up some default values. We do that with if (!is_array( $options )). Where the ! changes ‘is array?’ to ‘is not array?’. If it isn’t, we create the array in the standard way and pop in some default variables. That’s fairly straightforward.

All we do next is output parts of the array in our widget, using echo $options['title']; and echo $options['text']; where ‘title’ and ‘text’ are the options we have previously set.

Make sense? I hope so. You can download the code from Part 1 (Right-click the link, and select “Save As”).

In part two of this tutorial, we’ll look at putting together the options screen. See you soon!