WordPress Bits

Hacking WordPress. Keeping the bits together.

Making WordPress themes II : The Loop

Posted by Leonid Mamchenkov on August 21, 2007

(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:

The Loop (cyphered)

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:

The Loop (decyphered)

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 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).

15 Responses to “Making WordPress themes II : The Loop”

  1. sunburntkamel said

    i thought the if … else was deprecated?

  2. sunburntkamel,

    maybe that post is outdated. There is at least one scenario that I can think of when the “else” block is going to be executed – a search result with no posts matching search criteria found.

    Thanks for the link anyway

  3. No wonder why it felt right when I was looking at the Sandbox theme without have_posts and else. I always thought it was odd to use if…else with the 404.php file. Although, Leonid is right about the else block on no search results.

  4. sunburntkamel said

    ok, so search.php needs the if … else. but it should be the only one.

  5. sunburntkamel,

    as we’ll see in the next post of the series, there are many ways to organize the theme. Yes, there is some truth to the statement that the “else” part is not needed everywhere, but it’s not as as simple as it may seem (theme can be defined in just index.php file, archives for certain dates might be empty, categories too, and the upcoming taxonomy in 2.3 is yet to be tried, etc).

  6. Sadish said

    Even in the index.php, it might be needed.

    Try running this link on your browser.
    https://wpbits.wordpress.com/?p=1000 where I used 1000 for a non-existing post id. see what happens. It does not load the 404.php, and it uses the else part in the index.php.

    Just my 2 cents !


    • I actually don’t understand The Loop so much. But i’ve heard this enough and most people say it is very useful. Why don’t someone create a new post that explain everything about The Loop for a novice like me. I think that will be absolutely useful

  7. […] Posts More WordPress theming at WPDesigner.comMaking WordPress themes II : The LoopTip #3 : Under ConstructionMaking WordPress themes I : static basicsNavigating WordPress source […]

  8. […] Making WordPress themes II : The Loop […]

  9. […] Making WordPress themes II : The Loop […]

  10. […] is important for usability).  I don’t use this in my index or single page templates, because 404’s shouldn’t land there (if they do, it’s a problem with wp_query() ).  After the search field, we jump into a custom […]

  11. Ghosts said

    Very useful. Thanks very much.

  12. […] (which is important for usability). I don’t use this in my index or single page templates, because 404’s shouldn’t land there (if they do, it’s a problem with wp_query() ). After the search field, we jump into a custom […]

  13. ambj said

    nice, good info.

  14. […] gli aspetti di base della costruzione della parte statica dei temi. Il secondo, pubblicato oggi, analizza invece la parte di tema relativa al Loop, ovvero la parte “dinamica” di WordPress. La […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: