• wp_reset_postdata()
• wp_reset_query()
• rewind_posts()
• Quick Summary

wp_reset_postdata()

First up we have wp_reset_postdata, which restores the global $post variable to the current post in the main query. This is useful when using WP_Query to customize loops or create multiple loops on the same page. It looks like this:

<?php wp_reset_postdata(); ?>

This tag is nice and simple – it accepts no parameters and returns no values. It simply resets the post data after a custom query. So for example, let’s say we have a custom WP_Query loop in our theme’s header.php file, something like this:

$random_post = new WP_query(); 
$random_post->query('cat=3&showposts=1&orderby=rand'); 
while ($random_post->have_posts()) : $random_post->the_post(); 
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($random_post->ID, 'featured', true); ?>">
</a>
endwhile;

This would display a random post in the header, but it will also change the main query object for any other loops on the page. Without the original query data available, the main posts loop contained in, say, index.php may produce unexpected results. Fortunately, we can use wp_reset_postdata to restore the query object to its original state.

To use wp_reset_postdata, just place after your custom loop(s). Here is our previous example with wp_reset_postdata to reset the loop:

$random_post = new WP_query(); 
$random_post->query('cat=3&showposts=1&orderby=rand'); 
while ($random_post->have_posts()) : $random_post->the_post(); 
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($random_post->ID, 'featured', true); ?>">
</a>
endwhile;
wp_reset_postdata();

When to use: best used after custom or multiple loops created with WP_Query.

wp_reset_query()

Next up we have the wp_reset_query function, which resets the query used with custom loops. It’s a simple function that accepts no parameters and returns no values. It looks like this:

<?php wp_reset_query(); ?>

Specifically, this function was created to prevent issues with query_posts, as indicated for the function in the wp-includes/query.php file:

/**
 * Destroy the previous query and set up a new query.
 *
 * This should be used after {@link query_posts()} and before another {@link
 * query_posts()}. This will remove obscure bugs that occur when the previous
 * wp_query object is not destroyed properly before another is set up.
 *
 * @since 2.3.0
 * @uses $wp_query
 */

Looking at the wp_reset_query function in query.php, we see that it uses the adjacent wp_reset_postdata function to restore the global $post variable to the current post in the main query:

// destroy and reset the query
function wp_reset_query() {
	unset($GLOBALS['wp_query']);
	$GLOBALS['wp_query'] =& $GLOBALS['wp_the_query'];
	wp_reset_postdata(); // <-- RESET QUERY
}

// restore the query
function wp_reset_postdata() {
	global $wp_query;
	if ( !empty($wp_query->post) ) {
		$GLOBALS['post'] = $wp_query->post;
		setup_postdata($wp_query->post);
	}
}

So both wp_reset_query() and wp_reset_postdata() reset the query object by restoring the global $post variable, but wp_reset_query takes it a step further and actually destroys the previous query before doing so. This is important when using query_posts(), as seen in the following example:

<?php query_posts('posts_per_page=3');
if (have_posts()) : while (have_posts()) : the_post(); ?>

<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>

<?php endwhile; endif; ?>
<?php wp_reset_query(); ?>

When to use: best used after a query_posts loop to reset things after a custom query.

rewind_posts()

Last but not least, we have the rewind_posts function, which basically does what it says: rewinds the loop so you can re-use the same query. The function accepts no parameters, returns no values, and looks like this when used in your theme files:

<?php rewind_posts(); ?>

So to understand when to use rewind_posts(), let’s say we want to use the same query in two different locations on the page. We want to display post titles in the first loop and post content in the second loop. To re-use the same posts, we include rewind_posts after the first loop, like so:

if (have_posts()) : while (have_posts()) : the_post(); ?>
<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
<?php endwhile; endif; ?>

<?php rewind_posts(); ?>

<?php while (have_posts()) : the_post(); ?>
<?php the_content(); ?>
<?php endwhile; ?>

So, while wp_reset_query and wp_reset_postdata reset the entire query object, rewind_posts simply resets the post count, as seen for the function in the wp-includes/query.php file:

// rewind the posts and reset post index
function rewind_posts() {
	$this->current_post = -1;
	if ( $this->post_count > 0 ) {
		$this->post = $this->posts[0];
	}
}

When to use: best for re-using the same query on the same page.

5-second summary

Quick summary for future reference:

• wp_reset_postdata() -> best used after custom or multiple loops created with WP_Query
• wp_reset_query() -> best used after a query_posts loop to reset a custom query
• rewind_posts() -> best for re-using the same query on the same page

I hope this is a useful round-up of when & how to reset/rewind the WordPress loop. Note that the WP Codex information on these functions is kinda thin, so feel free to share any tips or examples in the comments.

© 2011 Digging into WordPress | Permalink | 11 comments | Add to del.icio.us | Post tags: loop, PHP, tips, tricks

• Default Loop
• Loop with query_posts()
• Loop with WP_Query()
• Loop with get_posts()

Each of these looping methods is useful in a variety of situations. They share a lot of the same underlying functionality, and the query parameters are essentially the same. Collectively, these four techniques enable simple loops, multiple loops, and custom loops in your WordPress theme template. A good place to find a default loop, for example, is in your theme’s index.php file. Its purpose is to loop through the posts stored in the database and echo their contents to the browser. Using WordPress’ template tags, it’s easy to display post titles, content, meta info, and much more. That said, let’s examine the four ways to loop with WordPress.

The Default Loop

The default WordPress loop looks something like this:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
		<?php the_content(); ?>
	</div>

<?php endwhile; ?>

	<div class="navigation">
		<div class="next-posts"><?php next_posts_link(); ?></div>
		<div class="prev-posts"><?php previous_posts_link(); ?></div>
	</div>

<?php else : ?>

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1>Not Found</h1>
	</div>

<?php endif; ?>

So what makes it “default”? Mostly because it uses the default query to loop through post content, making it the loop used like 99% of the time for most themes. It tells WordPress to loop through posts and display the information according to context, and as called by the various template tags (the_title, the_content, et al). There are tags available for just about any type of data stored in the database.

