Rockin’ out WordPress custom loops

What’s a loop?

When using WordPress, “The Loop” refers to the code in your template files that displays posts. Usually there is only one main loop per page, but you can have secondary custom loops to show special content. These can include recent posts and related posts.

The loop depends on queries

A query is related to the loop in that it determines what should be shown in the loop. For example, the default home query will contain all posts, 10 per page (or whatever number is set in Settings > Reading), from all categories; a single post query contains only information for the post or page you are viewing; archive loops will have posts according to the kind of archive page you are on (category, tag, month etc).

Default and custom queries

The main query for a WordPress page is determined automatically by the type of page you are viewing (it’s all handled by WordPress). You can create a custom query out of the default query by using the following PHP code somewhere before the start of your main loop code.

global $query_string;
query_posts($query_string . '&cat=-5');

The above code gathers the variable $query_string, which contains all the default query information and then uses query_posts() to create a query with all of the features of the default query, except the attributes that you change. In the example I have excluded the category with an ID of 5 from the query.

The benefit of using $query_string in this way is that you don’t destroy page pagination on the home and archive pages, which will happen when using query_posts() by itself.

The Loop code

The main loop code generally starts with something like <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>. Where have_posts() is a WordPress function that determines whether the current query has any posts in it. while ( have_posts() ) says “as long as there are posts in the query, do the following things”, and this repeats for each post until there are no more. In this case “the following things” are to execute the function the_post(), which fetches the post data from the database and makes it accessible for use via Template Tags, some of which are only available inside the loop.

Creating a custom loop

If you which to access other posts (to create a recent, related, popular or featured post list, for example) while keeping the main loop in tact you need to create a secondary custom loop. The best way to do this is to create a new query, using the WP_Query() function, which will be completely separate from the main query. Then you may loop over the posts in your new query.

New query for the custom loop

WP_Query() accepts the same parameters as query_posts(), so have a look at that Codex page to find out what parameters you need.

For this example, let’s query 5 random posts from a category called “Featured”.

$custom_loop = new WP_Query('showposts=5&category_name=Featured&orderby=rand');

Custom loop code

Now we have to loop over the posts in the new query. Since the original page query still exists and our new query is stored in the variable $custom_loop we can’t use the same code as the main loop, but it is similar. This loop is basically the same as the main loop code, but it checks our custom query variable $custom_loop for the posts.

if ( $custom_loop->have_posts() ) :
	while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

		// this is where we put the code to show what we want for each post

	endwhile;
endif;

Content for the custom loop

Unless we replace // this is where we put the code to show what we want for each post with something, nothing will actually show up when we run this code.

One of the simplest (and useful) things we could do is create a list of linked post titles.

if ( $custom_loop->have_posts() ) :
	echo '<ul>';
	while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

		echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';

	endwhile;
	echo '</ul>';
endif;

Note that because the code between while and endwhile gets repeated for every post, <ul> and </ul> (which start and end the unordered list) need to go outside of that part, i.e. outside of the loop.

Putting it all together

The complete code for a custom query and custom loop producing an unordered list of random featured post title link is:

$custom_loop = new WP_Query('showposts=5&category_name=Featured&orderby=rand');
if ( $custom_loop->have_posts() ) :
	echo '<ul>';
	while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

		echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';

	endwhile;
	wp_reset_query();
	echo '</ul>';
endif;

This is all PHP code, so make sure that you are in a PHP environment, i.e., this code should be somewhere after <?php and before ?>. If these bits aren’t in your file where you want the custom loop to go, you can wrap the code in them.

Towards the end I’ve added wp_reset_query(), which — as the name suggests — resets the query. For some reason, when using new WP_Query(), endwhile ends the loop, but not the custom query. There’s another method on The Loop codex page, but it hasn’t always worked for me.

Sometimes I find that wp_reset_query() doesn’t quite work the way I want it to, I don’t get back to the original query. If you have that problem try if ( have_posts() ) { while ( have_posts() ) { the_post; } };. That usually works for me to reinitiate the original loop, but I’ve seen it create a recursive post loop too, so be careful.

Using the custom loop in Thesis

Using the custom loop in Thesis is pretty simple (once you have a grasp on the less simple stuff above): all you have to do is wrap the above code in a function and hook it in. If you need more info on basic function syntax check out What are hooks and how do you use them? and The basic anatomy of a custom function on the Tech for Luddites blog.

function custom_featured_posts() {
	$custom_loop = new WP_Query('showposts=5&category_name=Featured&orderby=rand');
	if ( $custom_loop->have_posts() ) :
		echo '<ul>';
		while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

			echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';

		endwhile;
		wp_reset_query();
		echo '</ul>';
	endif;
}
add_action('thesis_hook_after_post','custom_featured_posts');

That code pasted into custom_functions.php will add a list of 5 random posts from a category called “Featured” to the bottom of every post.

If you only wanted to show it on single post pages you would use a conditional tag by adding if ( is_single() ) : after the first line that opens the function, and endif; before the last curly bracket that ends the function.

Add it to the sidebar

If you want to add it to the sidebar to look like your other sidebar widgets you can use the following function.

function widget_featured_posts() {
	$custom_loop = new WP_Query('showposts=5&category_name=Featured&orderby=rand');
	if ( $custom_loop->have_posts() ) :
		echo '<li class="widget widget_featured_posts">';
		echo '<h3>Featured Posts</h3>';
		echo '<ul>';
		while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

			echo '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';

		endwhile;
		wp_reset_query();
		echo '</ul>';
		echo '</li>';
	endif;
}
add_action('thesis_hook_before_sidebar_1','widget_featured_posts');

The function has the widget code and a heading added to match the HTML format of widgets in Thesis.

How about using thumbnails instead of post titles?

Using thumbnails is a bit more attractive and intriguing than a list of post titles (not that a good post title can’t pull people in). If you use Thesis you should know about Post Images and Thumbnails; if you don’t please watch the in-post options video!

There’s a nice little snippet of code that you can use (inside the loop) to fetch the thesis post image or thumbnail:

$post_image = thesis_post_image_info('thumb');
echo $post_image['output'];

Use this in your custom loop like so.

function custom_featured_posts() {
	$custom_loop = new WP_Query('showposts=5&category_name=Featured&orderby=rand');
	if ( $custom_loop->have_posts() ) :
		echo '<strong>Featured Posts</strong>';
		echo '<ul class="featured_posts">';
		while ( $custom_loop->have_posts() ) : $custom_loop->the_post();

			$post_image = thesis_post_image_info('thumb');
			echo '<li>' . $post_image['output'] . '</li>';

		endwhile;
		wp_reset_query();
		echo '</ul>';
	endif;
}
add_action('thesis_hook_after_post','custom_featured_posts');

$post_image['output'] has the whole linked image markup with classes etc. If you just want to fetch the thumbnail URL to add your own HTML around it, use $post_image['url'].

The following CSS (to be placed in custom.css) will cause the thumbnails to be displayed horizontally next to each other.

ul.featured_posts {list-style:none;}
	ul.featured_posts li {float:left;}

A related posts query

There are several ways to determine if a post is related to another post, without getting too crazy with it, the simplest and most obvious attributes to use are categories and tags. If you haven’t been using categories and tags on your blog I would say to find a plugin that uses other means to determine relatedness, and don’t try to write your own related posts query (if you’re able to write one not based on categories and tags you probably don’t need this tutorial anyway!).

function custom_related_posts() {
global $post;
if ( is_single() ) :
	//stores the original post data
	$original_post = $post;

	//get the post category
	$category = get_the_category();
	$cat = $category[0]->cat_ID;

	//gather a list of tags
	$tags = wp_get_post_tags($post->ID);
		$taglist = '';
		if ($tags) {
			foreach ($tags as $tag) {
				$taglist .= $tag->term_id . ',';
			}
			//start loop and query stuff
			$args = array(
				'cat' => $cat,
				'tag__in' => array($taglist),
				'post__not_in' => array($post->ID),
				'showposts'=> 5,
				'caller_get_posts'=> 1
			);
			$related_posts = new WP_Query($args);
			if ( $related_posts->have_posts() ) :
				echo '<ul class="related_posts">';
				while ( $related_posts->have_posts() ) : $related_posts->the_post();

					$post_image = thesis_post_image_info('thumb');
					echo '<li><a class="post_image_link" href="' . get_permalink() . '" title="Permanent link to ' . get_the_title() . '">' . $post_image['output'] . '</a></li>';

				endwhile;
				wp_reset_query();
				echo '</ul>';
			else :
				echo '<p>Sorry, no posts found</p>';
			endif;
		}
endif;
}
add_action('thesis_hook_after_post','custom_related_posts');

This adds a list of linked thumbnails of related posts to the bottom of a single post page. I’ve added a couple of comments in there to indicate what’s happening in the code.

The $args = array(... syntax is just another way of writing out the parameters to use in WP_Query(). It can be a bit easier for humans to read when using more than a few parameters to put them into an array like that.

The tag__in parameter indicates that the related post should be tagged with any (but not necessarily all) of the same tags as the current post. post__not_in is used here to exclude the current post from the query. caller_get_posts, when set to “1″, means that sticky posts are excluded.

You may notice that I’ve added a link around $post_image['output'] because the whole function will only be shown on a single page, but $post_image['output'] doesn’t output a link on single posts and pages.

Questions?

If you are not sure which WordPress tags to use in your loop or parameters in your query, please check the WordPress codex before asking here:

• Template Tags
• query_posts()
• Conditional Tags

If you need clarification on a particular bit of the code or it doesn’t work in a particular situation, please let me know and be specific. Thanks!