Dissection of a WordPress theme: Part 4

In previous guides we have concentrated on the building blocks of a WordPress theme. A basic design structure has been defined, followed by enclosing header and footer elements, and finished off with a navigational panel. While important aspects of any blog, they are secondary to its main purpose: the content.

In this fourth and final part we carefully dissect the process of taking content from WordPress and arranging it on screen. Attention is paid to the alternative methods of grouping this information, from the multiple posts of the front page, to search results and archives.

We will look at how WordPress distributes responsibility for this work, and how everything is tied together with the all-seeing all-knowing construct known as ‘The Loop’.

By the end of this guide we should have a fully working theme and enough WordPress experience and knowledge to extend our theme beyond the basic design presented here.

The Loop

The Loop is the front-facing side of WordPress and sits at the top of the code hierarchy. Its basic role is to obtain information about posts that can then be displayed easily and conveniently.

It is called ‘The Loop’ because it is, very simply, a loop – there is no hidden trickery here. Each iteration through The Loop causes WordPress to load the post information, which is then accessed through special template functions. The Codex describes most of these functions in great detail.

The primary loop exists within index.php, but the loop can also be found in several other of the files contained within a theme. We will look at index.php in more detail shortly, but for now the loop can be extracted as a very short piece of PHP code:

while ( have_posts() ) : the_post();

Yes, that really is it. All the underlying database work and the multitude of PHP files all boil down to whatever exists between these two lines. Breaking this down even further we have two WordPress function calls wrapped within a PHP while statement – PHP will execute whatever is between the colon and endwhile, so long as the condition is true.

In the above code, the condition is the first WordPress function:

have_posts ();

This is a simple function call that returns true if we have a post to display, or false if we don’t.

How does WordPress know whether we have a post to display? It deduces this from the URL of the current page. On the front page we may have several posts to display, while a single page will only have one. Regardless of the context, The Loop is fundamentally the same, and WordPress will stop the loop at the correct time by causing have_posts to return false when there are no more posts. Execution then resumes after the endwhile.

The second essential part of The Loop is:

the_post ();

You can think of this as being the function that tells WordPress to load the information for the next post and prepare it for our use. Each subsequent call of the_post will cause WordPress to give us the next post, and the next, and so on – it is basically a pointer that steps through the posts.

For example, if we have ten posts to display then have_posts will be called 11 times – the first ten will return true and the eleventh will return false. Each time it returns true, the_post will be called to get the information about the post.

Anything else following the_post and before the end of the loop is entirely our choosing, and is what we use to display the post information – it can be as basic or advanced as required.

Delegation of duty

WordPress provides many ways for us to display a collection of posts. For example, the front page contains the latest posts. The archive section will show a larger collection of posts, spread over a specific time period. The search page shows posts that meet search conditions.

Rather than having one super-sized piece of code that manages all of this, the work is broken down and delegated to several smaller handlers that deal with a specific task. Each of these will contain the exact same loop discussed above, but will process the information in different ways.

The handlers are spread across different files:

  • index.php – displays the front page
  • single.php – displays a single page
  • search.php – displays search results
  • archive.php – displays archives
  • page.php – displays a WordPress ‘page’

While this is very flexible, it does cause one problem: duplication. If we wish to maintain a consistent theme across our entire blog then we will need to duplicate it in each of these files. Fortunately most of the changes will be stylistic, and will only require a CSS modification. A basic structural change can cause a lot of work.

It should be noted that in previous guides we did in fact introduce a basic structural change. This means we need to update each of the files – an ideal reason to investigate everything.

105 Responses to Dissection of a WordPress theme: Part 4

  1. Thank you for the awesome Theme Guide series!!! I’ve been thinking about digging into Kubrick to find out how it worked, but I couldn’t figure out where to start, and it all seemed too complicated. Your guides made it seem a piece of cake. Really, I went through the first three “episodes” in only a couple of hours with excellent results. I even managed to make some modifications of my own: as my posts are usually really long, fixed width makes scrolling a painful experience, therefore taking advantage of the entire window width is mandatory. But I also wanted to keep a fixed width on the sidebar… A couple of wrappers, some negative margins and it worked! My blog will have a brand new theme in a couple of hours, as I complete the fourth tutorial. Thank you again!

  2. Thanks so much for this terrific guide! I’ve been learning CSS, and this guide will definitely help me ni creating my own themes. Before this, I didn’t really know where to start, but I followed your step-by-step directions, and it worked. It’s a great guide. Nice work!

  3. John,

    It still isn’t working for me. It happens when I click on a short entry and it takes me to a single view of just that entry. There’s a big text box at the bottom of the page that says “Leave a reply” and the side bar kind of covers or gets covered up by it.

    I’m seeing it on:

    Maybe send me your email and I’ll send you a screen shot.