In Part 1 of our Creating a Basic WordPress Theme series we kicked off our custom theme by creating a header, footer and style sheet. These three files make up one part of a barebones theme and offer some of the structure that's needed for bringing the whole theme together.

It's now time to get down to working with some Template Tags and getting the theme actually working. In this post we'll start by creating basic functions.php and sidebar.php files to make our theme widget ready. We'll also create an index.php file that invokes the WordPress loop and starts displaying our posts.

By the end of this post we'll have a working WordPress theme! It won't have any styling and it will lack some things like comments and a developed sidebar but it WILL be working.

Using functions.php to Activate Widgets in a WordPress Theme

For full documentation on "widgetizing" a theme there's no better place to start than the Official Documentation for Widgetizing Themes. The documentation provided by Automatic is definitely helpful but it's not terribly accessible for new designers.

In this section I'll attempt to bridge the gap a bit - please use the comment form below to ask any questions.

For a theme to have widgets you basically need two code snippets. One appears in your functions.php file the other in your sidebar.php file. The makeup of this code is really dependent on whether or not you utilize one of two types of sidebars.

Personally I prefer to avoid making a sidebar that consists of too many nested lists - so for the purposes of this post I'll be using the second method of widgetizing themes.

To get things rolling we'll look at the code supplied by Automatic, with a few tweaks, for a non-list formatted sidebar:
<?php
if ( function_exists('register_sidebar') )
register_sidebar(array(
'before_widget' => '<div class="widget">',
'after_widget' => '</div>',
'before_title' => '<h4>',
'after_title' => '</h4>',
));
?>

This code defines the rules that will cover all the WordPress widgets that display on your site. If you're not familiar with PHP it might seem a little bit intimidating. Basically the piece of code above offers four variables for formatting your widget. The first pair (before_widget and after_widget) basically make up tags that surround each individual widget. The second pair of variables (before_title and after_title) make up the tags that will surround each widget's title.

The code above results in the following HTML output:

<div class="widget">
<h4>First Widget</h4>
<!-- Widget Content -->
</div>
<div class="widget">
<h4>Second Widget</h4>
<!-- Second Widget's Content -->
</div>

For now this is all the code you really need in your functions.php file.

Note: Make sure that the first line and last line of your functions.php template contains no extra spaces. The absolute first characters in functions.php should be '<?php' the absolute last characters should be '?>'.

Creating a Dynamic Sidebar

We're basically going to add two things to our sidebar. First we want to finish widgetizing the theme then we're going to add a quick category listing.

After we get the widget code and category listing in place we're going to add a little extra HTML too - you'll see why in Part 3.

Adding Widgets to your Sidebar

We've already got the code in our functions.php file now we have to activate it in our sidebar. To do this we'll just add the following code:

<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
<?php endif; ?>

This particular piece of code is a basic type of PHP conditional phrase. What it basically does is designate the spot in which your widgets should appear.

It's important to note that this code is more powerful than just a flag for where to display a widget but it's functionality is something we can explore more elsewhere.

For now we just need it's basic function ... displaying widgets.

Adding a Category Listing to sidebar.php

OK at this point I want to get into something a bit more fundamental. Part of the ease of coding a WordPress theme comes from the extensive Template Tag library that the developers have put into place. The code above required two lines to activate but we can also get a lot done in just a single line. In this case we're going to list all of our theme's categories with just a little bit of code.

The basic Template Tag for listing categories is wp_list_categories (great name right?) Like most Template Tags it's got a lot of potential for getting things done inside a template but we're just interested in it's basic role.

For now we'll just add the following:
<ul><?php wp_list_categories(); ?></ul>
This will display an unordered list of all the categories currently active in our blog. One thing mising from the wp_list_categories() output is the <ul></ul> brackets needed to enclose it - that's why we've added them.

Note: If a category has fewer than 1 post it won't be displayed.

wp_list_categories has plenty of options to it but for now we're just going to settle with this default display.

At this point our basic sidebar is complete. Before we move onto our index.php file though I want to take a second to lay the groundwork for something we'll be doing in our next post. In this next section we'll create an portion of our theme that can be easily identified and styled using CSS.

Preparing the Sidebar for CSS Styling

While the sidebar.php file holds our sidebar's code we still need something to identify the sidebar for both HTML and CSS purposes. When it comes time to align the sidebar and add some basic styling we'll need to access it specifically - we do this by creating an id selector that belongs solely to our sidebar.

Our sidebar, like our header and footer will be, is a basic division of our theme so we're going to use the <div> tag to identify it. Next we want to a CSS selector - we do this with id.

For now we'll define the <div> tag that encloses our sidebar with the id "sidebar," because we're only making one sidebar.

Our complete sidebar should now look like this:
<div id="sidebar">
<ul><?php wp_list_categories(); ?></ul>
<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
<?php endif; ?>
</div>

