Talk In Code

A widget is a little program that fits into the side menu of your site. These widgets can be moved around using the admin section of your WordPress blog and there are quite a few to chose from with a default install.

To create a theme that supports widgets you can follow the instructions in the post creating a widget proof WordPress theme.

You can create a widget in one of two places, either within your functions.php file of your template, or in a plugin. To get a widget to display you need to call a function called register_sidebar_widget(). This function takes two parameters, the name of the widget in the admin section, and a callback function that controls what the widget contains.

register_sidebar_widget(__('My Widget'), 'myWidgetFunction');

The callback function takes a single parameter called $args, which is used to pass in all of the parameters that are set in the register_sidebar() function call. The first thing you have to do is use the extract() function to convert the $args variable into separate variables. After this function you will have access to such variables as $before_widget, $after_widget, $before_title and $after_title.

The following is an example of a very simple widget callback function that produces a widget with a single bit of text.

function myWidgetFunction($args) {
 extract($args);
 echo $before_widget;
 echo $before_title . __('My Widget') . $after_title;
 echo '<ul><li>The contents of my widget go right here.</li></ul>';
 echo $after_widget;
}

Of course if you wanted the widget to do something more interesting, which is probably your intent, then you can replace this line of text with a loop, or function call or whatever you need.

When you visit the widgets page in the Design section of your blog admin you will now see a widget called My Widget, which you can add to the current widgets on your blog.

Finally, you might have noticed that there is no descriptive text for the widget in your admin section. To add this you have to use the wp_registered_widgets variable, which contains an array of the registered widgets. You need to reference your widget and set an option called description to set the description in your admin section.

$wp_registered_widgets[sanitize_title('My Widget')]['description'] = 'A description of your widget.';

This took me quite a while to track down, and doesn’t seem to be in any of the WordPress codex.

When adding a search form to your WordPress blog you will want to have control over what sort of form is displayed. It is possible to override the search form created by the widget function without having to go into the /wp-includes/widget.php file and editing the wp_widget_search function. Here is the function that is present in WordPress 2.6.

function wp_widget_search($args) {
 extract($args);
 $searchform_template = get_template_directory() . '/searchform.php';
 
 echo $before_widget;
 
 // Use current theme search form if it exists
 if ( file_exists($searchform_template) ) {
  include_once($searchform_template);
 } else { ?>
  <form id="searchform" method="get" action="<?php bloginfo('url'); ?>/"><div>
  <label class="hidden" for="s"><?php _e('Search for:'); ?></label>
  <input type="text" name="s" id="s" size="15" value="<?php the_search_query(); ?>" />
  <input type="submit" value="<?php echo attribute_escape(__('Search')); ?>" />
  </div></form>
 <?php }
 
 echo $after_widget;
}

Notice that the first thing the function tries to do is load a template file called searchform.php, and if this doesn’t exist the function prints out a standard search form. That is it basically. If you want to override the search form created by this function then just create a file called searchform.php in your template directory and create a search form inside this file. The form must have the following:

• The action of the form should go to the home of the blog. So if your blog is located at domain.com/blog then the action should go to there.
• The method of the form should be get, but the form will also work with a post method.
• A text input box must be present and this must have the name of s.
• For good search form usability you should print out the search query in the text field of the form. This can be done with the function the_search_query(), which will print out the search query, if there is one.

There are many different ways to create a search form. I found these two in two different templates, created by different people.

<h2>Search</h2>
<form method="get" id="searchform" action="<?php echo $_SERVER['PHP_SELF']; ?>">
<div class="searchbox">
<label for="s">Find:</label>
<input type="text" value="<?php echo wp_specialchars($s, 1); ?>" name="s" id="s" size="14" />
<input type="submit" id="searchsubmit" value="Search" />
</div>
</form>

This one will print out a little bit of JavaScript in the text box.

<div id="search">
<form method="get" id="searchform" action="<?php bloginfo('home'); ?>/">
<div><input type="text" value="search..." name="s" id="s" onfocus="if (this.value == 'search...') {this.value = '';}" onblur="if (this.value == '') {this.value = 'search...';}" />
</div>
</form>
</div>

They both seem to work quite well, but I would advise that any search form you create should be copied from the original and modified. This is usually the best practice with WordPress themes as the WordPress documentation can be a little thin on the ground (or hidden) and their developers tend to use the best functions available.