Based on the query that is sent, the default loop will display a certain number of posts from a certain category from a certain date, and so on. For example, the number of posts displayed in the first part of the loop is specified in the WP Admin. So if someone requests the second page of your “Awesome” category, that information is sent via the query, along with the number of posts, theme template file, and so on.

So the default loop is perfect if you’re happy with the query that is sent, but it is also possible to customize the query and generate an entirely different set of posts.

Loop with query_posts()

The query_posts function enables us to modify the query and display our desired results. We can either override the entire query or keep it around and just change a few parameters. Here’s an example where query_posts is called before the default loop to exclude a specific category:

<?php global $query_string; // required
$posts = query_posts($query_string.'&cat=-9'); // exclude category 9

<?php // DEFAULT LOOP GOES HERE ?>

<?php wp_reset_query(); // reset the query ?>

Say you have a default loop in your index.php theme template, but you want to change the number of posts, exclude two categories, and display the results in ascending order. Easy. Just add some query_posts action before the default loop and wp_reset_query immediately after, like this:

<?php global $query_string; // required
$posts = query_posts($query_string.'&posts_per_page=3&cat=-6,-9&order=ASC');

<?php // DEFAULT LOOP GOES HERE ?>

<?php wp_reset_query(); // reset the query ?>

Here we are keeping the original query around and just overriding a few parameters. There are many parameters available, so customizing any default loop is accomplished quite easily. If we wanted to completely override the original query, we would replace the second line with something like this:

$posts = query_posts('posts_per_page=3&cat=-6,-9&order=ASC');

Notice here that we’ve removed the $query_string from the query_posts parameters. This essentially erases the default query and replaces it with one that contains only those variables included in query_posts. This means no paging information will be available, so remove the original query only if you know what you’re doing.

When to use? Use query_posts to modify the type of posts that are returned for a single loop. It’s perfect for limiting the number of posts, excluding posts from a certain category or tag, and so on. If more than one loop is required, multiple query_posts loops could work, but there is a much better way to do it using WP_Query.

Loop with WP_Query()

For complete control over the customization of any number of loops, WP_Query is the way to go. When used to modify a default loop, it looks similar to query_posts. For example, let’s exclude a specific category using WP_Query:

<?php $custom_query = new WP_Query('cat=-9'); // exclude category 9
while($custom_query->have_posts()) : $custom_query->the_post(); ?>

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
		<?php the_content(); ?>
	</div>

<?php endwhile; ?>
<?php wp_reset_postdata(); // reset the query ?>

It also accepts the same parameters as query_posts, so modifying stuff like number of posts, included/excluded categories, and post order looks quite familiar. As seen in the following examples, WP_Query makes it easy to customize the loop by simply changing the parameter:

$custom_query = new WP_Query('cat=-7,-8,-9'); // exclude any categories
$custom_query = new WP_Query('posts_per_page=3'); // limit number of posts
$custom_query = new WP_Query('order=ASC'); // reverse the post order

As expected, we can combine parameters with WP_Query using the same syntax as both query_posts and get_posts. Here’s the equivalent of our query_posts example:

$custom_query = new WP_Query('posts_per_page=3&cat=-6,-9&order=ASC');

Notice, however, that with WP_Query, we don’t need the $query_string variable. In addition to using WP_Query to customize the default loop, we can also use it to create and customize multiple loops. Here is a basic example:

<?php // Loop 1
$first_query = new WP_Query('cat=-1'); // exclude category
while($first_query->have_posts()) : $first_query->the_post();
...
endwhile;
wp_reset_postdata();

// Loop 2
$second_query = new WP_Query('cat=-2'); // exclude category
while($second_query->have_posts()) : $second_query->the_post();
...
endwhile;
wp_reset_postdata();

// Loop 3
$third_query = new WP_Query('cat=-3'); // exclude category
while($third_query->have_posts()) : $third_query->the_post();
...
endwhile;
wp_reset_postdata();
?>

Each of these additional loops may be placed anywhere in your theme template – no need to line them up sequentially. For example, one loop may be placed in your sidebar, another in your footer, and so on. And with the output of each loop easily modified using any of the available parameters, any loop configuration is possible.

When to use? Use WP_Query for creating multiple, customized loops. By setting up additional instances of WP_Query in your theme, you can create any number of multiple loops, and customize the output of each.

Even so, we don’t always need to break out the big guns, sometimes we just need a few additional loops displayed around the page. So let’s put down the bazookas and gather in the garden for some get_posts tea ;)

Loop with get_posts()

The easiest, safest way to create multiple loops in your theme is to use get_posts(). Anywhere you need to display a quick, static set of posts, get_posts is the perfect choice. Think 10 recent posts in the sidebar, or 10 random posts in the footer. get_posts makes it easy. Here again is a query to exclude a specific category:

<?php global $post; // required
$args = array('category' => -9); // exclude category 9
$custom_posts = get_posts($args);
foreach($custom_posts as $post) : setup_postdata($post);
...
endforeach;
?>

This code creates a loop of all posts except those in the excluded category. Of course, excluding a category is just one way to customize your additional, static loops. By using any of the same parameters accepted by WP_Query and query_posts, it’s possible to create loops that display just about anything you want.

Notice, however, that get_posts requires the use of an array for the parameters. The format for multiple parameters looks like this (using our previous example):

$args = array('numberposts'=>3, 'category'=>-6,-9, 'order'=>'ASC');

Also notice that we’re using numberposts instead of posts_per_page to limit the number of posts. According to the WP Codex, posts_per_page should work with get_posts, but if it doesn’t just go with numberposts. There is also a showposts parameter that also seems to work fine with get_posts.

When to use? Use the get_posts() function to easily create additional, static loops anywhere in your theme. get_posts accepts the same parameters as query_posts, and is perfect for adding static, custom loops to your sidebar, footer, or anywhere else.

30-Second Summary

