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.

Comments

  1. says

    Thanks for the tips. I’ll wait a few days until the smoke clears and then I’ll update my blogs. Looks like yet another good update, one that makes life easier for us bloggers.

  2. says

    Great stuff Gary :) I think I will wait till I do a redesign or new blog though, not sure widgets will add anything for me at this point?

  3. says

    Chris, I personally don’t use widgets on my own blog because I modify it so often that I would prefer modifying the actual source code itself. For most people, though, I can understand that modifying HTML can be tricky and so that’s the primary reason as to why widgets were introduced.

  4. says

    I tried making my theme widgets aware and did what you suggest here. Is there a way to have the current Items on my sidebar listed under Presentation > Widgets?

    Currently my Sidebar 1 shows the following message

    “Your theme will display its usual sidebar when this box is empty. Dragging widgets into this box will replace the usual sidebar with your customized sidebar.”

    Or is it suppose to display the message?

    I tried this http://automattic.com/code/widgets/themes/ but to now avail.

    Any suggestion?

Trackbacks