The first step in adding a new widget-ready area to your theme is to register it with WordPress, so that it will appear in the widget administration interface.

To keep our functions.php file nice and tidy, let’s create a new file in the library directory of our child theme; we’ll call it widget-areas.php and include it as follows in functions.php:

include('library/widget-areas.php'),

In this file, we’ll put all the code required to register and display our new widget-ready area. To register it we need to call on WordPress’s register_sidebar function. It accepts an array of options that define the new sidebar:

<?php

// Register the extra Footer Aside
function wicked_footer_aside() {
  register_sidebar(array(
    'name' => 'Main Footer Aside',
    'id' => 'footer-aside',
    'description' => __('A widget area in the footer, above the subsidiary 
↵asides.', 'thematic'),
    'before_widget' => thematic_before_widget(),
    'after_widget' => thematic_after_widget(),
    'before_title' => thematic_before_title(),
    'after_title' => thematic_after_title(), )
  );
}
add_action('init', 'wicked_footer_aside'),

?>

The array passed to register_sidebar needs to have the following values:

For more info about how to use register_sidebar, you guessed it: check out the WordPress Codex.

Now that the widget-ready area is registered, it will appear in the back-end interface and you can add widgets to it. However, we’ve yet to call on it in any of our templates, so as they stand, these widgets would never be displayed. Let’s fix that now.

So we’ve registered our new widget-ready area, but currently it only exists on the back-end interface, and nowhere on the front end. We now need to insert it in a template for it to appear. When we added the page list to the footer-homepage.php template in Chapter 5, we put it right above the call to thematic_footer. Now that we know about hooks, we can just add our function to that action hook and we should be good to go. Add this code to your widget-areas.php file:

// Add footer Sidebar Area
function add_wicked_footer_aside() {
  if (is_sidebar_active('footer-aside')) {
    echo thematic_before_widget_area('footer-aside'),(1)
    dynamic_sidebar('footer-aside'),(2)
    echo thematic_after_widget_area('footer-aside'),(3)
  }
}

add_action('thematic_footer','add_wicked_footer_aside', 10);

What we’ve done here is created a function called add_wicked_footer_aside, and used it to grab our newly registered sidebar, called footer-aside, and add it to the top of Thematic’s footer. There’s a conditional statement—if (is_sidebar_active('footer-aside'))—that checks to see if the sidebar is active; in other words, if it has widgets added to it. This tells the theme to only show the widget area if the user has added widgets. After that come the three essential lines that we use to output the actual markup of our widget-ready area:

Any time you want to output a widget-ready area with the benefit of Thematic’s extra markup and filters, you’ll need to use those same three lines of code, so remember them well.

At this point, if you add a few widgets to your new Main Footer Aside, you should see them appear on the site above the subsidiary asides. The aside just needs a few quick styles to set it to be the same width as the main content area:

#footer-aside {
  width: 940px;
  margin: 0 auto;
}

Victory!

To create a new widget in WordPress, you extend the WP_Widget class. If this seems a bit beyond your grasp, don’t worry: when developing WordPress widgets, it’s unnecessary to think about objects and classes very much. Every widget class has the same four functions inside it, so you only need to write those four functions for every widget—and you can just copy and paste the basic layout of the class every time you want to make a new widget. The four functions you need are a constructor function (which always has the same name as the class itself), widget, update, and form.

Let’s first have a look at the empty shell of a new widget:

class My_Widget extends WP_Widget {
  function My_Widget() {
    // this is a constructor, where each new instance of your widget gets built
  }

  function form($instance) {
    // this generates the widget options form which you see
    // in the widgets section in the admin
  }

  function update($new_instance, $old_instance) {
    // this handles the submission of the options form to 
    // update the widget options
  }

  function widget($args, $instance) {
    // the most important function: this one handles actually outputting
    // the widget's content to the theme
  }
}

Assuming you’ve filled out each of these functions with your desired functionality, there’s only one step left. Much like widget-ready areas, new widgets need to be registered with WordPress:

register_widget('My_Widget'),

At the most basic level, the form and update functions only need to give your users the option to input the title to be displayed with the widget. This means that unless you require more detailed options here, you can reuse the same code for those two functions for each widget you develop.

To create our first custom widget, we’ll first create a widgets folder inside our child theme folder, and add a new PHP file to it. We’ll call it author-data.php. Let’s start by putting in the declaration of the Author_Data_Widget class, along with the four required functions and the register_widget call:

<?php

class Author_Data_Widget extends WP_Widget {
  function Author_Data_Widget() {

  }

  function form($instance) {

  }

  function update($new_instance, $old_instance) {

  }

  function widget($args, $instance) {

  }
}

register_widget('Author_Data_Widget'),

?>

Our first task is to write the constructor function. In its most basic form, it consists of:

function My_Widget() {
  $this->WP_Widget($id, $name, $widget_ops, $control_ops);
}

That one function ($this->WP_Widget) is what WordPress uses to create each instance of your widget, so that’s all that’s necessary here. The $id parameter is used internally to refer to your widget, and $name is the name that’s shown in the widget admin interface. The $widget_ops parameter is an array that includes the widget’s description to be shown in the admin section. $control_ops is optional and not required for most widgets, so you can forget about it for now.

Let’s have a go at writing this function for our author data widget:

function Author_Data_Widget() {
  $widget_ops = array(
    'description' => 'A widget that displays author info on single posts.' 
  );
  $this->WP_Widget('author_data', 'Author Data', $widget_ops);
}

Even with only this one function in place, we can already see our widget in the back-end interface, as shown in Figure 6.1.

Figure 6.1. Our custom widget, as it appears in WordPress’s admin section

However, if you drag the widget onto one of your widget-ready areas, you’ll see that it lacks any customizable options, as shown in Figure 6.2.

Figure 6.2. Our newly defined widget has no options

We’d like our users to at least be able to set a custom title for the widget, so we should fill out the form and update functions to give us an options form. Let’s start with the form method.

Fortunately, WordPress handles the creation of the form element; all you need to do is write the label and input elements specific to your option. These must be assigned specific id and name attributes in order to work correctly, but again WordPress has your back: your widget has functions called get_field_id and get_field_name that serve this purpose. Here’s what our simple form looks like:

function form($instance) {
  $title = esc_attr($instance['title']);

  ?>
    <p>
      <label for="<?php echo $this->get_field_id('title'), ?>">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>
    </p>
  <?php
}

The function receives an $instance variable that represents the current widget, which will include the options that are currently set. So, to make sure the form displays the current value of the title, we first extract the $title variable from $instance.

Then we construct the form field, using $this->get_field_id and $this->get_field_name to set the field’s id and name attributes. Other than that, this is fairly straightforward HTML. If you want your form to have more than one field, all you have to do is add them here, setting their attributes appropriately.

When the form is submitted, WordPress will use your update function to save the options the user has entered. Let’s have a look at that next:

function update($new_instance, $old_instance) {
  $instance = $old_instance;
  $instance['title'] = strip_tags($new_instance['title']);

  return $instance;
}

The update function works a little differently: it receives two parameters, which hold a brand new widget containing the new options submitted in the form, and the old widget with the previous options, respectively. So we need to grab the title from $new_instance—being careful to strip out any HTML and PHP tags—and use that to set the title on our instance. To avoid confusion, we’ve dumped $old_instance into a new variable simply called $instance, and that’s where we set the new title. Then we return $instance, and WordPress handles the rest, updating the widget with the options we’ve set.

If your form has more than one field, just repeat this process for each option that requires setting. You can include as much logic as you want in update. If ever you’d like to discard the new options (based on some condition), all you have to do is return false and the widget won’t be updated.

Now that we have our options form, test it out: go back to your widgets admin page, and drag the Author Data widget onto one of the widget areas. You should see your new title form, as shown in Figure 6.3.

Figure 6.3. A simple widget options form

That’s three out of four functions defined: we have our constructor, as well as the form and update methods for handling our widget options form. Now all that’s to be done is tell WordPress how to display the widget!

Here’s what that function will look like:

function widget($args, $instance) {
  extract($args, EXTR_SKIP);(1)

  if (is_single()) {(2)

    echo $before_widget;(3)
    $title = apply_filters('widget_title', $instance['title']);(4)

    if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };(5)
    echo '<div class="author-data">';
    echo get_avatar(get_the_author_meta('user_email'), 150);(6)
    echo '<h4>' . the_author_meta('display_name') . '</h4>';
    // Is there an author description?
    if (get_the_author_meta('description')) {
      echo '<div class="description"><p>' 
          . get_the_author_meta('description') 
          . '</p></div>';
    }
    echo '</div>';
    echo $after_widget;(7)
  }
}

Your function receives two parameters: the first one is $args, which is an array of the arguments provided to all widgets in your theme. They will be familiar to you: before_title, after_title, before_widget, and after_widget. The second parameter is our old friend $instance, which contains all the options set on your widget. In our case that’s only the title.

Here’s a breakdown of what’s going on in there:

Now that you’ve written all the functions required for your widget, it should correctly display the author info on single-post pages. Give it a try!

Here’s the full author-data.php file:

<?php

class Author_Data_Widget extends WP_Widget {
  function Author_Data_Widget() {
    $widget_ops = array(
      'description' => 'A widget that displays author info on single posts.' 
    );
    $this->WP_Widget('author_data', 'Author Data', $widget_ops);
  }

  function form($instance) {
    $title = esc_attr($instance['title']);
    ?>
      <p>
        <label for="<?php echo $this->get_field_id('title'), ?>">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>
      </p>
    <?php
  }

  function update($new_instance, $old_instance) {
    $instance = $old_instance;
    $instance['title'] = strip_tags($new_instance['title']);

    return $instance;
  }

  function widget($args, $instance) {
    extract($args, EXTR_SKIP);
    
    if (is_single()) {
    
      echo $before_widget;
      $title = apply_filters('widget_title', $instance['title']);
  
      if (!empty($title)) { echo $before_title . $title . $after_title; };
      echo '<div class="author-data">';
      echo get_avatar(get_the_author_meta('user_email'), 150);
      echo '<h4>' . the_author_meta('display_name') . '</h4>';
      
      // Is there an author description?
      if (get_the_author_meta('description')) {
        echo '<div class="description"><p>' 
            . get_the_author_meta('description') 
            . '</p></div>';
      }
      echo '</div>';
      echo $after_widget;
    }
  }
}

register_widget('Author_Data_Widget'),

?>