X

The Ultimate Guide to the WordPress Loop

In this tutorial, I’ll be going over The Loop, and how WordPress uses it to display your posts and pages. Keep in mind, this is slightly more advanced than our previous tutorials. Hopefully you will find this ultimate guide easier to understand than what’s available in the WordPress documentation. Here’s what we will go over:

  • A definition of The Loop.
  • Basic flow of The Loop.
  • Template tags used in The Loop
  • What to do after The Loop
  • Template file hierarchy

If you want to get a better understanding of how a WordPress theme really works behind the scenes, read on.

Note: This tutorial assumes you’re using a standard WordPress theme, such as the default Kubrick theme. No advanced multiple-loop stuff…yet.

What is The Loop?

You’re probably still wondering what The Loop even is. Basically, it’s what displays the content you see on your homepage, your single posts, pages, archives, search results, and more.

If a user accesses your homepage, archives, or search results – by default, the Loop will display a certain number of posts as defined in your Reading Options.

WordPress Reading Options

At the moment, my homepage displays 10 posts per page, which is what I defined Show at most * posts. On single posts and pages – the same basic Loop code will just display just that specific page.

Basic flow of the loop

Let’s break the Loop down into 3 parts.

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

1. What you want displayed in the Loop

<?php endwhile;?>

2. What is displayed when the Loop is over

<?php else : ?>

3. If there’s nothing to display

<?php endif; ?>

If there are posts available in the query, it will start displaying them in a while loop, what is defined in part 1. When the while is over, it will display what is in part 2. If there’s no posts found, or there’s some sort of other 404 error, part 3 gets displayed.

Template Tags used within the Loop

Unless you want 1. What you want displayed in the Loop repeated on your WordPress blog’s homepage 10 times, you should probably learn some of the basic template tags. Let’s take a look at the code of index.php in the default WordPress template.

WordPress Loop Breakdown

As you can see, there’s quite a few template tags within the Loop that will output things such as the post title, the permalink, the content, etc. I’ll break down each of the template tags in the WordPress default theme.

  • <?php the_permalink() ?> – This will echo the permalink of the post, i.e http://www.themelab.com/?p=1
  • <?php the_title(); ?> – This echos the post title, i.e. Hello World!
  • <?php the_time(‘F jS, Y’) ?> – This will echo the date, i.e. April 4th, 2008. A full list of ways to format the date can be found on php.net
  • <?php the_author() ?> – This will display the author’s name, i.e. Leland. This is commented out in the default theme.
  • <?php the_tags(‘Tags: ‘, ‘, ‘, ‘<br />’); ?> – This will display the tags assigned to the post, separated by commas, and followed by a line break
  • <?php the_category(‘, ‘) ?> – This will display the categories in a similar fashion as the tags above.
  • <?php edit_post_link(‘Edit’, ”, ‘ | ‘); ?> – The edit post link will be visible only to those with permission.
  • <?php comments_popup_link(‘No Comments »’, ‘1 Comment »’, ‘% Comments »’); ?> – Will display the link to the comments. This will not be displayed on single posts or pages.

There are a lot more listed on the Template Tags page over at WordPress.org. Some of these may work in the Loop, while some may not.

After the Loop

Let’s take a look at the code after the loop stops looping in the default theme.

After the Loop breakdown

<div class="navigation">
<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
</div>

As you might have guessed, this will display the pagination you see on the homepage, archives, and search results. These won’t be displayed on single posts and pages. Of course you could replace this with something like PageNavi, but that’s up to you.

If there are no posts to display (possibly due to a 404 error), the following will be displayed after the else

<h2 class="center">Not Found</h2>
<p class="center">Sorry, but you are looking for something that isn't here.</p>
<?php include (TEMPLATEPATH . "/searchform.php"); ?>

That will display the Not Found message along with the search form. In this case there would have to be a search form code located in a file called searchform.php in the template directory, which there is in the default theme.

Template Hierarchy

Some template files will take priority over the index.php for certain types of pages if they are present in the template directory. Listed below are a few examples of template hierarchy, listed in order of priority.

Homepage

  1. home.php
  2. index.php

Single Post

  1. single.php
  2. index.php

Search Results

  1. search.php
  2. index.php

404 Page

  1. 404.php
  2. index.php

There are a few more advanced techniques listed on the Template Hierarchy page over at WordPress.org.

So what’s the point of the template hierarchy? Basically you can use the it to create new layouts for different types of WordPress pages without hacking up your index.php file too much.

Conclusion

So now you (hopefully) have a better insight on what the WordPress Loop is all about. Feel free to leave a comment if you liked it, hated it, couldn’t understand, whatever – I welcome all feedback. Subscribe to the feed for all the latest updates on Theme Lab theme releases and new tutorials. Thanks for reading.

