Easily Adaptable WordPress Loop Templates
In this article, I present several heavily commented examples of WordPress loops. I have found that many readers appreciate these types of loop examples, as it helps them to understand how the loop works while enabling them to easily copy, paste, and adapt the code for their own purposes. In our first example, we examine a basic WordPress loop. When implemented, this loop will display “x” number of posts, where “x” represents the number specified via the WordPress Admin reading options panel. To use this code, simply copy & paste into your WordPress theme’s index.php file1 and customize accordingly.
Your Basic WordPress Loop
// any code included here occurs before the wordpress loop and is always displayed
<?php if (have_posts()) : ?>
// if there are posts to display, process any code included here only once
// display any code output from this region above the entire set of posts
<?php while (have_posts()) : the_post(); ?>
// loop through posts and process each according to the code specified here
// process any code included in this region before the content of each post
<?php the_content(); ?> // this function displays the content of each post
// process any code included in this region after the content of each post
<?php endwhile; ?>
// stop the post loop and process any code included here only once
// any code output will be displayed below the entire set of posts
<?php else : ?>
// if there are no posts to display, process any code that is included here
// the output of any code included here will be displayed instead of posts
<?php endif; ?>
// any code included here occurs after the wordpress loop and is always displayedHopefully, this basic loop will look very familiar to you. If you are new to WordPress, and would like to gain a better understanding of how the loop works, I highly recommend utilizing the following example. The next example is a carbon copy of the previous loop example, only with several key (X)HTML elements added for clarity. Copy & paste this code into the index.php1 of your WordPress theme and examine the results in a browser. Hopefully, combining the code comments with the browser output2 will give you a crystal clear picture of the various features of the WordPress loop.
// any code included here occurs before the wordpress loop and is always displayed
<h1>This text is generated via the h1 element included before the WordPress loop.</h1>
<p>Any code included in this part of the document is processed only once.</p>
<?php if (have_posts()) : ?>
// if there are posts to display, process any code included here only once
// display any code output from this region above the entire set of posts
<h2>This text is generated via the h2 element only if there are posts.</h2>
<p>Any code included in this part of the document is processed only once.</p>
<?php while (have_posts()) : the_post(); ?>
// loop through posts and process each according to the code specified here
// process any code included in this region before the content of each post
<h3><a href="<?php the_permalink() ?>">Title: <?php the_title(); ?></a></h3>
<p>The title of this post is generated before the content of each post.</p>
<?php the_content(); ?> // this function displays the content of each post
// process any code included in this region after the content of each post
<h4>This is post #<?php the_ID(); ?>, written by <?php the_author(); ?></h4>
<p>The previous metadata is generated after the content of each post.</p>
<?php endwhile; ?>
// stop the post loop and process any code included here only once
// any code output will be displayed below the entire set of posts
<h5>This text is generated via the h5 element only if there are posts.</h5>
<p>Any code included in this part of the document is processed only once.</p>
<?php else : ?>
// if there are no posts to display, process any code that is included here
// the output of any code included here will be displayed instead of posts
<p>If you are seeing this message, there are no posts to process/display.</p>
<p>Any code included in this part of the document is processed only once.</p>
<?php endif; ?>
// any code included here occurs after the wordpress loop and is always displayed
<h6>This text is generated via the h6 element included after the WordPress loop.</h6>
<p>Any code included in this part of the document is processed only once.</p>Once you understand the basic functionality of a basic WordPress loop, it is much easier to customize the look and feel of your WordPress-powered blog. Using built-in WordPress functionality, you can display any information you want, wherever you want. WordPress makes it easy to display vital post data, navigational tools, and many other versatile features3.
To see an example of this in action, replace the previous loop example with the following, fully-pimped version of WordPress looping bliss. This is like the advanced course for understanding the basic WordPress loop. Dig into this, and you will soon be crafting your own, highly specialized loops.
// any code included here occurs before the wordpress loop and is always displayed
<h1><?php echo get_settings('home'); ?>/"><?php bloginfo('name'); ?></a></h1>
<ul class="menu">
<li><a href="<?php echo get_settings('home'); ?>/">Home Page</a></li>
<?php wp_list_pages('sort_column=menu_order&depth=1&title_li='); ?>
<?php wp_register('<li>','</li>'); ?>
</ul>
<?php if (have_posts()) : ?>
// if there are posts to display, process any code included here only once
// display any code output from this region above the entire set of posts
<h2>Here are a few of my recent posts:</h2>
<?php while (have_posts()) : the_post(); ?>
// loop through posts and process each according to the code specified here
// process any code included in this region before the content of each post
<h3><a href="<?php the_permalink() ?>">Title: <?php the_title(); ?></a></h3>
<p>Date: <?php echo date("l, F d, Y"); ?> | <?php comments_number(); ?></p>
<?php the_content(); ?> // this function displays the content of each post
// process any code included in this region after the content of each post
<h4>This is post #<?php the_ID(); ?> | Author: <?php the_author(); ?></h4>
<p>Filed under: <?php the_category(','); ?> | <?php edit_post_link(); ?></p>
<?php endwhile; ?>
// stop the post loop and process any code included here only once
// any code output will be displayed below the entire set of posts
<h4><?php posts_nav_link() ?><?php previous_post_link(); ?> •
<?php posts_nav_link() ?><?php next_post_link(); ?></h4>
<?php else : ?>
// if there are no posts to display, process any code that is included here
// the output of any code included here will be displayed instead of posts
<p>Sorry, no posts matched your criteria.</p>
<?php endif; ?>
// any code included here occurs after the wordpress loop and is always displayed
<h6>Copyright © <?php echo get_settings('home'); ?>/"><?php bloginfo('name'); ?></a> <?php echo date('Y'); ?></h6>Observing the patterns involved with the WordPress loop, it becomes easier to look at the code and understand how each part operates and contributes to the whole. With a little practice tweaking and rearranging the various elements, you will improve your ability to manipulate your theme files and gain a better understanding of how WordPress works in general.
The Ever-Popular Mullet Loop
Now that we understand the functionality behind a basic WordPress loop, let’s tweak things a bit and transform our previous example to serve as the ever-popular “mullet” loop. Rather than simply display the full content from each post, the mullet loop displays the full content for only the first post, and then displays only excerpts for all remaining posts. This is a very popular and effective way of highlighting your latest article while providing easy access to recently published posts. To get a better idea of how this works, consider the following:
This paragraph represents the full content of your most recent post.
It will be displayed in its entirety until you publish your next post,
at which time it will appear beneath this location as an excerpt only.
If we were numbering these hypothetical posts, this post would be #7.
Here comes the dummy text Lorem ipsum.. Lorem ipsum dolor sit amet, a
consectetuer adipiscing elit. Suspendisse nisi. Aliquam ac massa vitae
ligula dictum congue. Sed elit nulla, eleifend ut, fringilla porttitor,
tincidunt, nunc. Nam eros nisi, dapibus faucibus, placerat sed, congue
sed, lectus. Pellentesque vel risus in lacus iaculis auctor. Fusce vel.
Praesent imperdiet diam ut urna. Phasellus a tortor sit amet maurismet
vulputate gravida. Suspendisse sed diam. Duis pede ipsum, sagittisorit
ut, semper in, ultricies at, justo. Sed leo risus, scelerisque quis, a
luctus dictum, vulputate id, mi. Praesent at magna auctor magna dictum
suscipit sagittis. Aliquam gravida facilisis dui. Morbi placerat leros
est. Nulla a nibh fringilla est eleifend lacinia. Mauris arcu. Ut diam.
This sentence represents an excerpt from post #6, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.
This sentence represents an excerpt from post #5, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.
This sentence represents an excerpt from post #4, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.
This sentence represents an excerpt from post #3, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.
This sentence represents an excerpt from post #2, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.
This sentence represents an excerpt from post #1, which is displayed
instead of its full content, thanks to the ever-popular mullet loop.To produce this presentational functionality, we have modified our previously discussed, basic WordPress loop according to the following, heavily commented example. As before, read through the comments to gain an understanding of how everything works, and then proceed to the final example for a “marked-up” version to use on a “live” WordPress page.
// any code included here occurs before the wordpress loop and is always displayed
<?php if (have_posts()) : ?>
<?php $count = 0; ?>
// if there are posts to display, set the count to zero and begin the loop
// if there are posts to display, process any code included here only once
// display any code output from this region above the entire set of posts
<?php while (have_posts()) : the_post(); ?>
<?php $count++; ?>
// for each post, increase the count variable by one and process any code included here
// the output of any code included here will be displayed above the content of every post
<?php if ($count == 1) : ?>
// if this is the first post, process any code that is specified in this region
// process any code specified in this region before the content of the first post
<?php the_content(); ?> // display the full content of the first post only
// process any code specified in this region after the content of the first post
<?php else : ?>
// if this is not the first post, process any code specified in this region
// process any code specified in this region before the content of each post
<?php the_excerpt(); ?> // display only the excerpt for all other posts
// for all posts except the first, process this code below each post
<?php endif; ?>
// for each post, including the first, process any code included here
// any code output will be displayed below the content of every post
<?php endwhile; ?>
// stop the post loop and process any code included here only once
// any code output will be displayed below the entire set of posts
<?php else : ?>
// if there are no posts to display, process any code that is included here
// the output of any code included here will be displayed instead of posts
<?php endif; ?>
// any code included here occurs after the wordpress loop and is always displayedNow, let’s wrap up this monster post with a marked up example of the mullet loop. Copy and paste the following code into your index.php file1, upload to your server, and examine in a browser. And with that, you now have a complete mullet loop template with which to conquer the world, as well as a better understanding of how to create your own looping masterpiece!
// any code included here occurs before the wordpress loop and is always displayed
<h1><?php echo get_settings('home'); ?>/"><?php bloginfo('name'); ?></a></h1>
<ul class="menu">
<li><a href="<?php echo get_settings('home'); ?>/">Home Page</a></li>
<?php wp_list_pages('sort_column=menu_order&depth=1&title_li='); ?>
<?php wp_register('<li>','</li>'); ?>
</ul>
<?php if (have_posts()) : ?>
<?php $count = 0; ?>
// if there are posts to display, set the count to zero and begin the loop
// if there are posts to display, process any code included here only once
// display any code output from this region above the entire set of posts
<h2>Welcome to the Mullet Loop: Full article first, followed by excerpts</h2>
<?php while (have_posts()) : the_post(); ?>
<?php $count++; ?>
// for each post, increase the count variable by one and process any code included here
// the output of any code included here will be displayed above the content of every post
<h3><a href="<?php the_permalink() ?>">Title: <?php the_title(); ?></a></h3>
<h4>Date: <?php echo date("l, F d, Y"); ?> | <?php comments_number(); ?></h4>
<?php if ($count == 1) : ?>
// if this is the first post, process any code that is specified in this region
// process any code specified in this region before the content of the first post
<p><strong>Here is the full content of my latest and greatest article:<strong></p>
<?php the_content(); ?> // display the full content of the first post only
// process any code specified in this region after the content of the first post
<h4>Please <a href="<?php bloginfo('rss2_url'); ?>">subscribe</a> to my feed!</h4>
<?php else : ?>
// if this is not the first post, process any code specified in this region
// process any code specified in this region before the content of each post
<?php the_excerpt(); ?> // display only the excerpt for all other posts
// for all posts except the first, process this code below each post
<?php endif; ?>
// for each post, including the first, process any code included here
// any code output will be displayed below the content of every post
<h4>This is post #<?php the_ID(); ?> | Author: <?php the_author(); ?></h4>
<p>Filed under: <?php the_category(','); ?> | <?php edit_post_link(); ?></p>
<?php endwhile; ?>
// stop the post loop and process any code included here only once
// any code output will be displayed below the entire set of posts
<h4><?php posts_nav_link() ?><?php previous_post_link(); ?> •
<?php posts_nav_link() ?><?php next_post_link(); ?></h4>
<?php else : ?>
// if there are no posts to display, process any code that is included here
// the output of any code included here will be displayed instead of posts
<p>Sorry, no posts matched your criteria.</p>
<?php endif; ?>
// any code included here occurs after the wordpress loop and is always displayed
<h6>Copyright © <?php echo get_settings('home'); ?>/"><?php bloginfo('name'); ?></a> <?php echo date('Y'); ?></h6>Footnotes
- 1 Virtually any WordPress theme file may be used here. Keep in mind, however, that the standard loop is designed to operate only once per web page. Thus, placing a loop in your
footer.phpfile, for example, will result in errors if a second loop is encountered elsewhere. - 2 For best results, I recommend setting the default number of posts displayed to a relatively large number such as 10 or 15. Displaying a greater number of posts makes it easier to recognize patterns in the code output that may not otherwise be recognized.
- 3 For additional information on these and many other WordPress features, please refer to the WordPress Codex.
17 responses to “Easily Adaptable WordPress Loop Templates”
Sure do — check out the excellent the_excerpt Reloaded (404 link removed 2013/10/15). It allows full control over just about everything related to post excerpt generation and display. I use it on many of my blogs.
Thanks for the link Perishable :) I’ve tried playing with the plugin but somehow I could not get it to work. It seems that the the_excerpt_reloaded function just loaded the_excerpt and ignoring any custom settings.
However, after a few minutes of Googling I found a quick and dirty way of overriding the_excerpt function :)
That works! :)
While it’s not too bad to be able to modify existing themes, I’ve always wanted to be able to create my own wordpress theme from scratch one day. Looks like this post will help me do it. I’m definitely bookmarking this for future references! -Andy
Thanks for the feedback, Andy — glad to be of service! ;)