The bottom line for customizing default loops and creating multiple loops:

• To modify the default loop, use query_posts()
• To modify loops and/or create multiple loops, use WP_Query()
• To create static, additional loops, use get_posts()

If you’re working with WordPress loops and want to learn more about using them to customize your theme, we cover the topic extensively in our book, Digging into WordPress, which is current with WordPress 3.1 :)

© 2011 Digging into WordPress | Permalink | 31 comments | Add to del.icio.us | Post tags: loop, PHP, query_posts

The biggest reason we decided to attach post thumbnails from the beginning was that it is just an interesting bit of data to have available for every single post. It means that we could do something like display random thumbnails in the sidebar, or display thumbnails next to search results. We don’t do either of those things in this current design, but it’s always a possibility and possibilities are awesome.

Another thing that is a cool thing to build with thumbnails is unique archive views. I’ve built one for us here on Digging Into WordPress and I have some ideas for several more. Check it out:

Read on for the “how”…

1. Created a special page template

This page will be totally unique, no standard header or footer, so I made a template just for it.

<?php
/*
  Template Name: Thumb Archives - Horz
*/
?>

2. Creating a horizontal row of thumbs

One of the best ways to create long horizontal row (that breaks the width of the browser window width) is to use a table with a single row of cells. This way we don’t have to manually set the width of anything, and also don’t have to worry about things wrapping as we would if the thumbnails were inline elements or floated.

So we’ll set up a loop querying for every single post on the site (that isn’t a link-post) and spit out a table cell for each. Within that table cell, there will be an anchor link pointing to the post which contains a title, the image, and an excerpt.

<table id="archives-table">
	<tr>
		<?php query_posts('posts_per_page=-1&cat=-52'); ?>
		<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
		<td>
			<a href="<?php the_permalink(); ?>" class="article-block">
				<span class="title"><?php the_title(); ?></span>
				<img src="<?php echo get_post_meta($post->ID, 'PostThumb', true); ?>" alt="" />
				<span class="ex"><?php the_excerpt(); ?></span>
			</a>
		</td>
		<?php endwhile; endif; ?>
	</tr>
</table>

3. Dependencies

We’re going to need a unique CSS file to use for this. Since this template is completely one-off and we aren’t using the standard header, the <head> element will be right in this template. We’ll link out to our own custom CSS file, load in jQuery, and load in some plugins that will facilitate the idea I’m trying to accomplish (hoverflow and mousewheel), as well as finally our own custom JavaScript file.

<head>
  <meta charset="UTF-8" />
  <title>Thumbnail Archives | Digging Into WordPress</title>
  <link rel="stylesheet" type="text/css" media="all" href="<?php bloginfo("template_url"); ?>/css/archives-horz.css" />
  <script src='http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js'></script>
  <script src='<?php bloginfo("template_url"); ?>/js/jquery.hoverflow.min.js'></script>
  <script src='<?php bloginfo("template_url"); ?>/js/jquery.mousewheel.min.js'></script>
  <script src='<?php bloginfo("template_url"); ?>/js/weirdarchives.js'></script>
</head>

If this page was anything more than a one-off page, we should be enqueuing scripts and providing proper hooks in the header and such. I’ve specifically not done that here because this page is it’s own unique thing that I don’t want anything else intruding upon.

4. Style

The styling for page is very simple, just a repeating background image and resets. Notice on the page though that the titles and excerpts are hidden until the mouse hovers over the thumbnails. We’ll do the “hiding” by setting the opacity of the thumbnails down to zero in the CSS. We’ll also position them inset into the thumbnail a bit so they have a bit more dramatic “reveal” upon mouse hover, as they slide out and into place.

.title { bottom: 50%; }
.ex { top: 50%; font: 11px Georgia, Serif; color: #555; }
.title, .ex { background: white; width: 130px; padding: 10px; display: block; overflow: hidden; position: absolute; opacity: 0; }

5. Horizontal scrolling

With the mousewheel plugin in place, we can force the window to scroll horizontally instead of vertically with mouse scrollwheels with this:

$("body").mousewheel(function(event, delta) {
    this.scrollLeft -= (delta * 30);
    event.preventDefault();
});

6. Animation

When a thumbnail is hovered over, the title and except will show themselves and slide down. To do that, I’m using jQuery’s hover function which accepts a function to run on mouseenter and a function to run on mouseleave. For the former, an animation begins which moves the position, height, and opacity. The latter, those values are returned to how they started.

$blocks.hover(function(e) {
    var $el    = $(this),
        $title = $el.find(".title"),
        $ex    = $el.find(".ex");
    
    $title.hoverFlow(e.type, { bottom: "99%", opacity: 1, height: $title.data("origHeight") })
    $ex.hoverFlow(e.type, { top: "95.5%", opacity: 1, height: $ex.data("origHeight") });
    
}, function(e) {
    $(this)
        .find(".title").hoverFlow(e.type, { bottom: "50%", opacity: 0, height: 0 })
        .end()
        .find(".ex").hoverFlow(e.type, { top: "50%", opacity: 0, height: 0 });
});

There is a bit more to the JavaScript (but not much), feel free to poke your way around to it from the demo page to see it all.

7. More

The point of all this was to create a unique archive browsing experience based around our thumbnails. This isn’t the only way to do it. In fact I have a few other ideas I’m going to work on in time. Are they super practical? Maybe not, but they are fun!

© 2010 Digging into WordPress | Permalink | 15 comments | Add to del.icio.us | Post tags: archives, loop

1. Using CSS3 and progressive enhancement
2. Multiple columns by filtering the_content
3. More flexible multiple columns
4. Multiple loops displayed in multiple columns
5. Display your posts in horizontal display order with two columns
6. Bonus: Display your category list in two columns

1. Using CSS3 and progressive enhancement

I think the easiest way to display your content in multiple columns is to apply a little CSS3 in progressively enhancing fashion. Let’s say you have the following markup:

<div class="content">
	<p>Lorem ipsum..</p>
	<p>Lorem ipsum..</p>
	<p>Lorem ipsum..</p>
</div>

We can add the following CSS to display the content in multiple columns:

.content {
	  -moz-column-count: 3;
	  -moz-column-gap: 10px;
	  -moz-column-rule: none;
	  -webkit-column-count: 3;
	  -webkit-column-gap: 10px;
	  -webkit-column-rule: none;
	column-count: 3;
	column-gap: 10px;
	column-rule: none;
	}

This will display your content in three columns with a 10px gap between each. This technique is a great way to enhance the display of your content for people running cool modern browsers like Safari and Firefox. What about folks visiting with Internet Exploder or older browsers? They will see your content displayed in a single column, just like they would have before you applied the multiple columns. Note that you can specify any number of coulmns and any width for the gap.

2. Multiple columns by filtering the_content

If you need something a little more “universal” than what is currently available with CSS3, we can always dig into our template files, modify things at the PHP/(X)HTML level, and then style accordingly. Here is the technique provided by Kriesi.at:

function my_multi_col($content) {

	$columns = explode('<h2>', $content);
	$i = 0;

	foreach ($columns as $column) {
		if (($i % 2) == 0) {
			$return .= '<div class="content_left">'."\n";
			if ($i > 1) {
				$return .= "<h2>";
			} else {
				$return .= '<div class="content_right">'."\n <h2>";
			}
			$return .= $column;
			$return .= '</p></div>';
			$i++;
		}
		if(isset($columns[1])) {
	    		$content = wpautop($return);
		} else {
	    		$content = wpautop($content);
		}
		echo $content;
	}
}
add_filter('the_content', 'my_multi_col');

Just place that into your active theme’s functions.php file and then apply the following CSS:

.content_right, .content_left{
	float: left;
	width: 45%;
	}
.content_left{
	padding-right: 5%;
	}

Once implemented, this multi-column technique creates a a column for each instance of <h2> found within the post content. Thus, be sure to limit the number of <h2> elements to two in order to avoid layout breakage. Note that you could also modify the code to use a different element if the <h2> tag isn’t good for you. Multiple columns doesn’t get much easier, but just in case you need an alternate method for whatever reason, read on for some more great techniques.

3. More flexible multiple columns

The previous method works nice for two columns and no fuss, but for three or more columns we’re going to need something a little more robust. fortunately, Rob Searles shares a technique that allows any number of columns with completely different content in each. This technique creates columns based on multiple instances of the <!--more--> tag. There are several caveats, so check the orginal article for all the details.

Here are the steps involved in implementing this technique:

1. Add the my_multi_col_v2 function to your functions.php file
2. Add another snippet to your theme template file, for example page.php
3. Add some CSS to format the markup into columns
4. Add a couple of <!--more--> tags in your post or page to create the three columns

1. Let’s go through these steps, beginning with the main function that you should place into your theme’s functions.php file:

function my_multi_col_v2($content){
	// run through a couple of essential tasks to prepare the content
	$content = apply_filters('the_content', $content);
	$content = str_replace(']]>', ']]>', $content);
 
	// the first "more" is converted to a span with ID
	$columns = preg_split('/(<span id="more-\d+"><\/span>)|(<!--more-->)<\/p>/', $content);
	$col_count = count($columns);
 
	if($col_count > 1) {
		for($i=0; $i<$col_count; $i++) {
			// check to see if there is a final </p>, if not add it
			if(!preg_match('/<\/p>\s?$/', $columns[$i]) )  {
				$columns[$i] .= '</p>';
			}
			// check to see if there is an appending </p>, if there is, remove
			$columns[$i] = preg_replace('/^\s?<\/p>/', '', $columns[$i]);
			// now add the div wrapper
			$columns[$i] = '<div class="dynamic-col-'.($i+1).'">'.$columns[$i].'</div>';
		}
		$content = join($columns, "\n").'<div class="clear"></div>';
	}
	else {
		// this page does not have dynamic columns
		$content = wpautop($content);
	}
	// remove any left over empty <p> tags
	$content = str_replace('<p></p>', '', $content);
	return $content;
}

2. Once that’s in place, replace your the_content() tag with the following code:

$content = get_the_content('',FALSE,''); // arguments remove 'more' text
echo my_multi_col_v2($content);

3. The last bit of code that we need to setup is the CSS to make it all sweet:

/* dynamic columns */
div.dynamic-col-1 { float: left; width: 38%; padding-right: 2%;}
div.dynamic-col-2 { float: left; width: 38%;padding-right: 2%;}
div.dynamic-col-3 { float: left; width: 20%;}
div.clear { clear: both; }

4. And last but not least, remember to add the two <!--more--> tags in your post/page content to create the three columns.

That’s all there is to it. Pretty good stuff, but even so, there are even more alternatives available. next we’ll look at a technique for displaying multiple loops in multiple columns.

4. Multiple loops displayed in multiple columns

Not too long ago, I wrote a post at Perishable Press explaining how to display multiple loops with multiple columns. The final product will look display something like this:

• First column, first loop: display posts #1-5
• Second column, second loop: display posts #6-10
• Third column, third loop: display posts #11-15

Using WordPress and a little CSS, this configuration is relatively easy to accomplish. Let’s cut right to the chase..

Step 1: Setup the multiple loops

The first thing we want to do is replace the standard WordPress loop with the following code:

// FIRST LOOP: display posts 1 thru 5
<?php query_posts('showposts=5'); ?>
<?php $posts = get_posts('numberposts=5&offset=0'); foreach ($posts as $post) : start_wp(); ?>
<?php static $count1 = 0; if ($count1 == "5") { break; } else { ?>

<?php the_title(); ?>
<?php the_content(); ?>

<?php $count1++; } ?>
<?php endforeach; ?>


// SECOND LOOP: display posts 6 thru 10
<?php query_posts('showposts=5'); ?>
<?php $posts = get_posts('numberposts=5&offset=5'); foreach ($posts as $post) : start_wp(); ?>
<?php static $count2 = 0; if ($count2 == "5") { break; } else { ?>

<?php the_title(); ?>
<?php the_content(); ?>

<?php $count2++; } ?>
<?php endforeach; ?>


// THIRD LOOP: display posts 11 thru 15
<?php query_posts('showposts=5'); ?>
<?php $posts = get_posts('numberposts=5&offset=10'); foreach ($posts as $post) : start_wp(); ?>
<?php static $count3 = 0; if ($count3 == "5") { break; } else { ?>

<?php the_title(); ?>
<?php the_content(); ?>

<?php $count3++; } ?>
<?php endforeach; ?>

That’s the juice right there. We have three loops, each displaying five posts. The first loop displays the first five posts, the second loop displays the next five posts, and the third loop displays the next five posts. Thus, this multiple-loop configuration displays the most recent 15 posts, each of which being unique. See the original post for more information, options and details.

Step 2: Markup your theme template file(s)

Now that we have the PHP in place, we are ready to add the (X)HTML markup required for the final three-column configuration. There are many ways to accomplish this, this is merely one of them:

<div id="column_01">

	<!-- FIRST LOOP -->

</div>

<div id="column_wrap">

	<div id="column_02">

		<!-- SECOND LOOP -->

	</div>
	<div id="column_03">

		<!-- THIRD LOOP -->
	
	</div>

</div>

Here, each of the three loops will be placed into its own div, which then will be styled with a little CSS to transform it into one of the three columns. Note that you may want to change the id names of the divisions to better represent the particular semantics of your document. Now let’s move on to the CSS..

Step 3: Styling the columns with CSS

The final step in the tutorial is to style the markup with CSS. Nothing too fancy, really. Creating the columns is merely a matter of floating the individual divs and applying a width to each of them:

/* three column layout */
div#column_01 {
	float: left;
	clear: none;
	width: 30%;
	}
