Let’s talk widgets. More specifically WordPress sidebar widgets. So why should you care about this particular type of widget. Let’s start from the beginning…

A long time ago…

… on a blog far, far away some overly enthusiastic bloggers wanted to add their own RSS feed icon on their blog’s sidebar. So they merrily hacked away at their sidebar.php template file adding some custom code and got something similar to this (if you do not already know how WP blogs are built under the hood, you can find out at the WP’s theme documentation pages):

But soon their designer protested: “No, no, no… That is terrible. We need to put the RSS icon as a second item in the sidebar below the about text. (evil grin)”. So our poor little bloggers got faced with a dilemma. Their whole sidebar before the RSS icon was composed dynamically from components (widgets ;)) which were selected from the blog administration interface. That required no programming knowledge whatsoever and even their designer could do that with no problem. With their hacking they introduced a bad thing – the RSS icon can not be moved from the first position in the sidebar without additional adrenaline-rising sleep-deriving code-crunching… err… work.

So the obvious conclusion reached after a few sleepless nights and who knows how many mugs of coffee was they needed to widgetize their RSS icon.

The widgets strike back

So how did they do it. Easy… Their hacked-up sidebar looked something like this:

<div id="sidebar" role="complementary">
  <ul>
    <li>
      <a id="rss-icon" href="<?php bloginfo('rss2_url'); ?>">
        <img
          src="<?php bloginfo('template_directory'); ?>/images/RSS_icon.png"
          alt="RSS icon"/>
      </a>
    </li>
    <?php
      if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) :
    ?>
...

After the widgetizing makeover the sidebar lost some weight:

<div id="sidebar" role="complementary">
  <ul>
    <?php
      if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) :
    ?>
...

But wait, where did that RSS icon code run off to. It settled in the theme’s functions.php file in a slightly more evolved form:

function widget_tardigrade_rss_link($args)
{
  extract($args);
?>
  <?php echo $before_widget; ?>
    <a id="rss-icon" href="<?php bloginfo('rss2_url'); ?>">
      <img
        src="<?php bloginfo('template_directory'); ?>/images/RSS_icon.png"
        alt="RSS icon"/>
    </a>
  <?php echo $after_widget; ?>
<?php
}
register_sidebar_widget(
  'Tardigrade RSS link',
  'widget_tardigrade_rss_link'
);

We see that the link and image tags are still here but the whole thing is now surrounded by the output from $before_widget and $after_widget PHP variables. The standard WP sidebar is composed as an unordered list of elements and these variables are here to make sure our widget plays nice with whatever WP theme it ends up inhabiting. More specifically, these variables contain opening and closing tags for the HTML list element in our case. In the end we register our widget using WP’s register_sidebar_widget() function which makes our widget “known” to the WP widget mechanism.

And now we can reposition the icon by using the drag-and-drop goodness from the WP administration panel. Here is our sidebar after the ordeal:

Not much has changed except the icon position, but that is the whole point. We meant it to look exactly the same and be more flexible at the same time.

In general code for some custom widget looks like this:

function widget_function($args)
{
  extract($args);
?>
  <?php echo $before_widget; ?>
    <?php echo $before_title; ?>
      Widget Title
    <?php echo $after_title; ?>
    Widget content.
  <?php echo $after_widget; ?>
<?php
}
register_sidebar_widget(
  'Widget Name',
  'widget_function'
);

Here we see a new pair of PHP variables: $before_title and $after_title. As a generic widget can have a title (like Latest posts or Archives built-in WP widgets do) we must predict that possibility. In our case these variables would output h2 header opening and closing tags with a widgettitle CSS class.

So what did we get from all of this trouble?

The nice thing about this is that the RSS icon is now more independent from our sidebar. We can reposition, remove or add icon without even touching a single line of code, all from WP administration panel. Heck, even our designer can now reorder widgets if the mood strikes him which leaves us with more time to do something more productive. That makes him happy and making your designer happy is almost always better then making him hospitalized ;)

If you want to know more about WP widgets there are some great resources and reading material on the WP widgets documentation page. Also in a future post we will discuss giving our widget an object oriented makeover.