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.
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.
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.
<div class="navigation">
<div class="alignleft"><?php next_posts_link('« Older Entries') ?></div>
<div class="alignright"><?php previous_posts_link('Newer Entries »') ?></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
- home.php
- index.php
Single Post
- single.php
- index.php
Search Results
- search.php
- index.php
404 Page
- 404.php
- 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.
[…] subscribe to our feed! You can also receive updates from this blog via email.We all know what the WordPress Loop is right? If not, there are many great tutorials around the web that explain the WordPress […]
Really useful guide, I will try at once.
@Fernando: Thanks for letting me know…
It’s a very nice guide and I’ve translate it to spanish here in order to share it with no english spoken folks 🙂
Thank you 😉
[…] The Ultimate Guide to the WordPress Loop: The Loop happens to be very challenging. This link will help you through it. […]
[…] 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. […]
[…] two recent articles, I have have found helpful are: The Ultimate Guide to the WordPress Loop and another called Global Variables and the WordPress […]
@RSS Filter: That’s possible…but I’ll save that for a future tutorial.
[…] teach you everything you need to know about the WordPress Loop. What it is, how to use it, and more.read more | digg story Share and Enjoy: These icons link to social bookmarking sites where readers can […]
So how would you tell the loop to display only the last post in a static home page or index file?
Awesome guide about an important aspect of WordPress theme development. Thanks!
[…] The Ultimate Guide to the WordPress Loop […]
[…] The Ultimate Guide to the WordPress Loop (tags: wordpress) […]
[…] propaganda press on April 6th, 2008 ok much like combolombo we just discovered a new site with an awesome article on the wordpress loopy. you definitely want to read and bookmark this one. Tagged with: wordpress « African […]
[…] Ultimate guide to the WordPress Loop… Get the skinny on all the globals and what […]
[…] The Ultimate Guide to the WordPress Loop | Theme Lab (tags: wordpress howto php guide programming theme blog) […]
[…] Guide to the WordPress loop […]
[…] The Ultimate Guide to the WordPress Loop – Theme Lab […]
[…] The Ultimate Guide to the WordPress Loop (tags: loop wordpress) […]
Oh man this is a keeper. I could have seriously used this when trying to figure out some plugin tweaks.
They kept saying, “place this code outside the loop”
And now I know what the !#$%^% a loops is 🙂
[…] is a guide to the WordPress Loop. Especially useful for beginning WordPress theme creators and wordpress developers. Share and […]
Hey Leland, OT, but congrats on your subscriber boost !
– Sean Pollock
very helpful guide.. thanks!
[…] The Ultimate Guide to the WordPress Loop – This site really breaks down the Loop for you to understand. […]
[…] WordPress. Go ahead, subscribe to our feed! You can also receive updates from this blog via email.The Ultimate Guide to the WordPress Loop: Ah, the famed WordPress loop that runs it all. Ronald has done a very nice job of identifying […]