Creating our index.php File

The last thing we'll need to do to get our basic WordPress Theme together involves the index.php file - the heart of the main theme.

To get started we're really going to dive deep into WordPress' heart and grab a basic version of the WordPress Loop. The WordPress Loop is really the force behind WordPress blogs. This little piece of code displays all the content that's stored in your WordPress Database and helps serve everything from index pages to single posts to categories and archives. If a post appears on a page the WordPress Loop is what's making it happen.

Again we're sticking to basic right now. To get started we'll only aim to display the post and it's title (with a permalink to the post) - later we'll add all the details like date published, category and author.

The WordPress Loop in Action

The basic WordPress Loop can be executed in three lines of code:

<?php if(have_posts()) : while (have_posts()) : the_post(); ?>
<?php endwhile; ?>
<?php endif; ?>

Translating this into plain English is a bit tough so we'll have to walk through it a bit. Basically the code asks the WordPress engine if there are posts to display that meet a certain criteria. If there are it tells the engine to execute some code until there are no more posts meeting the named criteria. Next it does one last thing (whatever appears between endwhile and endif) and then the loop ends.

The criteria that the loop runs under is actually hidden in the WordPress Database and is based off of the URL where the code is executed. If a URL specifies a single post the loop will only run once retrieving that post. If it specifies a category it will run a few times (based on the options set in your administration panel) and display posts in that category.

What we've added above doesn't do much yet - it just starts up the loop, runs a few times and shuts down. We'll need to add some rules about what to display. That means a few more WordPress Template Tags.

Having WordPress Display Post Titles and Content

Right now we've got the WordPress Loop running but it's basically just spinning it's wheels. We need to add some Template Tags to get things working. Because we're staying basic we're just going to shoot for getting WordPress to display the Post Titles and Post Content.

To do that we'll need two template tags: the_title() and the_content. We'll also use some basic HTML to make things stand out. Rewrite your loop to match the one below.

<?php if(have_posts()) : while (have_posts()) : the_post(); ?>
<?php the_title(); ?>
<?php the_content(); ?>
<?php endwhile; ?>
<?php endif; ?>

the_content is a WordPress Tag that requires the loop to execute. the_title is a bit more forgiving as we'll learn later. The code above now tells WordPress specifically what to do when there are posts to display - namely it says display the post's title and content.

Next we'll add the code to make the post title link back to the post.

Linking from the Post Title to the Post

To accomplish this we'll again need to use a little PHP and a little HTML. To start we'll create a basic HTML link around the_title - we'll also add some <h1> tags to make the title standout.

<h1><a href="" title=""><?php the_title(); ?></a></h1>

We know how to call the post's title so we can add that to the title attribute. Next we need to recover the post's permalink. Again we get to see how intuitive a lot of WordPress's Template Tags are.

  • the_title() returns the post's title
  • the_content() returns the post's content
  • the_permalink() returns the permalink for the post

Our final code for linking to the post looks like this:

<h1><a href="<?php the_permalink(); ?>" title="<?php the_title(); ?>"><?php the_title(); ?></a></h1>

OK - homestretch

At this point we've got the post displaying properly and we have a sidebar that provides some typical sidebar content - the problem is that we're still lacking the structure needed to pull our header, sidebar and footer together as part of our blog.

To finalize our index.php file we use three more Template Tags to get our header, sidebar and footer.

Here's our final index.php file:
<?php get_header(); ?>
<?php if(have_posts()) : while (have_posts()) : the_post(); ?>
<h1><a href="<?php the_permalink(); ?>" title="<?php the_title(); ?>"><?php the_title(); ?></a></h1>
<?php the_content(); ?>
<?php endwhile; ?>
<?php endif; ?>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

Can you tell what that new code does?

Just a quick note on the order I use here.

As a rule your theme should follow a certain hierarchy. Important information should always appear first. Since our posts are more important than our sidebar they go before it in the order. Obviously that places the footer last. The header (which will get fleshed out later) has to appear first so it gets first appearance in the document.

One thing we'll encounter later involves placement of the sidebar. CSS actually makes it difficult to float something as large as the sidebar to the left of content - this often leads new designers to place it before the main content in the themes structure. There are workarounds that can fix this problem though so make sure you keep that sidebar where it belongs - AFTER the content.

Congratulations!!!

If you've been following along you should now have six fully functional WordPress files. If you've already got the files on your server head over to the Presentation tab in the WordPress admin panel and load up your new theme. Click on "view site" and you should see a very basic theme staring back at you. You can see the HTML readout of what my sandbox produced here.

Well Done!

Obviously our theme right now is a bit plain - it really doesn't look unique so our next goal is to start working with our style sheet. In the next part of this series we'll work towards setting the groundwork for styling. Immediately after that we'll start making our theme look a bit more professional.