div#column_wrap {
	float: right;
	clear: none;
	width: 60%;
	}
	div#column_02 {
		float: left;
		clear: none;
		width: 45%;
		}
	div#column_03 {
		float: right;
		clear: none;
		width: 45%;
		}

The trick here is to use width values that will create the correct column widths. The values used in the example produce three columns of approximately equal width. Again, for more information on the details of this technique, see the original post.

Once you get everything setup, your posts should display your multiple-loop content in multiple columns, with each column showing the contents of a different loop. This is a great way to customize your theme, making it possible to present lots of disparate information within an easy-to-understand layout. Even so, this technique may not do it for you either. If so, we’ve got a couple more WordPress tricks up our sleeve!

5. Display your posts in horizontal display order with two columns

That’s a mouthful, isn’t it? What we’re doing in this section is changing the order in which your two-column posts appear on the page. Typically, your two-column layout displays posts like this:

Post #1   |   Post #4
Post #2   |   Post #5
Post #3   |   Post #6
 .        |    .
 .        |    .
 .        |    .

All of the multi-column methods we’ve discussed so far result in this sort of post-display order. So now we want to change things up a bit and display our two-column posts in horizontal display order, like so:

Post #1   |   Post #2
Post #3   |   Post #4
Post #5   |   Post #6
 .        |    .
 .        |    .
 .        |    .

How is this accomplished? As explained in my horizontal-display tutorial, this is easily accomplished using two default loops and the rewind_posts() function. The first loop will display the posts in the first column, while the second loop will display the posts in the second column. To do this, we use PHP’s modulus operator to filter out every other post from the first loop, which will display posts in horizontal order.

To make this happen, first replace your default WordPress loop with the following code:

<?php if (have_posts()) : while(have_posts()) : $i++; if(($i % 2) == 0) : $wp_query->next_post(); else : the_post(); ?>

<div id="left-column">
<h1><?php the_permalink(); ?></h1>
<?php the_content(); ?>
</div>

<?php endif; endwhile; else: ?>
<div>Alternate content</div>
<?php endif; ?>

<?php $i = 0; rewind_posts(); ?>

<?php if (have_posts()) : while(have_posts()) : $i++; if(($i % 2) !== 0) : $wp_query->next_post(); else : the_post(); ?>

<div id="right-column">
<h1><?php the_permalink(); ?></h1>
<?php the_content(); ?>
</div>

<?php endif; endwhile; else: ?>
<div>Alternate content</div>
<?php endif; ?>

With that code in place, oddly numbered posts will appear within a division identified with an attribute of id="left-column". Likewise, even-numbered posts will appear within a division identified with an attribute of id="right-column". Thus, we may apply the following CSS to position the divisions as two adjacent columns:

div#left-column {
	width: 333px;
	float: left;
	clear: none;
	}
div#right-column {
	width: 333px;
	float: right;
	clear: none;
	}

Of course, when it comes to configuring the WordPress loop and styling your page with CSS,
anything is possible. Feel free to experiment and adapt this technique to suit your own diabolical purposes ;) As with the other methods described in this DiW post, much more information is available for this technique at the original article, including a nice, CSS-only method that is sure to leave you breathless.

6. Bonus: Display your category list in two columns

Using a little PHP magic, we can get WordPress’ wp_list_categories() to display our categories in two columns. As Blog Oh Blog explains, all you need is the following code placed in your theme file:

<?php // display categories in two columns
$cats = explode('<br />', wp_list_categories('title_li=&echo=0&depth=1&style=none'));
$cat_n = count($cats) - 1;
for ($i = 0; $i < $cat_n; $i++):
	if ($i < $cat_n/2):
		$cat_left = $cat_left.'<li>'.$cats[$i].'</li>';
	elseif ($i >= $cat_n/2):
		$cat_right = $cat_right.'<li>'.$cats[$i].'</li>';
	endif;
endfor; ?>

<ul class="left">
	<?php echo $cat_left; ?>
</ul>
<ul class="right">
	<?php echo $cat_right; ?>
</ul>

Just use that code where you would like the categories to appear and enjoy the results.

Wrapping it up

Hopefully these techniques will inspire and enable you to break out of the “single-column” mindset and explore some multi-column possibilities. Using multiple columns for your content is a great way to enhance the visual appeal of your design and readability of your content.

There is SO much you can do with WordPress, PHP, (X)HTML, and CSS. The possibilities are endless indeed. The multiple-column techniques presented in this article provide a great starting point for creating more elaborate and sophisticated page layouts. So experiment, have fun, and be safe!!

© 2010 Digging into WordPress | Permalink | 30 comments | Add to del.icio.us | Post tags: CSS, loop, PHP, posts

Hence, the Custom Query Shortcode!

This is basically how I wanted it to work. You have a shortcode with one single parameter called “query”. (Remember, shortcodes are those things in brackets you can use in the body of Pages/Posts that do special stuff). In the “query” parameter, you literally enter exactly what you would enter for a query when using the query_posts() function. In other words:

[loop query=""]

You can pass whatever query you want to it. For example, let’s say you wanted to query for 20 Pages that were the child of a specific page and list them in Ascending order:

[loop the_query="showposts=20&post_type=page&post_parent=453&ord=ASC"]

What it returns

This is totally customizable in the function itself, but I made the judgement call for myself that it would return list items with linked post titles inside. So you’d go like this:

<ul>
[loop query="posts_per_page=3"]
</ul>

and you’d get:

<ul>
<li><a href="http://digwp.com/post-1/">Post 1</a></li>
<li><a href="http://digwp.com/post-2/">Post 2</a></li>
<li><a href="http://digwp.com/post-3/">Post 3</a></li>
</ul>

And of course those would be real URL’s and real Post titles…

The Code

This would go in your themes functions.php file. Now that I’m thinking more clearly about it, this probably makes more sense to be a plugin since it probably shouldn’t be theme-dependant, but oh well, we can do that another day.

function custom_query_shortcode($atts) {

   // EXAMPLE USAGE:
   // [loop the_query="showposts=100&post_type=page&post_parent=453"]
   
   // Defaults
   extract(shortcode_atts(array(
      "the_query" => ''
   ), $atts));

   // de-funkify query
   $the_query = preg_replace('~&#x0*([0-9a-f]+);~ei', 'chr(hexdec("\\1"))', $the_query);
   $the_query = preg_replace('~&#0*([0-9]+);~e', 'chr(\\1)', $the_query);

   // query is made               
   query_posts($the_query);
   
   // Reset and setup variables
   $output = '';
   $temp_title = '';
   $temp_link = '';
   
   // the loop
   if (have_posts()) : while (have_posts()) : the_post();
   
      $temp_title = get_the_title($post->ID);
      $temp_link = get_permalink($post->ID);
      
      // output all findings - CUSTOMIZE TO YOUR LIKING
      $output .= "<li><a href='$temp_link'>$temp_title</a></li>";
          
   endwhile; else:
   
      $output .= "nothing found.";
      
   endif;
   
   wp_reset_query();
   return $output;
   
}
add_shortcode("loop", "custom_query_shortcode");

Credit

When I first wrote this up to use, it totally didn’t work. I couldn’t figure it out… the query was getting passed over just fine, and if I hard coded the query, the whole thing would work just fine. It turns out that because the shortcode lived inside the content of a Post/Page, the ampersand characters in the query were getting encoded, and thus screwing up the query.

Dan Smith had the genius idea to use html_entity_decode() on the query before using it in query_posts(), but for some reason I couldn’t get it to take.

Roger Stringer coded up the solution with regular expressions you see above. Thanks guys!

© 2010 Digging into WordPress | Permalink | 10 comments | Add to del.icio.us | Post tags: functions, loop, shortcode

But what if you want to display different numbers of posts for different types of page views? For example, instead of showing just ten posts on your search-results pages, you may want to show a whole bunch, like maybe fifty or something. Perhaps you would also like to limit the number of posts displayed on your category archives to only five. Of course, many of us know the easy way to do this: install Custom Query String or Custom Post Limits, tweak a few settings, and call it good. But.. this does require commitment to yet another plugin, which is a good reason for doing things the “hard” way..

Method 1

Fortunately, we can account for the latter scenario without relying on a plugin. Normally, the loop controls the number of posts displayed via the while(have_posts()) condition, as shown in this extremely boring example of a typical loop:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php endwhile;?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; ?>

What’s happening here is that we are running the loop only if we have posts, and only while the number of posts is less than or equal to the amount specified in the Admin area. Thus, limiting the number of posts is simply a matter of replacing “while(have_posts())” with something more restrictive.

There are probably a zillion ways of doing this, but the easiest that I have found is to simply setup a counter variable to keep track of each iteration of the loop. Once the counter variable reaches the specified value, the loop stops. Here’s the previous example loop showing the required modifications:

<?php $i = 1; while (have_posts() && $i < 6) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php $i++; endwhile; ?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; ?>

Notice that in the first line we are initiating the counter variable “$i” and then setting its limit at “6”. We also add “$i++;” before the “endwhile” statement to increase the count by one for each iteration of the loop. The result of these modifications is that the loop will now run only five times (as specified in the first line) instead of ten times (as specified in the WordPress Admin).

Just keep in mind that this trick only works when you want to limit the total number of posts displayed on a particular page. Even so, it is still possible to avoid a plugin by setting your default post display to something high, like 20 or 30. Then, your blog displays the highest number of posts where you want them, and everything less is customized by limiting this default number with a couple lines of code. This technique could also be useful for designing themes that required a specific number of posts displayed in certain areas of the blog.

Method 2

Or, you could just use query_posts to create a custom query and specify the showposts parameter with a value of “5” (or whatever number you wish). Here is what our original loop example looks like using the query_posts function:

<?php query_posts('showposts=5'); if (have_posts()) : while (have_posts()) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php endwhile;?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; wp_reset_query(); ?>

Notice the two additions to the original loop: in the first line, we added the query_posts function with the required posts_per_page parameter set to 5. Then, in the last line, we invoke the mystical powers of wp_reset_query to reset the original posts query. Resetting the query ensures that it’s available elsewhere in the template and is just good practice in general when using query_posts.

