Using The WordPress Loop

When developing WordPress themes, it’s important to know about the loop. The WordPress Loop is a function that grabs posts from your database, and allows you to display multiple posts on a page, such as the index page of a blog.

There are many advanced variations of the loop, but in this article we’ll focus on the basic loop, so you can build up from there.

If you would like more information on creating WordPress plugins, see our tutorial series on creating your first WordPress plugin.

What you will need…

In order to edit your theme, you will need a local development site, or you can edit the theme files on your server using the cPanel File Manager. (It is recommended that you do not edit live site files for a production site.) Creating a local WordPress installation on your computer is outside the scope of this article.

You will also need a plain, bare bones text editor like Notepad, TextEdit, Sublime, or similar. Editing files in a Word document will add all kinds of extra text that will corrupt your file.

How the Loop Works

So how does the loop work? A basic understanding of PHP is important here, but here are the basics.

• The loops checks for posts.
• If there are posts, each one will be displayed until there are no more.
• While displaying the posts, you can add any content or HTML.

The loop does its job best when you match the elements of your post (like the title, date, or other information) with an appropriate HTML tag.

Starting the Loop

To begin the loop, simply initiate a PHP while statement, which will run as long as there are posts available to process:

<?php 
// Check to see if we have posts 
if ( have_posts() ) : while ( have_posts() ) : 
// Open a 'while' loop 
the_post(); 
// Repeatedly grab next post 
the_content(); 
//Get the content of the post 
endwhile; 
// End the loop 
endif; 
// End the 'if' statement 
?>

Inside the Loop

Within the loop, you would call functions like the_permalink(), the_title(), the_content(), and various other WordPress functions that you want displayed for each post on the page.

In this example, we just want to display the post title with a link to the main post, as well as the post content:

<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></h2>
<?php the_content(); ?>

As you can see, we created a link within the title of the post on the first line, then display the content below it.

As this is a loop, it will display this information for each post that you have within WordPress until there are no more posts to process.

Ending the Loop

Now that we have started the loop and added our content to the loop, we need to end it. To end the loop, you may use the following code:

<?php endwhile; else: ?>
<p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
<?php endif; ?>

Complete the WordPress Loop

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></h2>
<?php the_content(); ?>
<?php endwhile; else: ?>
<p><?php _e('Sorry, no posts matched your criteria.'); ?></p>
<?php endif; ?>

Where does the loop go?

In theory, you can put the loop anywhere you need to generate an index of posts. But typically, the loop will go into the index.php template page, or any pages designated as an index page like Archives, Category pages, and the like.

References

For further technical documentation on the WordPress loop, you may review the WordPress Codex page on the loop, and the newer documentation on have_posts.