Simpler tags are those functions that can be used with little or no funny business with PHP. The easy tags are generally characterized by starting with the word the.

For the most part, our arsenal of the_ template tags will do the job; but sometimes the output that WordPress provides is less flexible than we’d like. Maybe we’d want to get at the information about each post, but we’d like to make a few tactical strikes with our PHP before it’s printed.

Fortunately, WordPress provides a number of tags that retrieve, rather than simply print, post and page information (like our the_ tags). These are generally prefixed with get_. These get_ functions return strings or arrays that we can stash in a variable and manipulate. For every the_ function, there’s at least one get_ function that can do a similar job. Let’s look into how to use some of these.

Your readers often want to navigate backwards and forwards through pages of posts—especially on blog- or news-style sites, so remember to include options for pagination in your themes. In WordPress, there are a few ways to achieve this. posts_nav_link() is a single template tag that creates a pair of links allowing the user to navigate to the next or previous posts; you can use it in archive templates or single post templates. If you want to split them up on an archive page, you can use previous_posts_link() and next_posts_link() to print a link to the previous and next set of results. To split these links on a single template, previous_post_link() and next_post_link() print a link to the previous and next single post.

posts_nav_link() accepts three parameters: text to sit between the links, the text for the previous link, and the text for the next link:

<p><?php posts_nav_link(’ &bull; ’, ’Older posts’, ’Newer posts’); 
    ?>.</p>

Used on listing pages, previous_posts_link() and next_posts_link() each accept two parameters: the link text, and the number of pages on which to show the links. The default for the second parameter is 0, meaning all pages:

<p><?php next_posts_link(’Go back in time...’, 0); ?></p>
                     
                  

For single posts, previous_post_link() and next_post_link() act a little differently. They accept four parameters: a format for the link, the text of the link, whether we only want to show a post from the same category, and any categories from which we don’t want to show posts. In most cases, you can go ahead and call this without passing any parameters, but if you do have a need to fiddle with the links, you can use the %title and %link tokens to fine-tune the output. In this example, we create a link to the previous and next post, and adjust the text output accordingly:

<?php next_post_link(’Older: <strong>%link</strong>’); ?> 
<?php previous_post_link(’Newer: <strong>%link</strong>’); ?> 

We often find it’s useful to interrupt The Loop at a certain point, or to treat particular positions differently. For example, you might want to make the first post in your loop stand out more, or place an advertisement after the fifth post. You can accomplish this quite easily by introducing a counter to your loop. Every time The Loop prints out a post, we’ll increment the counter. All you need is a bit of code to check the value of the counter, and act accordingly.

In the following example, we’ll extend our simple mini loop from the previous section to show the first post’s full content, and leave the others as excerpts:

<?php if (have_posts()) : $postcounter = 1; ?>
  <h1>Latest Posts</h1>
  <ul class="mini-list">
    <?php while (have_posts()) : the_post(); ?>
      <li>
        <h2><a href="<?php the_permalink() ?>">
            <?php the_title(); ?></a> 
            <?php the_time("j M"); ?></h2>
        <p>
          <?php if ($postcounter == 1) {
                  the_content();
                } else {
                    the_excerpt();
                  } ?>
        </p>
        <p><?php the_tags( "Tagged with: ", " / ", "" ); ?> </p>
      </li>
<?php $postcounter++; ?>


…

You’ll see that we start by creating a variable, postcounter, and at the beginning we assign it a value of 1. At the end of the while loop, we increment the value of postcounter by 1. And in the middle of the loop, we check the value of postcounter and decide whether to show the excerpt (the_excerpt()), or the post’s content (the_content()).

Now, let’s put that same counter to work in the pursuit of cold hard cash: we’ll insert advertising blocks after every third post. After the end of the list items, we’ll check to see whether the value of postcounter is divisible by three, and if so, we’ll insert a subtle bit of advertising. The following example extends further on our previous one:

…

</li>
<?php 
  if (($postcounter % 3) == 0) { ?>
    <li class="break">
      <a href="http://www.example.com">Buy lots of widgets please
      </a>
    </li>
<?php  } 
$postcounter++; ?>

Let’s see how that turned out, in Figure 3.3.

Figure 3.3. Our mini loop, now with ads—we’ll be rich!

Of course, you might have better luck with raking in the cash if you use a more enticing ad from a reputable ad network, but no doubt you get the drift.

If you want to use more than one loop on a page, use the rewind_posts() function to reset The Loop’s counters to the beginning. If you forget to do so, you might find that you’re missing posts in your other loops, or experiencing funny behavior in pagination.

We learned earlier that WordPress, being a helpful type of CMS, sets up its own queries on certain pages. What happens, though, when you want to alter that behavior ever so slightly? If your goal is simply to modify what should appear in the main WordPress loop, the query_posts() function is for you. It’s a function that overrides the current page’s default loop, and it’s useful whenever you want to make some quick tweaks to the type of posts that appear.

To use it, simply call on query_posts() before your loop begins, and set up the parameters you need from the available options. For example, we often find that we want to exclude certain categories from date-based archives or the home page. We can do this by simply adjusting the query to exclude those categories’ IDs with a minus sign, like so:

<?php query_posts(’cat=-11,-8,-90’); 
if (have_posts()): while (have_posts()) : the_post(); ?>
... continue your loop as normal

To add more parameters, just pass on more of them, separated by ampersands:

<?php query_posts(’cat=-11,-8,-90&post_type=reviews&tag=action’); ?>

Once you start adding more and more criteria, it becomes a little easier to read if you express these as a longhand-style array, and then pass the array into the query_posts() function:

<?php $args = array(
        ’cat’ => ’-11,-8,-90’,
        ’post_type’ => ’reviews’,
        ’tag’ => ’action’,
        ’posts_per_page’ => 30,
        ’order’ => ’ASC’,
        ’order_by’ => ’rand’
    );    
    query_posts($args);
?>

When you’ve finished with your customized loop, it’s important to clean up after yourself, and reset the query back to normal. query_posts() modifies a lot of global variables, many of which are also in use by plugins and themes; if you neglect to reset your query once you’re done, it could have an adverse effect on plugins and the elements that assume the query has been left untouched. Overcoming it is simple—the wp_reset_query() function avoids all the drama:

    ... The Loop
<?php else: ?>
    ... the no posts message
<?php endif;
 wp_reset_query(); ?>
                     
                     
                  

The query_posts() function is great if you want to modify what happens on any given page’s default loop. When you have a need to create completely customized loops, however, we have a different tool at our disposal: get_posts().

We often find ourselves using custom loops when we want to create complex pages. For example, the ever-popular magazine-style layout frequently makes use of a number of separate loops to achieve effects such as sliders and featured posts, or formats including topical sections. In this situation, modifying the existing loop isn’t going to be enough.

For example, let’s say that we’re creating a page template that lists a particular series of posts. Each post in the series is tagged with wordpress and tutorial. We want to show the list of posts in ascending date order, so that a reader of the page knows which order to read them in.

To set up a loop that works for this scenario, we’ll first need to make a new array with all the parameters we want to use to retrieve our posts. Then, we’ll use get_posts() to create a new array of posts, tutorials, and use a foreach loop to iterate through them. By default, we’re unable to use template tags like the_content in the usual way, so the addition of the setup_postdata() function takes each post and prepares it for easier use:

<?php $args = array(
    ’numberposts’ => 30,
    ’tag’ => ’wordpress+tutorial’,
    ’order’ => ’ASC’,
    ’order_by’ => ’date’
);

$tutorials = get_posts($args);
foreach($tutorials as $post) : setup_postdata($post); ?>
    <h2><a href="<?php the_permalink(); ?>">
      <?php the_title(); ?>
      </a>
    </h2>
    <?php the_excerpt(); ?>
<?php endforeach; ?>

The WP_Query class is what’s responsible for returning the posts for a default loop, get_posts(), and query_posts(), alike; these functions call on the same class, just in different ways. Calling on it directly gets you a big object with a selection of posts, plus a good deal of information about the request itself.

If you’re a creature of habit and consistency, a big benefit of this approach is that you can instantiate a new WP_Query object and treat it just like a regular WordPress loop, but dealing with get_posts() can be a little more tricky. Most of the techniques and functions are the same as the ones you’d use when you’re manipulating a regular old loop, so it’s very easy to pick up and use this method right away. With get_posts(), you’ll find that there are a few caveats: pagination needs extra help, plugins work differently with a loop made from get_posts(), and so on.

Another benefit of the WP_Query approach is that you’ll often find it in use with plugins, especially ones that modify the WordPress back end. If you’re an aspiring plugin ninja, it’s likely you’ll deal with WP_Query often, so some consistency in how you retrieve content is handy to have.

It’s still okay to use get_posts() to grab simpler lists of posts—in fact, it’s been a popular method for so long that it will probably be around for a little while yet—but the ease of dealing with the WP_Query object directly makes it a great choice overall. You may find that you never need to worry about using get_posts() at all!

Let’s look at how easy it is to deal with a WP_Query object. In this example, we’re creating a similar loop to the one in the previous section, showing our WordPress tutorial series in chronological order—this time, using the WP_Query method. Before we begin, we’ll put the existing query in a new variable for safekeeping:

<?php
$original_query = $wp_query;
$wp_query = null;

$args = array(
    ’numberposts’ => 30,
    ’tag’ => ’wordpress+tutorial’,
    ’order’ => ’ASC’,
    ’order_by’ => ’date’,
    ’paged’ => $paged
    );
$wp_query = new WP_Query($args);
?>

With us so far? Now that we’ve stashed the old query away and set up our new one, we can start using the new query in a loop:

<?php if ($wp_query->have_posts()): ?>
<?php while ($wp_query->have_posts()) : $wp_query->the_post(); ?>
  <h2><a href="<?php the_permalink(); ?>">
      <?php the_title(); ?>
    </a>
  </h2>
  <?php the_excerpt(); ?>
<?php endwhile; else: ?>
    ... something to show if there were no posts
<?php endif; ?>

When you’re finished playing with your WP_Query object, it’s time to return everything to how you found it. We’ll put the contents of $original_query back into $wp_query, and ensure everything’s back to normal by using the wp_reset_postdata() function. This function uses the page’s POST data to restore the post global variable to its original state:

<?php
  $wp_query = $original_query;
  wp_reset_postdata();
?>