<?php
/*
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
*/
 
function widget_widgetTutorial($args) {
// First we grab the Wordpress theme args, which we
// 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;
}

You should already have read part one, and know what all the above does.

We have two more things to do to get this widget working. Firstly we need to put together our options function, which allows the user to set the variable ‘text’ to whatever they want. Secondly we need to ‘register’ the Widget with WordPress so that it actually appears as part of your blog.

In this, part 2 of a 3 part tutorial, we’re going to concentrate on setting up those options. In the third and final installment we will register the widget with WordPress and launch it!

Setting Widget Options

What do we mean by options? Well, in your WordPress Dashboard you are able to access all, and edit some, of your widgets. We now need to create that ability to edit the widget options, which will look a little something like this to the user…

To set our options, we just need a relatively simple function.

function widgetTutorial_control() {
 
// We need to grab any preset options
$options = get_option("widget_widgetTutorial");
 
// No options? No problem! We set them here.
if (!is_array( $options )) {
$options = array(
'title' => 'Widget Title',
'text' => 'Widget Text'
);
}
 
// Is the user has set the options and clicked save,
// Then we grab them using the $_POST function.
if ($_POST['widgetTutorial-Submit']) {
$options['title'] =
htmlspecialchars($_POST['widgetTutorial-WidgetTitle']);
$options['text'] =
htmlspecialchars($_POST['widgetTutorial-WidgetText']);
// And we also update the options in the Wordpress Database
update_option("widget_widgetTutorial", $options);

And inside this function we have some fairly vanilla HTML…

<label for="widgetTutorial-WidgetTitle">Widget Title:</label>
<input type="text"
id="widgetTutorial-WidgetTitle"
name="widgetTutorial-WidgetTitle"
value="<?php echo $options['title'];?>" />
 
<label for="widgetTutorial-WidgetText">Widget Text:</label>
<textarea id="widgetTutorial-WidgetText"
name="widgetTutorial-WidgetText"
cols="30" rows="4">
<?php echo $options['text'];?>
</textarea>
 
<input type="hidden"
id="widgetTutorial-Submit"
name="widgetTutorial-Submit"
value="1" />

You’ll spot the cheeky little bit of php in there, and , which obviously loads our options into the form fields.

And the final bit of PHP, closing the function with curly braces.

}

Okay, calm down! Let’s look at each little bit and piece it together. The first thing we do in the function is see if any options have previously been set.

$options = get_option("widget_widgetTutorial");

get_option is the standard WordPress way to grab options for our widget, which it then loads into an array that we’re calling (rather inventively) $options. The argument for the get_option function is the name of the widget, which in our case is “widget_widgetTutorial”. We’ll find out how that name is set a little later, and it can be called whatever you like.

Next up, if there aren’t any values in that array (which means the options have NOT been set), then let’s set up a couple of deafult values…

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

If $options is an NOT an array (!is_array), let’s add our own values. $options['title'] is set to the default value of ‘Widget Title’, and $options['text'] is set to ‘Widget Text’.

If, on the other hand, $options is an array when we need to find out what options have already been set.

if ($_POST['widgetTutorial-Submit']) {
$options['title'] =
htmlspecialchars($_POST['widgetTutorial-WidgetTitle']);
$options['text'] =
htmlspecialchars($_POST['widgetTutorial-WidgetText']);
update_option("widget_widgetTutorial", $options);
}

First we check that the form has already been submitted. You’ll spot in the HTML a little farther above that we have a hidden field called ‘widgetTutorial-Submit’, and at the start of this if statement we are simply testing to see if that’s ‘true’ – in other words, has the user just changed and saved the options.

If it has, it means the user has already submitted some options, and we need to grab em!

$options['title'] =
htmlspecialchars($_POST['widgetTutorial-WidgetTitle']);

It’s simple enough. We flush out any unwanted junk with the php command ‘htmlspecialchars‘, and then we use $_POST to grab hold of the values the user entered into the form before pressing submit.

So now we have both the options, as set by the user, in our array. We now just need to update the widget, which we do by relying on another useful WordPress function:

update_option("widget_widgetTutorial", $options);

All we’re doing is telling WordPress to take the options we have stored in our array $options and save them into our widget widget_widgetTutorial. WordPress then does the rest for us!

You can download the code from Part 2 (Right-click the link, and select “Save As”).

Head on over to part 3 where, finally, this will all come together and your first WordPress Widget will be born!