Making WordPress themes II : The Loop

(This post is a second part of the “Making WordPress themes” series. The first part is “Making WordPress themes I : static basics“)

The Loop is perhaps the most important thing there is to understand in WordPress theme building. It is the heart, the soul and the skeleton of any WordPress theme. It’s been fairly well documented at Codex – see pages “The Loop” and “The Loop in Action” – but no WordPress theme building series could be complete without yet another attempt of making it easier to understand, so here we go…

Let’s try and make it as simple as possible – The Loop is all about posts and pages.

Think about any WordPress web site out there. Now separate that web site into logical parts – front page, single post, single page, archives, category, search results, etc. Any of those parts does one of the things below:

• display single post or page (either a title, link, excerpt, or full body content)
• display a list of posts or pages (archives pages, category pages, search results, etc)
• display several lists of posts and pages (complex front pages with posts from several categories displayed separately)

If you know how to control The Loop, you know how to do any of the above. Now let’s see how it works, in case you weren’t born with The Loop Controlling Super-Powers.

Navigate your file manager to the themes directory of your WordPress installation, and look through any theme that you have available. One common thing between all themes that you probably won’t notice from the first glance, looks something like this:

It is somewhat difficult to notice, because the lines above are usually surrounded by a lot of theme specific XHTML and PHP. Let’s clean those lines up a bit, so that they make more sense:

Better? Here is how it goes. A check is done for if there are any posts (or pages that is) to be displayed on the current page. If there are any, then a while loop is started and each post is loaded one by one (using the_post() function call). This is a rather simple piece of code, which does a lot on the background, and makes our lives, as theme developers, a lot easier.

First of all, The Loop is smart enough to understand where we are – front page, category, archives, or search results. That means that you’ll use exactly the same code to lists posts no matter where you are. (In our next post for this series, we’ll see how WordPress identifies different locations a visitor can come to, and how we can control what is displayed.)

Secondly, The Loop gets all those relevant posts, taking into consideration the limits which you’ve set in the Options -> Reading -> Blog Pages -> Show at most X posts.

Thirdly, it provides us with a bunch of useful functions for displaying particular parts of posts – the_ID(), the_title(), the_guid(), the_content(), the_excerpt(), etc. Here is a simple example of The Loop in action:

The above snippet will look for posts, and if any are found, will show a title and full content of each, linking title to the full post page.  If no posts were found, the truth will be told.

Which functions are available from within The Loop?  Now that’s a touch question.  There are quite a few, but one has to dig through WordPress source code to find them all.  Looking through theme files is an alternative, but a rather limited one – most themes use the same stuff.

If you are prepared to look through the source code, start in wp-includes/ directory and given priority to files named something-template.php (wp-includes/post-template.php is a good place to start).  These usually provide functions for templates, and that’s exactly what you need.  Also, while looking through those functions, note that some even accept parameters.

Now I’ll give you some time to play with your loop.  Make it beautiful.  Make it useful.  Learn it inside out. In the next post we’ll see how WordPress knows which posts to fetch (hint: template hierarchy), and, once we know, we’ll see if there is any way for us to control that behavior (hint: the query).