Enabling sidebar widgets for your WordPress theme

So, you’ve got that brand-spanking-new (or kind-of-new) WordPress theme, and you’re strutting your stuff like it’s no one’s business. What next? Well, with WordPress 2.2 being released yesterday, major changes come along with it. One of the most important changes to take place involve sidebar widgets; these were once provided as a plugin, but are now built right into the application.

In this post, I am going to walk you through on what you need to know to ‘widgetize’ your blog’s theme, meaning we first have to allow your blog’s theme to use widgets. If you haven’t yet installed WordPress 2.2, then don’t worry, because you can install sidebar widgets as a separate plugin and still follow along.

Okay, now that you’ve got WordPress widgets installed, we first have to widgetize your theme.

First thing first, open up your theme’s sidebar.php file. You can find out where this file is located by clicking on the ‘Themes’ tab and checking where it says “All of this theme’s files are located in wp-content/themes/default.” The sidebar.php file will be located in this directory when you login to your website via FTP.

Secondly, look for the very first <ul (yes, it’s purposely missing the closing >). This may look like <ul>, or <ul id=”sidebar”>, or something similar. Immediately after this line of code, place

<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>

It should end up looking something like this:

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

Then, find </ul> and immediately before that, place

<?php endif; ?>

Once you’ve done that, the final step is to create a functions.php file in the same directory as where your sidebar.php file is located; the file’s contents should be:

<?php
if ( function_exists('register_sidebar') )
register_sidebar();
?>

If you have more than one sidebar, then use the following in functions.php instead, where ‘2’ is the number of sidebars you have (change this to how many you actually have):

<?php
if ( function_exists('register_sidebars') )
register_sidebars(2);
?>

That’s it! You should now be able to drag and drop widgets from the bottom of the Widgets tab to your sidebar. Keep in mind that if you use even a single widget from the available widgets, then your sidebar as you know it will be replaced with a new sidebar showing the widgets that you’ve placed.

Let me know if you’ve found this useful, or if you have any questions that you’d like answered! If you’d like a more comprehensive guide on how to widgetize your theme, then visit the official tutorial. If you’d like to continue on modifying your widgets, then take a look at Nathan’s tutorial, entitled “Styling Those Widgets“.

Gary King is a professional freelance web developer, primarily using Ruby on Rails and PHP to create cool new websites. When he’s not trying to take over the world one blog at a time, you can find him mulling over his thoughts at King Gary.