Add Widgets to Your Wordpress Theme: How-to

Adding widgets to your own WordPress theme is incredibly straightforward, and involves only a few simple steps.

In this article I’ll explain exactly how you can go about adding easily-customizable content to your WordPress themes.

Step 1:  Create or Edit functions.php

If your theme already contains a functions.php file, you may find inside it the following:

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

If you don’t have the file, or the code, don’t worry! Simply create a functions.php file in your theme directory. We’re going to use code that is more useful than the default, so replace (or add) the code above with the following:

<?php

if ( function_exists('register_sidebar') )

register_sidebar(array('name'=>'widget1',

'before_widget' => '',

'after_widget' => '',

'before_title' => '',

'after_title' => '',

));

?>

Whatever you choose to name the widget (in this case, I am using ‘widget1′) will be the name WordPress will display in the Appearance->Widgets tab.

For each widget you want to add to your theme, simply include another call to the register_sidebar function:

<?php

if ( function_exists('register_sidebar') )

register_sidebar(array('name'=>'Welcome Message',

'before_widget' => '',

'after_widget' => '',

'before_title' => '<h1>',

'after_title' => '</h1>',

));

register_sidebar(array('name'=>'Top Ten Articles',

'before_widget' => '',

'after_widget' => '',

'before_title' => '<h4 class="top-ten">',

'after_title' => '</h4>',

));

register_sidebar(array('name'=>'Reviews',

'before_widget' => '<div id="reviews">',

'after_widget' => '</div>',

'before_title' => '',

'after_title' => '',

));
?>

The additional parameters are fairly straightforward to understand. For my ‘Reviews’ widget, I want to place everything inside a div, so I use the ‘before_widget’ and ‘after_widget’ parameters to add the code I want to appear before and after.

Similarly, I want the titles of the ‘Top Ten Articles’ and ‘Welcome Message’ widgets to be inside h1 and h4 tags, respectively. I do this by adding the appropriate code to the ‘before_title’ and ‘after_title’ parameters.

Step 2: Add Your Widgets to Your Pages

I want to add the ‘Top Ten Articles’ widget to my theme’s sidebar, so I open sidebar.php and add the following where I want the widget to be displayed:

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

<?php endif; ?>

Now I can go to the Appearance->Widgets tab to drag and drop content into my new ‘Top Ten Articles’ widget. It’s as simple as that.

Step 3: Advanced Widgetry

Although I’m using the ‘register sidebar’ and ‘dynamic_sidebar’ functions, I’m not restricted to placing widgets in my sidebar. Anywhere I want a widget, I can have one with exactly the same method, and make life easier for the end users of my themes at the same time.

If I want to jazz up my WordPress theme with a welcome message on the homepage, I can use widgets to achieve this. A standard theme I might distribute could have the following code in either index.php or page.php:

<?php

if( is_home() || is_home_page() ){ ?>

    <div id="welcome">

       <h1>Welcome to My Site!</h1>

       <p>Xyclopsoft.com is a great resource for WordPress themes,
                   custom code, and all kinds of software for small to
                   medium enterprise companies.</p>

    </div>

<?php

} //end homepage welcome message

?>

That message works fine for demonstration purposes, but it’s frankly lame and of course everyone will want to change it. I wouldn’t expect everyone to want to go through my code to find the bit of text they need to change – that’s not user-friendly at all. It would be much better to allow the user to change the message by typing their own welcome message into a widget text box.

Let’s complicate things a little more: I also want to be sure that the demo welcome message is displayed if the widget hasn’t been set up yet – someone might see my site name and come check me out (new clients are always welcome, right?)

I can use a widget to make this really, really easy for everyone concerned, by changing the welcome message code to this:

<?php

if( is_home() || is_home_page() ){ ?>

    <div id="welcome">

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

            <h1>Welcome to My Site!</h1>

            <p>My site is a great resource for WordPress themes,
                        custom code, and all kinds of software for
                        small to medium enterprise companies.</p>

      <?php endif; ?>

    </div>

<?php

} //end homepage welcome message

?>

The code between the if / endif tags will only be executed if the ‘Welcome Message’ widget has not been set up. Additionally, all the user has to do is drag a text widget into the ‘Welcome Message’ widget container, and their own title and message will be displayed.

Lastly, because I set the ‘before_title’ and ‘after_title’ parameters, the custom title will be formatted in the correct way.

That’s all there is to adding widgets to your custom WordPress theme.

Useful Links:

• WordPress Widget Plugins – Find more widgets for your blogs
• WordPress Codex – An invaluable reference for WordPress developers
• WordPress on Wikipedia
• Layout Garden – Blog design best practices