Now that we have a theme that displays posts on the front page, it’s time to add some meaningful content in the sidebar. WordPress allows users to decide what to have in the sidebar using widgets. Using a GUI in WordPress admin users can place, remove and rearrange elements without the need of editing any theme files.

In this lesson we will define a widget area – a place where the user can arrange widgets. To do so we need to write some code in our sidebar.php, but also tell WordPress that our theme support widgets by creating the functions.php and adding some code. The functions.php is a file we will revisit frequently during this tutorial since it’s here we store our PHP functions and WordPress configurations.

According to the tutorial’s design, we want to have a search field and share buttons below it, and the site’s menu on top of the sidebar, without allowing the user to remove or rearrange these elements. In other words we hard-code these elements in our sidebar.php and add the widget area right below.

I’ll show the sidebar.php with the hard-coded elements first, before we go on to defining the widget area:

sidebar.php:

<div id="sidebar-wrapper">
	<div id="sidebar">	

		<!-- search and share -->
		<div class="sidebar-box">
			<div id="search-wrapper">
				<form method="get" action="<?php bloginfo('url'); ?>/">
					<input type="text" value="Search..." name="s" id="search" onfocus="if(this.value=='Search...')this.value=''" onblur="if(this.value=='')this.value='Search...'" />
					<input type="submit" id="search-submit" class="button" name="submit" value="" title="Search" />
				</form>
			</div>
			<div id="share">
				<a href="<?php bloginfo('rss2_url'); ?>" title="Subscribe to RSS feed"><img src="<?php bloginfo('stylesheet_directory'); ?>/images/share-rss.png" /></a>
				<a href="..." title="Share this on Facebook"><img src="<?php bloginfo('stylesheet_directory'); ?>/images/share-fb.png" /></a>
				<a href="..." title="Share this on Twitter"><img src="<?php bloginfo('stylesheet_directory'); ?>/images/share-twitter.png" /></a>
				<a href="..." title="Share this on e-mail"><img src="<?php bloginfo('stylesheet_directory'); ?>/images/share-mail.png" /></a>
			</div>
		</div>
		
		<!-- Menu (pages) -->
		<div class="sidebar-box">
			<h2 class="widgettitle">Menu</h2>
			<ul class="sidebar-menu">
				<?php wp_list_pages('title_li=&depth=-1');?>
			</ul>
			<div style="clear:both;"></div>
		</div>

		<!-- widgetized area -->

		<!-- end widgetized area -->
	</div>
</div>

Basically the sidebar is split into three parts. The first part is the hard-coded sidebar-box for our search field and share buttons. I have added the RSS feed url, but as for the three others (Facebook, Twitter and Mail) you need to provide the url’s yourself. Just replace the “…” with the corresponding URLs.

The second part is our hard-coded menu, which for now is a list of all published pages in your WordPress implementation. It’s been a common practice in WordPress using pages as the site’s menu, but in version 3.0 WordPress introduced a custom menu system. In lesson 9 we will replace the pages with support for a custom menu. The WordPress function call wp_list_pages() returns all published pages in <li> form. WordPress will automatically give the <li> elements a class called page_item, which we can target with CSS for styling the menu slightly different than the other lists that may appear in the sidebar. If you prefer, you could manually write the list yourself instead of using pages, but that’s only recommended if you are to use the theme for yourself only.

The third part is where our widget area will be, and that’s what we’ll get to now.

WordPress Function Reference:

• bloginfo
• wp_list_pages

Defining a Widget Area

Now that we have completed the hard-coded parts of our sidebar, we add the third and final part. The widget area is to appear after the two hard-coded parts (marked with comments in the above code):

sidebar.php:

		<!-- widgetized area -->
		<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar()) : else : ?>
						
		<div class="sidebar-box">
			<h2 class="widgettitle">Categories</h2>
			<ul>
				<?php wp_list_categories('sort_column=name&optioncount=0&hierarchical=0&title_li='); ?>
			</ul>
		</div>

		<div class="sidebar-box">
			<h2 class="widgettitle">Blogroll</h2>
			<ul>
				<?php wp_list_bookmarks('title_li=&categorize=0&category=2&before=<li>&after=</li>&show_images=0&show_description=0&orderby=name'); ?>
			</ul>
		</div>
						
		<?php endif; ?>
		<!-- end widgetized area -->

The test if (function_exists('dynamic_sidebar') && dynamic_sidebar()) : else : and the closing endif are the actual definintion of a widget area. That’s really all we need. All of the code inbetween are the alternative; what WordPress should display if the user hasn’t added any widgets. You could skip adding anything, which will result in an empty sidebar if there are no widgets placed. I’ve chosen to display the most common sidebar elements, categories and blogroll.

The first part of the if-check, allows for backwards-compability for older versions of WordPress which don’t support widgets. The last part in the if-test, dynamic_sidebar(), is a WordPress functions that prints out whatever widgets the user has placed. If dynamic_sidebar() returns false, meaning the user has not placed any widgets in WordPress admin, it will go to the else, and print out anything between the else and the endif. Whenever a widget is placed in the sidebar, all the output after the else until endif is ignored.

If you navigate to WordPress admin » Appearance » Widgets, WordPress tells us that our theme doesn’t support widgets. That’s because we lack a line of code in our functions.php. In fact, we haven’t even added that file in our theme yet. Let’s take care of that.

WordPress Function Reference:

• dynamic_sidebar
• wp_list_categories
• wp_list_bookmarks

Creating functions.php and Adding Widget Support

Create a new empty file in your theme folder, named functions.php. Open it, add a opening PHP statement and a single line of code telling WordPress that our theme supports widgets:

functions.php:

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

What the line of code does is first allowing for backwards-compability with older versions of WordPress which don’t support widgets, and then calling the WordPress function register_sidebar(), which defines a widget area in WordPress and provides it an ID.

When you’ve saved functions.php with that line, the theme now support widgets. Navigate back to Widgets in WordPress admin and notice that you can drag widgets into a widget area on the right. You can add as many widgets as you can and want to, as well as reorganize them by dragging them up or down. Try removing all widgets completely to trigger the content in our sidebar (categories and blogroll), and then add a widget to see that it replaces the else part.

WordPress Function Reference:

• register_sidebar

A tip to the functions.php file: The content of functions.php will mostly be PHP so I always start the file with a <?php and leave out the closing ?>. This is because WordPress gets cranky if there are any white space or empty lines after the closing PHP statement – giving a warning every time the theme is activated. The theme will work just fine, but the warning is annoying. You are obviously allowed to closing and reopening PHP statements in the middle of the file, though.

This concludes Lesson 4 of the WordPress Theme Tutorial. Go to the next lesson, Creating WordPress Templates, or back to the tutorial’s Table of Contents.