All You Need to Know About Making Widget Areas in WordPress Themes

Some of the best features of WordPress are the ways in which any user, once he or she learned the WordPress interface, can quickly change complex site features. Sidebar widgets are a great example — and one which is increasingly used and useful across many other areas of a WordPress site besides the sidebar. With a little dragging-and-dropping, you can quickly and easily change the appearance of your site.

We’ll explain the process of making widget areas appear in your theme.

Today we’re not going to talk about where and how a user can fiddle with widgets, nor how to make them for yourself (we did cover that one before, with the basics and a guide to user-editable ones). Nope: here we’ll explain the process of making widget areas — areas into which your end-user can place and manipulate widgets — appear in your theme.

Nicely, making widget areas is not too complex a project. If making widgets scared you, this should not. We’ll need to do just two things:

  1. Create the widget-ized area, and
  2. Make that area show up on our theme.

A Quick Note on Terminology: “Sidebar” vs. “Widget Area”

The term “sidebar” often gets used to mean “widget area,” even though not all widget areas are actually in sidebars.

Before we get too deep, you should know the difference between a “widget area” and a “sidebar.”

A sidebar is a type of widget area: a widget area that shows up in a site’s sidebar. Not all widget areas are in sidebars (they can be in the header, the footer, the main post body, or anywhere), but because widget areas started out as sidebars in WordPress’s history, the term “sidebar” gets used to mean “widget area” an awful lot.

It’s a little weird that all widget areas are often called “sidebars” in WordPress. (Just as it’s weird that all “custom post” or content types are called “posts”.) But I think there’s some charm in the oddities of WordPress’s naming. After all, one of the best things about WordPress from a user’s perspective is that it’ll just keep working, and these naming weirdnesses developers see are just a direct result of that commitment to backwards compatibility.

Making Widget Areas In Your Theme

So the first half of our task: telling WordPress we want to have one (or many) widget areas. It’s really pretty simple, and consists of putting lines like these into your theme’s functions.php file:

$args = array(
    'name'          => __( 'Widgetized Sidebar' ),
    'id'            => "widgetized-sidebar",
    'description'   => 'Our Widgetized Sidebar',
    'class'         => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget'  => "</li>\n",
    'before_title'  => '<h2 class="widgettitle">',
    'after_title'   => "</h2>",
);
register_sidebar( $args );

Now, if you’ve done much WordPress programming you may notice this pattern: we pass an array of options to a function, and the function works its magic. And the first thing to know is that in this case — as is usually true in WordPress — you don’t actually need to have any arguments for the function. Simply calling register_sidebar() works, and will create a sidebar for you.

You will probably want to, at a minimum, include the id, because it makes is so much easier for you to actually find and display your sidebar; and the name and description are a good thing to include because it shows in the user interface. But if you don’t know why you’d need to use any of the others, you’ll be fine not including them in your array.

For those wondering about those others, they’re pretty simple: class refers to a CSS class that the widget area will take on — but only in the admin area, not on your actual site. before_widget and after_widget are the markup you want WordPress to wrap all widgets within this widget area with, and before_title and after_title fulfill the same role for wrapping each widget’s specific title.

If you’ve been around WordPress much, you probably also understand that you should wrap your registration in an action filter. Like so:

add_action( 'widgets_init', 'theme_slug_widgets_init' );
function theme_slug_widgets_init() {
    register_sidebar( array(
        'name' => __( 'Main Sidebar', 'theme-slug' ),
        'id' => 'sidebar-1',
        'description' => __( 'Widgets in this area will be shown on all posts and pages.', 'theme-slug' ),
        'before_title' => '<h1>',
        'after_title' => '</h1>',
    ) );
}

I include this example because it shows off two things you should understand how to do: use action hooks (I explained the basics of WordPress’s hook system here), and passing an array into a function without first assigning it. Functionally, there’s no difference between creating an $args variable and passing it into the function, and creating the array right inside the functions. The difference between the two is mostly down to style and readability preferences. But you will see both and should be familiar with their similarity.

A Brief Note on register_sidebars()

There’s another function you should probably be aware of: register_sidebars(), note the final “s”. The reason I think you should know of it is that it exists. That said, because it’s automatically generating your sidebars with the not-very-useful names of “Sidebar 1”, “Sidebar 2” (or similar), I’d argue that you should basically never use it.

Something like a foreach through an array of $args arrays with all your relevant values will take you just a few more keystrokes to do but will allow your widget area’s naming to be much simpler to comprehend for both users and fellow developers.

How To Use The Widget Areas You’ve Registered

One of the nice things is how brain-dead the basic code to display your widget area (or “sidebar”) is once it’s registered. Here’s the code that does it in the sidebar.php from a default theme (Twenty Twelve):

<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?>
    <div id="secondary" class="widget-area" role="complementary">
        <?php dynamic_sidebar( 'sidebar-1' ); ?>
    </div><!-- #secondary -->
<?php endif; ?>

The names of the functions involved could be better — even after understanding it, it’s weird to see a footer that contains three calls to dynamic_sidebar() — but the basic thing is pretty simple. Essentially, the actual display of a widget area is just accomplished with that dynamic_sidebar( 'sidebar-id' ). The sidebar ID should, as you’ve probably guessed, match the ID that you’ve passed in the register_sidebar() function for the particular sidebar.

The actual function of is_active_sidebar() is much closer to “sidebar currently contains at least one widget?”

The outer if condition here is also interesting. You don’t, strictly speaking, need the if (is_active_sidebar( 'sidebar-id' )). The reasons that it’s here is that the maker of this theme didn’t want their <div> showing up on the page if it would be empty. If you don’t mind the unnecessary markup showing up on your page, it’s safe to omit it — trying to show an empty widget area doesn’t make WordPress break or anything.

And here again I’ve got to bring up a confusing name: the actual function of is_active_sidebar is much closer to “sidebar currently contains at least one widget?”. But we’re using what we’ve got, so is_active_sidebar is how you check if a widget area is not empty. Just remember that, and try to ignore anything else that the name makes you think it might possibly be doing.

Widget Areas: Now You Know

I hope you now understand what a widget area is in WordPress, the process of making widget areas, and how to make them show up in your theme. That these widget areas are always referred to as sidebars in the WordPress functions you’ll be using shouldn’t prevent you from using them anywhere on your site they’ll be helpful. Themes today often contain at least a few widget areas, and with good reasons. In the header, the footer, the front page — wherever — widget areas are still the most WordPress-native way to provide easy customizability to your theme.

Thanks for reading!


2 Responses

Pingbacks