Comments   Leave a Reply

  1. I want to display the link to next and previous post on single post page . Also the anchor text for the link should be the respective post name.

    Please tell me how can I do it?

    I tried to embed in single.php but not showing post name.

  2. Great, I’m learning to hack the loop, even at RSS-Atom levels and this basics are good for me. Keep rocking guys.

  3. Thank you, thank you, thank you.
    I can’t thank you enough. Everyone, including wordpress.org is saying ‘put that code in the Loop’ but NO ONE was saying what the hell is Loop! Except YOU. Great help.

  4. Tutorial de loop do wordpress « Galeria de scripts September 17, 2009 at 10:02 am

    […] Link do tutorial […]

  5. I’m an IT project manager who, at one time in his life, was a hands-on “techie.” I guess this sort of puts me somewhere in the middle of the spectrum between computer-literate-but-clueless-about-computer-programming and total-geek-who-thinks-and-speaks-in-Cplusplus.

    The great thing about WordPress is that it’s simple enough to use that the most clueless computer illiterate can get some sophisitcated features going with ease while someone with even a small amount of techie skills can do a lot of tweaking.

    While I’m not a PHP or Java programmer, I DO have training in the C#/VB.NET language and understand loops and programming structures. This small bit of knowledge along with tutorials, such as yours, gives me the ability to tweak with the best computer “geeks.” Your tutorial was very easy to understand (probably because I do have an IT background). I think that even if I didn’t have the IT background, your explanation made it possible (with a little effort) to understand how to use the “loop” and a bit more about the internal plumbing of the WordPress application.

    Thanks !!
    Jerry Bucknoff, PMP
    My WordPress blog is blogs.pmbestpractices.com, another site proudly powered by WordPress.

  6. 30 WordPress Development Tutorials | Pro Blog Design – Learningism September 7, 2009 at 2:18 am

    […] The Ultimate Guide to the WordPress Loop […]

  7. Wordpress Wednesday: 50 Links & Resources from around the web | Wordpress Guerrilla August 19, 2009 at 11:16 am

    […] The ultimate guide to the wordpress loop […]

  8. 30 WordPress Development Tutorials | SEO & Web Design July 21, 2009 at 2:35 am

    […]  The Ultimate Guide to the WordPress Loop […]

  9. 30 WordPress Development Tutorials at BLOG GRAPHIC DESIGN July 3, 2009 at 7:39 am

    […]  The Ultimate Guide to the WordPress Loop […]

  10. James McWhorter May 27, 2009 at 9:29 am

    Very helpful. Thanks!

  11. WordPress Loop | Theme Heven April 23, 2009 at 10:27 pm

    […] Read More… […]

  12. Derek Perkins April 5, 2009 at 9:27 am

    Thanks for the post, it really helped. My only suggestion would be to edit your template tags so that they all have the closing semicolon.

  13. I was trying to get it so that I only displayed one category on the main page and I was succussful after reading this post with the exact syntax I need to modify the loop

    http://www.nietoperzka.com/wptraining/custom-order-of-posts-on-main-page/

    But then I had errors with my other categories and areas of the site but once I read your post and it explained more the page heirarchy I made a seperate home.php for my landing page loop and left everything else the same as original

    thanks for this post.

  14. Jarod Taylor - Web Design & Web Development January 7, 2009 at 9:36 am

    […] you are having trouble understanding anything we just did, I recommend visiting this tutorial for a better understanding of the […]

  15. Can I modify wordpress loop using a plugin fnction?

  16. you know what, u r simply awesome, i m wondering why didnt I find your site before and why didnt I switch over to wordpress before.

    I have also started promoting your website through positive word of mouth here in India.

    Recently, I went to a Toastmasters club meeting and told people about how wonderful your site is.

    Thanks for your wonderful tips.

  17. TheMoonbase - Bookmarks » Blog Archive » The Ultimate Guide to the WordPress Loop | Theme Lab October 13, 2008 at 2:00 pm

    […] The Ultimate Guide to the WordPress Loop | Theme Lab because after all this time, I’m STILL confused […]

  18. One thing I found particularly useful is the category hierarchy:

    1. category-6.php
    2. category.php
    3. archive.php
    4. index.php

    The first page allows you to have a page for each category. WordPress will use ‘category-6.php’ as the default page for category 6. You can find out the category number in the backend by going to Manage > Categories and then clicking on a category. After clicking on the category look up in the address bar and near the end you will see: &cat_ID=6. That 6 is the category number. ‘category.php’ will be the default template for all categories if there are no individual category templates (like category-6.php) found. Just place these PHP files in the root of your theme folder.

  19. Really useful guide, thanks for sharing!

  20. Cynthia Clinton August 20, 2008 at 9:33 pm

    Thank you! Finally the Loop explanation I’ve been searching all over the web for! Now I get it. Thanks, again 😀

  21.   Table Of Contents Of Wordpress Tutorials, Helps, Tips and Tricks by aComment.net July 14, 2008 at 12:32 pm

    […] The Ultimate Guide to the WordPress Loop […]

  22. How To: Make your WordPress Search Results Unlimited | [Blog Tutorials] June 7, 2008 at 9:58 pm

    […] you may not want your search results to be limited by the confines of the standard WordPress Loop. This is a quick code hack to allow a search to return unlimited results, altering the standard […]

  23. Ultimate Guide to the WordPress Loop | [Blog Tutorials] June 7, 2008 at 9:50 pm

    […] One great area to start is learning how the WordPress loop works.  This is a basic function of blogging used to display the most recent X number of posts on your blog’s homepage (for traditional blogs).   Rather than go into to much detail here, I’d like to point you towards a new post by Themelab which is designed to be the Utlimate Guide to the WordPress loop.  […]

  24. Excuses, Wordpress, & Blogging | FPettit.com May 16, 2008 at 9:20 pm

    […] The Ultimate Guide to the WordPress Loop | Theme Lab […]

  25. TalkingApes.com » Blog Archive » Brad’s 2008 Link Extravaganza May 8, 2008 at 3:58 pm

    […] The Ultimate Guide to the WordPress Loop | Theme Lab […]

Add a Comment

We're glad you have chosen to leave a comment. Please keep in mind that all comments are moderated according to our privacy policy, and all links are nofollow. Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.

WordPress Launch Checklist

The Ultimate WordPress Launch Checklist

We've compiled all the essential checklist items for your next WordPress website launch into one handy ebook.
Yes, Send Me the Free eBook!