Widgetise Your Theme

If you want to use widgets in your WordPress theme, or you’re a theme developer and want to make your theme ‘widget ready’, then all it takes is a couple of steps to add the necessary code in and your theme is good to go.

The Function

First we need to register the sidebar in our functions.php file (if you don’t have a functions.php file, create one). At the simplest form this is

if ( function_exists('register_sidebar') ) {
    register_sidebar();
}

This will set your widgets up in an unordered list with the widget title in a h2 and the content in an unordered list eg.

<ul>
    <li><h2>Widget Title</h2>
        <ul>
            <li>Widget Item here</li>
            <li>Another Item</li>
        </ul>
    </li>
    <li><h2>Widget Title 2</h2>
        <ul>
            <li>Widget Item here</li>
            <li>Another Item</li>
        </ul>
    </li>
</ul>

Of course, this markup isn’t to everyone’s liking. Personally I prefer to use h3’s instead of h2 headings. So to do this we can override the default settings using the following code:

if (function_exists('register_sidebar')) {
    register_sidebar(array(
        'before_widget' => '<li>',
        'after_widget' => '</li>',
        'before_title' => '<h3>',
        'after_title' => '</h3>',
    ));
}

If you want to be able to target the widget’s output even more then we can add an ID and class to the widget using the following code:

if (function_exists('register_sidebar')) {
    register_sidebar(array(
        'before_widget' => '<li id="%1$s" class="widget %2$s">',
        'after_widget' => '</li>',
        'before_title' => '<h3>',
        'after_title' => '</h3>',
    ));
}

The ID is generated from the widget’s name and the class is generated from the widget’s callback.

So now we’ve got our sidebar set up in the functions file you can add widgets via the Appearance -> Widgets menu. Now we need to get them showing on the front end.

The Sidebar

The code required for the sidebar is a simple if statement that checks if we’ve registered a sidebar. If we have then it will show that, otherwise it will display what’s within the if statement. This is achieved using the following code:

if (!function_exists('dynamic_sidebar') || !dynamic_sidebar()) :

This simply says ‘if the function dynamic_sidebar() doesn’t exist, or there’s no output from the function dynamic_sidebar() display the following’. Within the if statement you place the code that you want to display if the user doesn’t add any widgets to their sidebar (even if you’ve got the functions file and sidebar set up, if no widgets are added then no output is made and so the if condition becomes true and the code within it will display.

So this gives us the final code of

if (!function_exists('dynamic_sidebar') || !dynamic_sidebar()) :
    // enter HTML code here for items such as list categories, pages, recent posts etc.
endif;

Conclusion

This is a simple addition but with widgets becoming quite popular, it’s a good idea to add the code in to make your theme even more flexible.

Written by Sarah from Stuff By Sarah
Posted on May 7th, 2009 and filed under WordPress Coding & Design
Do not forget to subscribe to our RSS feed for updates

8