The pros of using query_posts to modify the number of posts is that you can go either way — you can either decrease or increase the total number of posts displayed on any page — no plugins necessary.

The cons of using the query_posts method mainly involve the disruption of the original wp_query object normally used to communicate parameters involving page, category, search, and other properties to the SQL query*. Avoiding this drama is one of the reasons why using a simple counter variable (as described in the first half of the post) is often the preferred method (multiple loops, anyone?).

*Note: It is possible to include this default information in the query_posts query, but doing so is a bit beyond the scope of this article.

© 2009 Digging into WordPress | Permalink | 18 comments | Add to del.icio.us | Post tags: loop, PHP, template, tips, tricks

• “Everything” feed — that would include both the main posts and the Tumblr posts
• “Articles-only” feed — that would include only the main articles and no Tumblr stuff
• “Tumblr-only” feed — that would include only the Tumblr-style posts

Overview of this tutorial

To accomplish our goals, we’ll perform the following steps:

1. Create two custom-Page templates
2. Create two Pages, one for the articles and one for the Tumblr-posts
3. Assign the custom templates to their respective Pages
4. Make sure the feeds validate and clean up theme tags

That’s the plan, now let’s dig in!

Step 1: create a couple custom-page templates

Our two custom Page-templates will contain all of the code needed to generate our two custom feeds. These two custom templates are almost identical. For the articles-only feed, we will exclude the tumblelog category from the loop, and for the tumblr-only feed, we will include only the tumblelog category.

Let’s do the articles-only Page template first. In your theme, create a new Page-template file called “articles.php” and insert the following code:

<?php 
/* 
Template Name: Articles
*/
$numposts = 10; // number of posts in feed
$posts = query_posts('showposts='.$numposts.'&cat=-1'); // replace the number 1 with the ID of your tumblelog category
$more = 1;

header('Content-Type: '.feed_content_type('rss-http').'; charset='.get_option('blog_charset'), true);
echo '<?xml version="1.0" encoding="'.get_option('blog_charset').'"?'.'>';
?>

<rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:wfw="http://wellformedweb.org/CommentAPI/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
	xmlns:slash="http://purl.org/rss/1.0/modules/slash/"
	<?php do_action('rss2_ns'); ?>
>
<channel>
	<title><?php bloginfo_rss('name'); wp_title_rss(); ?> - Article Feed</title>
	<atom:link href="<?php self_link(); ?>" rel="self" type="application/rss+xml" />
	<link><?php bloginfo_rss('url') ?></link>
	<description><?php bloginfo_rss("description") ?></description>
	<lastBuildDate><?php echo mysql2date('D, d M Y H:i:s +0000', get_lastpostmodified('GMT'), false); ?></lastBuildDate>
	<?php the_generator( 'rss2' ); ?>
	<language><?php echo get_option('rss_language'); ?></language>
	<sy:updatePeriod><?php echo apply_filters( 'rss_update_period', 'hourly' ); ?></sy:updatePeriod>
	<sy:updateFrequency><?php echo apply_filters( 'rss_update_frequency', '1' ); ?></sy:updateFrequency>
	<?php do_action('rss2_head'); ?>
	<?php while( have_posts()) : the_post(); ?>

	<item>
		<title><?php the_title_rss(); ?></title>
		<link><?php the_permalink_rss(); ?></link>
		<comments><?php comments_link(); ?></comments>
		<pubDate><?php echo mysql2date('D, d M Y H:i:s +0000', get_post_time('Y-m-d H:i:s', true), false); ?></pubDate>
		<dc:creator><?php the_author(); ?></dc:creator>
<?php the_category_rss(); ?>
		<guid isPermaLink="false"><?php the_guid(); ?></guid>
<?php if (get_option('rss_use_excerpt')) : ?>

		<description><![CDATA[<?php the_excerpt_rss() ?>]]></description>
<?php else : ?>

		<description><![CDATA[<?php the_excerpt_rss() ?>]]></description>
	<?php if ( strlen( $post->post_content ) > 0 ) : ?>

		<content:encoded><![CDATA[<?php the_content() ?>]]></content:encoded>
	<?php else : ?>

		<content:encoded><![CDATA[<?php the_excerpt_rss() ?>]]></content:encoded>
	<?php endif; ?>
<?php endif; ?>

		<wfw:commentRss><?php echo get_post_comments_feed_link(); ?></wfw:commentRss>
		<slash:comments><?php echo get_comments_number(); ?></slash:comments>
<?php rss_enclosure(); ?>
<?php do_action('rss2_item'); ?>

	</item>
	<?php endwhile; ?>

</channel>
</rss>

Alternately, you may download the two required page-template files here.

Once you have that code in place, edit the $numposts variable according to the number of articles that you would like to display in the articles-only feed. Then edit the $posts variable according to the ID of your tumblelog category. See the comments in the code for details.

That’s it for your articles-only feed. Now, for your tumblr-only feed, create another new Page-template file called “tumblelog.php” and insert the exact same chunk of code as before. The first change that we need to make for this second template is to remove the hyphen ( - ) from the $numposts variable like so:

$posts = query_posts('showposts='.$numposts.'&cat=1');

This tells WordPress to include only your tumblelog category in your tumblr-only feed. For your articles-only feed, the presence of the hyphen (negative sign, whatever) tells WordPress to exclude your tumblelog category. Simple, but effective.

The second (and final) change that we need to make for the tumblr-only template is to give it a new template name in the first line:

Template Name: Tumblelog

This will enable WordPress to distinguish between the two custom templates in the next step.

Step 2: create two Pages in the WordPress Admin

With your two custom Page-templates uploaded to your server, login to your Admin area and create two new Pages:

• Create a Page called “Articles” and assign it the “Articles” template
• Create a Page called “Tumblelog” and assign it the “Tumblelog” template

At this point, your two new custom feeds are fully functional, appearing at the following URLs:

• http://domain.tld/articles/ — articles-only feed
• http://domain.tld/tumblelog/ — tumblr-only feed

Once you have some posts in your tumblr-only category, you will see that they are excluded from the articles-only feed and appear by themselves in the tumblr-only feed. Of course, your main posts feed, located at http://domain.tld/feed/ will contain all of your posts, enabling you to offer the following feeds to your readers:

• “Everything” feed — that would include both the main posts and the Tumblr posts
• “Articles-only” feed — that would include only the main articles and no Tumblr stuff
• “Tumblr-only” feed — that would include only the Tumblr-style posts

Final step: validation and theme clean-up

Now that everything is working, you should take the time to double-check the validity of your new feeds. This will ensure that subscribers receive the correct content in the proper format. Rest assured, I have already validated the XML produced from the custom page-template, but double-checking is always a good idea in case there are any unintended side-effects from plugins, scripts and whatnot.

One of our favorite validation services is available at: http://beta.feedvalidator.org/ — go there and enter the URLs of your new feeds.

Here at DiW, we recently used this exact method to establish an articles-only feed for use at Planet WordPress. You can see that it validates quite nicely.

Finally, after setting up your custom feeds, you should go into your theme and add some nice “subscribe” links for your readers. Also want to remind you that your new feeds are in fact Pages, such that you may want to remove them from any automatic Page-listings generated by the wp_list_pages or wp_page_menu template tags. For example, you can easily exclude your two feed Pages as follows:

wp_list_pages('exclude=123,456');

Where “123” and “456” are the IDs of your Articles and Tumblelog Pages.

Wrapping it up

With the technique described in this article, you now have an easy, sure-fire way of creating custom feeds in WordPress. The code for the feed markup is highly versatile, and may be customized to suit virtually any custom-feed configuration.

© 2009 Digging into WordPress | Permalink | 7 comments | Add to del.icio.us | Post tags: feeds, functions, loop, query_posts

Random post-display functionality with lightbox-style popup image and title post link

The key to setting this up involves creating a set of custom fields for each post and then displaying the information randomly before the main post loop. Let’s begin with the custom fields.

Setting up the custom fields

If you have already been taking advantage of WordPress custom fields, then you already understand the basic idea here. For each post that you would like to have appear randomly in the header of your theme, create the following custom fields:

Custom-field data associated with each randomly displayed post

Notice that we are using relative file paths for the images. This trick ensures maximum flexibility and portability for our custom-field data. Also note the two different images we are using for each post: a full-size image that will be displayed in the lightbox popup, and a cropped or resized version of that same image for display in the random header.

Once you have associated these custom fields with a few of your posts, it is time for a little get_posts() action to display the random content in your active theme.

Editing your WordPress theme files

One of the great things about WordPress custom fields is that they enable you to display your content in just about any way imaginable. In this tutorial, we are going to display our custom-field data in the header area for every page on the site. Thus, we open our theme’s header.php file and add the following code:

<?php $random = get_posts('showposts=1&orderby=rand'); foreach($random as $post) : setup_postdata($post); ?>

<p>
	<a href="http://domain.tld<?php echo get_post_meta($post->ID, 'randomImage', true); ?>" title="<?php echo get_post_meta($post->ID, 'randomCaption', true); ?>" class="thickbox">
		<img src="http://domain.tld<?php echo get_post_meta($post->ID, 'randomBanner', true); ?>" alt="" />
	</a>
	<small><a href="http://domain.tld<?php echo get_post_meta($post->ID, 'randomLink', true); ?>"><?php echo get_post_meta($post->ID, 'randomTitle', true); ?></a></small>
</p>

<?php endforeach; ?>

As mentioned, this code goes before the normal WordPress loop and calls data from each of the five custom fields that have been added to your posts. Instead of using the more powerful query_posts() for this random post display, we use the simpler get_posts() function instead. It does everything we need while eliminating unnecessary variables and potential complications.

A few other points of interest for this WordPress snippet; notice we are setting the randomness and limiting the post display to one ( 1 ) via two parameters in the get_posts() function. Once the query has been setup, we are using the get_post_meta() tag to populate the following markup with their respective custom-field values:

<p>
	<a href="[randomImage]" title="[randomCaption]" class="thickbox">
		<img src="[randomBanner]" alt="" />
	</a>
	<small><a href="[randomLink]">[randomTitle]</a></small>
<p>

This demonstrates the incredible design flexibility enabled by WordPress custom fields. Once this code is in place, it is time to wrap things up by implementing the JavaScript-powered lightbox functionality.

Adding the JavaScript

To finish things off, let’s make that random-banner image really “pop” by implementing some JavaScript-powered lightbox functionality. As you probably know, there are many lightbox clones from which to choose, but for this tutorial we turn to Cody Lindley’s excellent Thickbox script:

ThickBox is a webpage UI dialog widget written in JavaScript on top of the jQuery library. Its function is to show a single image, multiple images, inline content, iframed content, or content served through AJAX in a hybrid modal.

Using Thickbox is so easy, it almost feels like I’m just being lazy for using it. In fact, we have already setup our WordPress code for use with Thickbox by simply adding the class="thickbox" attribute to the random-banner anchor element. The only other thing that really needs to be done is to upload the Thickbox script and accompanying CSS file to your server and link to them from the <head> section of your header.php file:

<link rel="stylesheet" href="http://domain.tld/wp-content/css/thickbox.css" type="text/css" media="screen" />
<script type="text/javascript" src="http://domain.tld/wp-content/javascript/thickbox-compressed.js"></script>

Putting it all together

Once everything is in place, your random-post gallery should be working great. To see a working example of this technique, check out the header area of Thane Champie’s Graphics Portfolio site. That particular implementation of this method features a few more bells and whistles, but the basic functionality is the same.

© 2009 Digging into WordPress | Permalink | 15 comments | Add to del.icio.us | Post tags: custom-fields, header, JavaScript, layout, lightbox, loop