Adding “Widgeted” Sidebars To WordPress Themes

Published March 26th by studioJMC in WordPress Wednesdays 4

What’s A Widget Anyway?

Last week we discussed WordPress sidebars and include files. This week we’ll explore how we can prepare our sidebars (or any other area of our theme) to accept widgets. In case you haven’t done your homework, the WordPress Codex defines a widget as being:

…like a plugin, but designed to provide a simple way to arrange the various elements of your sidebar content (known as “widgets”) without having to change any code.

I have a couple problems with that definition:

1. It’s vague.
2. The use of the term sidebar is misleading.

So let’s try our own definition.

Widget: A “drop-in” bit of code that, once installed (in a manner similar to plug-ins) can be added to any “widgeted” area of your theme (not just sidebars) through the Presentation > Widgets sub-panel of WP-admin.

Note: A bit of confusion is inevitable here since WP refers to widgeted areas as sidebars, no matter where in your theme they occur. Just remember, for our discussion today, the term sidebar refers to a widget-enabled (widgeted) area not an actual column in your design or a particular file in your theme.

Is My Theme Wigetized?

Before we go any further, check to see if your theme is already widgetized (the technical term is widget-aware). To do so, simply select the Presentation > Widgets sub-panel of WP-admin. If you see a message like the one below, you have work to do.

Image 1: The Widgets sub-panel of a non-widgetized theme.

On the other hand, if you see something like the figure 2, your theme is already widgetized. For this discussion, I’m going to assume your theme isn’t widgetized but, if it is, don’t go away. Follow along and you’ll learn how to add additional widgeted areas to your theme.

Image 2: The Widgets sub-panel of a widgetized theme.

Creating A Wigetized Sidebar

To create a widgeted sidebar you’ll need a functions.php file. If you don’t have one, create one now and save it in your theme directory. You add a sidebar to your theme by adding code to the functions.php file that “registers” the sidebar (makes WP aware that the sidebar is available if needed). WordPress offers two functions to register sidebars: register_sidebar() and register_sidebars(n) where n is the count parameter or number of sidebars you wish to create.

So you can add one widgeted sidebar by adding the following code to your functions.php file:

<?php

if ( function_exists('register_sidebar') )

    register_sidebar();

?>

Notes: If your theme is already widgetized, you’ll want to edit or replace the existing register_sidebar() or register_sidebars() call rather than inserting a new one. Also, the if statement is used to accommodate older versions of WordPress where the register_sidebar function is not present. In those cases, the call to register_sidebar will simply be ignored.

You can add two widgeted sidebars with:

<?php

if ( function_exists('register_sidebars') )

    register_sidebars(2);

?>

Or even seven, as in the Blogging Experiment theme:

<?php

if ( function_exists('register_sidebars') )

    register_sidebars(7);

?>

Now when you view the Widgets sub-panel you’ll see something similar to Image 2 above depending upon how many sidebars you added. You’ll also notice that your sidebars are named Sidebar 1, Sidebar 2 etc. I’ll give you a tip for giving them more descriptive labels later.

Note: If you create more sidebars than you need the unused sidebars will simply be ignored.

Inserting A Sidebar Into Your Theme

Of course your sidebars don’t do anything until you insert them into your theme (remember you can place your widgeted sidebars anywhere in your theme not just in the left or right columns or the sidebar.php file). In the Blogging Experiment theme, we use seven sidebars: One in the actual sidebar.php file (which appears in the right column), three at the top of the page (they’re in the header2.php file which we insert into the theme as an include in the manner described last week) and three more at the bottom of the page.

Here’s sample code that actually inserts a sidebar into your theme.

<ul id="sidebar-right">

<?php if ( !function_exists('dynamic_sidebar')

     || !dynamic_sidebar() ) : ?>

                <li><h2>Categories</h2></li>

        <?php wp_list_categories(); ?>

    <?php endif; ?>

</ul>

Some things to notice:

1. The sidebar is inserted INSIDE an unordered list.
   • Since most widgets output in list format, this is the format you’ll normally use.
   • The list is given a unique id (in this case sidebar-right) that can be used when specifying styles unique to this sidebar. A style class could also be assigned if you intend to create a style that can be applied to multiple sidebars.
2. The sidebar is called with the function dynamic_sidebar(). The example above includes the parameter 2 so Sidebar 2 is called. If no parameter is specified, Sidebar 1 is used.
3. Without getting all technical, the if statement is designed to test if the sidebar you specify has been created AND if one or more widgets has been assigned to it. If either of those steps hasn’t occurred the default code is inserted into your page. In this case, the default code inserts a list of post categories. You can of course insert your own code but remember it’s ignored if the sidebar exists and a widget has been assigned to it.

Installing Widgets

There are a number of widgets such as Recent Posts and Recent Comments built into WP but most of the more interesting widgets such as the Most Commented Posts Widget will have to be downloaded and installed before you use them. Usually it’s just a matter of uploading the widget file(s) to your WP plugins directory and activating the widget in the Plugins panel of WP-admin. For more information, read the installation instructions for your plugin and check out the WP Codex.

Assigning Widgets To Sidebars

In the Presentation > Widgets sub-panel, you can assign one or more widgets to a sidebar by simply dragging the widget from the Available Widgets box to the appropriate sidebar box (image 3). Once the widget has been placed in a sidebar box it can be configured (if it includes configurable options) by clicking on configuration icon that appears on the right side the widget box. As usual, I recommend checking out the codex (http://codex.wordpress.org/Widgets_SubPanel) for more information.

Image 3: Dragging and dropping a widget into a sidebar.

And Now For That Tip I Promised

One of the annoying things about the Blogging Experiment theme is that, with seven sidebars, it’s hard to keep track of which sidebar is which when you’re assigning widgets. In the course of researching this article, I came across a simple way to name the sidebars.

It turns out the register_sidebar function can accept a number of optional parameters. I won’t go into detail here but you can learn more about them at Automatic.com. For our purposes we only need to know that one of the parameters allows us to name our sidebar like so:

<?php

if ( function_exists('register_sidebar') ){

    register_sidebar(Array("name" => "right sidebar"));

}

?>

If we have only one sidebar, that’s not such a big deal, but if we have seven (as we do here) we can create and name more than one sidebar at a time:

<?php

if ( function_exists('register_sidebar') ){

register_sidebar(Array("name" => "right sidebar"));

register_sidebar(Array("name" => "top left"));

register_sidebar(Array("name" => "top middle"));

register_sidebar(Array("name" => "top right"));

    register_sidebar(Array("name" => "bottom left"));

    register_sidebar(Array("name" => "bottom middle"));

    register_sidebar(Array("name" => "bottom right"));

}

?>

The sidebars are still numbered (in the order they are created) as before but now, in the Presentation > Widgets sub-panel the assigned name will be used to identify the sidebar. So Sidebar 1 will now be identified as “right sidebar”, Sidebar 2 will be “top left”, and so on.

Image 4: The Widgets sub-panel with the sidebars identified by name.

Important note: When you place a sidebar in your theme using the dynamic_sidebar function, you can use either the name or number as the parameter so that dynamic_sidebar(2) and dynamic_sidebar(‘top left’) are equivalent. However it’s still best to place sidebars using the number. That way if you switch to a new theme the widgets you have assigned to your sidebars will stay in place as long as the new theme has corresponding sidebars (even if they are named differently).

TAGS: WordPress Plugins