How to design a variable sidebar WordPress theme with widgets (by guest blogger Daria Black)

This post is by a guest blogger.

Daria Black is a freelance writer and web designer. Visit her website Webernet Architect located at for information and tutorials on web design, blogging, social networking and a general guide to having fun on the internet. To learn more about Daria visit her personal weblog at Lexicon Indigo.

When I first heard of WordPress widgets, I was appropriately disgruntled. ‘Widgets? We don’t need no stinking Widgets,’ I grumbled. I was resistant towards the notion of widgetizing my themes because it meant having to change my style of design from using divs to separate the content in my sidebar to placing everything in an unordered list.

But when I saw how they make the end user’s life a little bit easier and how they can make an already powerful content management system even better, I can’t praise the creators of the Widgets plugin enough. So to show you just how creative one can be with the plugin, I’m going to share with you a way to create a template where you can have different widgets on each of your template’s page views; the index, single post and Pages.

This tutorial assumes you have a basic understanding of WordPress themes and prefers that you know a little bit about PHP as well. However, knowing how to follow directions and cut and paste is just as good.

It all starts with having the correct template files

In addition to having your basic index.php file you will also need a page.php, single.php and three sidebar.php files which we will appropriately name sidebar.php, singlesidebar.php and pagesidebar.php.

The way WordPress works is that when a post is called it will display it according to what is available in the template hierarchy. According to the Codex when a page is called, if it is a post, the software will first look for the category specific template file (either category-x.php or category.php), then a single post template file (single.php) and if it can find none of those, then it will use the index.php file as its default. If it is a Page that is being called for, then the software will look for the page.php file before using the index.php as the default. The reason for this is to offer the maximum level of customization available for your WordPress installation.

All templates have an index.php file and most have a sidebar.php file. Some even come with already customized single.php and page.php file. If your template does not come with these additional files and you don’t have the first clue as to how to make them don’t worry, I won’t leave you hanging like that. All you have to do is copy and rename the index.php and sidebar.php files.

Now we need to partner up the sidebars with their appropriate template file. Pair the index.php with the sidebar.php file by adding

<?php  get_sidebar(); ?>

wherever you want it to appear in your template. If you are working off of someone else’s template than that should already be setup for you.

Put the single.php file with the singlesidebar.php file by adding (or overwriting <?php get_sidebar(); ?>) with:

<?php include(TEMPLATEPATH . '/singlesidebar.php'); ?>

This tells WordPress to use the singlesidebar.php file instead of the default sidebar.php file. Do the same with the page.php file and pagesidebar.php except substitute singlesidebar.php with pagesidebar.php.

Stir in the proper Widget technology

The Widgets code uses a file called functions.php to control the number of sidebars you need, their names and their CSS markup. For the Widgets plugin to work properly, at the very minimum, you must register your sidebar(s) using this file.

There are two ways you can go about doing this. The easiest way is to open up the text editor of your choice, add the following code and save the file as functions.php:

<?php

if ( function_exists('register_sidebar') )

register_sidebar(3);?>

This code tells the Widgets plugin that we need some dynamic sidebars, three to be exact. This will display 3 sidebars in the Sidebar Widgets area of your dashboard appropriately named Sidebar-1, Sidebar-2 and Sidebar-3. This is fine and dandy if you’re template is for personal use and you can remember which sidebar goes with which file. However if you are designing for other people or are like me and suffer from CRS (Can’t Remember Stuff) then you may want to think about giving your sidebars unique names. In this case you will need to edit the code slightly to get this desired effect.

<?php

if ( function_exists('register_sidebar') ){

register_sidebar(array('name'=>'ESSidebar'));register_sidebar(array('name'=>'ESSinglepost'));

register_sidebar(array('name'=>'ESPages'));

}

?>

Basically with this code you are registering each sidebar individually with its associated name. It can be any name you want, however you might want to pick something unique to the template. The Widgets plugin has the capability of saving widget schemes on a per template basis but that is only if the sidebar names are unique. Otherwise the information will be overwritten by the new sidebar widget scheme if it has the same name.

In this example, my sidebar names correspond to the template they belong to which is called Experimental Silver. ESSidebar goes to the index.php file, ESSinglepost goes with the single.php file and ESPage goes with the page.php file.

Add a dash of code

As I mentioned before, your sidebar should be set up as an unordered list. This is the default HTML coding for the Widgets plugin. If yours isn’t that’s okay. Just read up at the Automattic website on how to change the functions.php file to account for how your sidebar is designed.

Open up the pagesidebar.php file and add the following code just underneath the < ul > tag:

<?php if ( function_exists('dynamic_sidebar') && dynamic_sidebar(ESPages) ) : elseif ( function_exists('dynamic_sidebar') && dynamic_sidebar(ESSidebar) ): else : ?>

What this is telling WordPress is that if the Widget plugin has been activated and widgets are set for this sidebar (ESPages) then show the dynamic sidebar and its associated widgets otherwise if the Widgets plugin is turned on but there are no widgets for this sidebar then show the default dynamic sidebar setup for the index file (ESSidebar). If widgets are turned off and/or there are no widgets for the page sidebar or the default sidebar then just show the code setup in the pagesidebar.php file.

Be sure to overwrite the sidebar names with the custom names you created in the functions.php file. If you used the default setting then you must use numbers. Remember before when I said that the plugin will automatically name your sidebars Sidebar-1, Sidebar-2 and Sidebar-3 if you didn’t tell it any differently? Well those numbers are what you would use as the dynamic_sidebar designation here. So instead of dynamic_sidebar(ESPages) it would be dynamic_sidebar(1) and so on. Add the same code to your singlesidebar.php file (except update with the singlesidebar name or number).

Since the sidebar.php file is the default file, all you need to add to the file is this:

<?php if ( function_exists('dynamic_sidebar') && dynamic_sidebar(ESSidebar) ) : else : ?>

It just says that if Widgets are enabled and there are widgets for this sidebar then show the dynamic sidebar otherwise show the code in the sidebar.php file.

Just before the ending < /ul > tag add the following code:

<?php endif; ?>

This is necessary to end the PHP statement and prevent errors.

Upload and test

Upload the template files to the appropriate directory and make sure the Widgets plugin is turned on. Set up a few widgets and then navigate around to the different page views. If all goes well then you should see the different widgets on the different page views.
If all doesn’t go well and you are not seeing the desired effect, be sure to go back and check your code. Make sure the names are in the appropriate places, that they are written in your sidebar code exactly as you have them in your functions.php file (yes capitalization matters) and that you actually have widgets set for each of the sidebars. If all else fails, feel free to contact me and I will assist you.

And there you have it. One of the many things you can do with WordPress and widgets. Happy web designing!

You can find more stuff by Daria at Webernet Architect and Lexicon Indigo including her theme Experimental Black.