WordPress Theme Tutorial for Beginners – Part 4: The Post Loop

In this lesson of the WordPress theme tutorial for beginners we will go into detail about the “post loop” in WordPress; what it is, how it looks like, why we use it and how to access posts. We will then go about implementing the loop in our theme.

The post loop

If you are familiar with PHP you might recognize that a “loop” is a technique of going through each element in an array or object with for, foreach or while. The loop in WordPress works just like that. But we will use WordPress’ own functions to loop in order to get some additional benefits and simplifications.

At all times, WordPress has already queried the posts for you – depending on which page you are at. If you are at a category page, WordPress has already queried all posts associated with this category, And if you are at a single post page, WordPress has already fetched that one post for you.

When we want to access the posts WordPress has queried in our templates, we add the loop. Inside the loop we have access to each post. And for each post we decide what to show or do.

Note: Even in single post or single page templates you will add a loop, even though we know it only contains one post! The loop simply runs just once.

Here is the WordPress loop in all its glory:

while (have_posts()) : the_post();
	// Access to each post here
endwhile;

This piece of code does two things. The while part (including the endwhile) is the looping part which will loop however long there are any posts left. The second part is the the_post() which sets up simplified and intuitive access to the post object inside the loop. We will learn more about that later on.

It’s good practice to wrap the loop inside an if check that checks if there actually are any posts to loop through. Then we can also optionally shows a message if there weren’t. The post query could be empty if you go to an empty category archive or tries to search for something that has no hits. This is a better version of the loop:

if (have_posts()) {
	while (have_posts()) : the_post();
		// Access to each post here
	endwhile;
} else {
	?><p>No posts, sorry.</p><?php
}

Get familiar with this piece of code as you will repeat this whenever you want to access posts! Let’s implement the loop in our theme.

Implementing the loop in our theme

Let’s add the loop in our index.php, replacing the dummy text.

<?php get_header(); ?>
<?php 
if (have_posts()) {
	while (have_posts()) : the_post();
		the_title();
	endwhile;
} else {
	?><p>No posts, sorry.</p><?php
}
?>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

I added a function called the_title() inside the loop which echoes out the post title. This is just to that we can see the loop in practice. Don’t worry, we will in the next step learn all about accessing all of the actual post information.

Let’s see what happens in WordPress now. Refresh the front page. Depending on your settings and content you should see some titles appearing. In my WordPress I have the default post “Hello world!” and another post I created titled “This is another post”. This is what I get on the frontpage:

If you try to visit a single post page, you should see only one title, the title to the post you are viewing. Nice!

global $wp_query;
var_dump($wp_query);

Let’s add one important detail to our loop in index.php; a way for the user to navigate to next and previous page of posts.

Adding post loop navigation

Keep in mind that the loop will fetch the number of posts defined in your WordPress Settings > Reading, whenever you are at a page that shows multiple posts. If there are more posts available in the loop than the number defined here, we need a way to navigate between the pages. For this we can use the function the_posts_pagination().

This function accepts some parameters to customize its output. You can define the number of pages between the ellipses (when there are a lot of pages). You can also define what the texts for the “Previous” and “Next” page links should be. I’ll add it without any parameters in order to do the defaults, but you can adjust it if you like.

...
	while (have_posts()) : the_post();
		the_title();
	endwhile;
	the_posts_pagination();
} else {
...

This function outputs absolutely nothing if there are less or equal posts as number of posts per page setting. So don’t worry if you think you got it wrong because you don’t see any output. Once there are more posts than posts per page, this function outputs a div, a heading for screenreaders (which you typically hide with CSS), and a number of pagination links.

Now that we know how to get access to any post WordPress has found for us, the next step is to learn how to show what we want from each post; inside the loop.

Documentation on methods used

• have_posts
• the_post
• the_title
• the_post_pagination