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:

1
<?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:

1
2
3
4
<?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:

1
2
3
4
5
6
7
<?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:

1
2
<?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:

1
2
3
4
5
6
7
8
<?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:

1
2
3
4
5
6
7
8
9
10
<?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:


Next:

Previous: