• posts_nav_link() – for navigating various archive (non-single) pages
• previous_post_link() & next_post_link() – for navigating single-post pages

These template tags output the HTML markup required to create the actual hyperlinks that will appear on your web pages. By default, navigation links for single pages display the title of adjacent posts, while those for archive pages display “Next-Page” and “Previous-Page”.

Of course, the default text, link-position, and just about everything else can be customized and optimized according to your specific needs.

Normally, WordPress’ navigational template tags appear within the loop:

<?php get_header(); ?>

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

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

	<?php endwhile; ?>

		<p class="nav"><?php posts_nav_link(); ?></p>

	<?php else : ?>

		<h1>Nothing Found</h1>
		<p>Please try a little harder next time..</p>

	<?php endif; ?>

<?php get_footer(); ?>

This code is typical for index.php and other “Archive-View” pages, such as for Categories, Tags, Search Results, and so on. Similar code is used for Single Page-Views, where single.php would replace the posts_nav_link() ¹ template tag for previous_post_link() and next_post_link() tags.

The navigational template tags are generally placed between the endwhile and else ² statements, along with stuff like post comments, meta information, and social-media links. Within this section of the loop, code is processed only once, as opposed to multiple times in the first part of the loop.

Navigation outside of the loop

The good news is that the template tag for archive-view navigation (i.e., non-single pages) seems to work just fine outside of the loop. So you can just place posts_nav_link() anywhere within your theme template.

Then, to include single-view navigation outside of the loop, we can use query_posts to substantiate the loop anywhere within your single.php file. Here is a simplified version of the code that I am using at Perishable Press:

<?php $posts = query_posts($query_string); if (have_posts()) : while (have_posts()) : the_post(); ?>

	<?php previous_post_link(); ?> | <?php next_post_link(); ?>

<?php endwhile; endif; ?>

That’s all there is to it, really. A nice trick to have in the hat. Then, we can take it a step further and consolidate both types of page navigation (single and archive) in a single chunk of code:

<?php if(is_single()) { // single-view navigation ?>

	<?php $posts = query_posts($query_string); if (have_posts()) : while (have_posts()) : the_post(); ?>

		<?php previous_post_link(); ?> | <?php next_post_link(); ?>

	<?php endwhile; endif; ?>

<?php } else { // archive view navigation ?>

		<?php posts_nav_link(); ?>

<?php } ?>

This code displays the appropriate template tags for both single-page-views and archive-views. If placed in its own file named “nav.php”, including it within your theme files is as simple as a template tag:

<?php include_once("nav.php"); ?>

That’s an easy way to get your Next/Previous page navigation working anywhere outside the loop. This could easily be made into a custom function for your theme’s functions.php file. Or maybe even a plugin..? ;)

For more information on WordPress Page Navigation, check out these fine DiW articles:

• Definitive Guide to WordPress Page Navigation
• Optimizing WordPress Post Navigation

© 2010 Digging into WordPress | Permalink | 15 comments | Add to del.icio.us | Post tags: navigation, posts, tips, tricks

• Index and archive navigation: posts_nav_link()
• Index and archive navigation: previous_posts_link() and next_posts_link()
• Single-view posts navigation: previous_post_link() and next_post_link()

Without repeating ourselves, suffice it to say that previous_posts_link and next_posts_link are perfect for setting up separate links for index, category, and archive pages. Likewise, previous_post_link and next_post_link are perfect for setting up separate links for single-view post navigation.

Now that we’re on the same page, so to speak, let’s look at how these tags are typically used and how to improve and optimize their functionality..

Improving the next_posts_link and previous_posts_link (for archive views)

Here are the archive/category navigation links as provided in the default theme that is packaged with WordPress:

<div class="navigation">
	<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
	<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
</div>

Functionally, this setup works great — the previous-post link is displayed only when there are previous posts, and likewise the next-post link is displayed only when there are newer posts. As convenient as this is, it doesn’t help us with the accompanying markup used to display the links. Any CSS styles applied to the <div>s in our example will be displayed even when the links themselves aren’t displayed. This can result in several issues, including:

• Padding and margins may prevent proper display when links are missing
• Background images used to enhance the navigational links will still be displayed
• Additional text and/or characters will still be displayed even when links absent
• Use of any markup other than <div>s may result in validation errors when left empty

And we’re not just talking about the front page and last page here — any category, tag, search, date, or author archive will also display botched navigational elements and design flaws when previous and next posts are unavailable. Your main index may always have previous posts, but what about that guest author archive, 2005 archive, and search results? Such pages are frequently one of a kind. Even worse, by defualt, your Home page will never have a page after it, which means a broken navigational element right there on the most important page of your site. Not good.

The easiest way that I have found to prevent this from happening when the “next” link is not generated is to simply test the $paged variable for a value greater than 1:

<?php if ($paged > 1) { ?>

	<div class="navigation">
		<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
		<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
	</div>

<?php } ?>

By checking if there are more posts to display before calling the navigational code, this technique will prevent empty elements from wrinkling your home page and archive pages. Another way of doing this is shared by Eric Martin. Just place this snippet into your active theme’s functions.php file:

// return TRUE if more than one page exists
function show_posts_nav() {
	global $wp_query;
	return ($wp_query->max_num_pages > 1);
}

And then use the function to conditionally display navigational code in your archive.php and other archive-view template files:

<?php if (show_posts_nav()) : ?>

	<div class="navigation">
		<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
		<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
	</div>

<?php endif; ?>

Not sure if there is any benefit to adding the extra code in the functions.php file, but I thought I would share that technique with you as another possible solution (hey you never know).

Also, a great way to improve the functionality and presentation of your blog is to provide some alternate navigational elements to help keep things flowing and balanced on the front pages of your site. For example, at Perishable Press, if the “next” link isn’t displayed, I provide a link to my site Archives:

<?php if ($paged > 1) { ?>

	<div class="navigation">
		<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
		<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
	</div>

<?php } else { ?>

	<div class="navigation">
		<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
		<div class="alignright"><a href="http://perishablepress.com/press/archives/">Site Archives &raquo;</a></div>
	</div>

<?php } ?>

And of course, anything is possible here; the key is to keep things consistent, logical, and well-styled. Now let’s see how to improve navigational display for single-post views.

Improving the next_post_link and previous_post_link (for single views)

Fortunately, the situation is much improved for single-post navigation. By default, the next_post_link and previous_post_link provide parameters that enable us to avoid the “empty-element” syndrome. Let’s take a look at these parameters:

<?php next_post_link('format','link','in_same_cat','excluded_categories'); ?>
<?php previous_post_link('format','link','in_same_cat','excluded_categories'); ?>

The format and link parameters enable us to do something like this:

<div class="navigation">

	<?php previous_post_link('<div class="alignleft">Previous entry: %link</div>', '%title'); ?>
	<?php next_post_link('<div class="alignright">Next entry: %link</div>', '%title'); ?>

</div>

Here we have replicated the markup in our previous examples, but have done so conditionally, such that the markup will only be displayed when the corresponding link is displayed, thereby enabling us to avoid empty elements when either the previous or next post-link is not displayed. As you can see, the single-post nav tags enable us to include the surrounding (X)HTML and text within the function itself. We can do similar tricks with the actual link title. Check out our definitive guide to post navigation for more information.

Conditional navigational display for single posts

Just as we did with the archive nav tags (next_posts_link and previous_posts_link), we can implement some conditional functionality to display alternate navigational links when viewing the first and last posts in any archive view. For example, if I also wanted to provide a link to my Site Archives when the “next” and/or “previous” links were not displayed, I could do so using the following code:

<div class="navigation">

	<?php previous_post_link('<div class="alignleft">Previous entry: %link</div>', '%title'); ?>
	<?php if(!get_adjacent_post(false, '', true)) { 
		echo '<div class="alignleft"><a href="http://perishablepress.com/press/archives/">Site Archives</a></div>'; 
	} ?>

	<?php next_post_link('<div class="alignright">Next entry: %link</div>', '%title'); ?>
	<?php if(!get_adjacent_post(false, '', false)) { 
		echo '<div class="alignright"><a href="http://perishablepress.com/press/archives/">Site Archives</a></div>'; 
	} ?>

</div>

Here we are using the get_adjacent_post function to determine whether or not there is a post before/after the current post. This enables us to conditionally display some sort of fallback navigation in the first- and last-post case. The get_adjacent_post tag accepts the following parameters:

• $in_same_cat – specifies whether or not the adjacent post should be in the same category
• $excluded_categories – a comma-delimited list of categories for which the adjacent post should not belong
• $previous – specifies whether the previous post should be displayed

That does it for the single-post views. Let’s wrap things up with a way to consolidate and streamline the single and archive navigational methods..

Optimize your theme’s navigational code

Finally, here is a nice way to clean up your theme files and source code. The first step is to streamline production by getting more fine-grained with includes. This basically means that you can clean things up and save time/effort by moving your navigational code to its own file, named something like “navigation.php” or similar. You would then remove your nav code from your other template files and consolidate them all into that one location. You would then include navigation.php in any theme file where you want the navigation section to appear:

<?php include_once("navigation.php"); ?>

This technique makes maintaining and modifying your code a breeze. And, you can even streamline things further by using some conditional logic to display either archive or single navigation depending on the current page being viewed:

<?php if (is_single()) : ?>

	<div class="navigation">
		<?php previous_post_link('<div class="alignleft">Previous entry: %link</div>', '%title'); ?>
		<?php next_post_link('<div class="alignright">Next entry: %link</div>', '%title'); ?>
	</div>

<?php else : ?>

	<div class="navigation">
		<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
		<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
	</div>

<?php endif; ?>

This is a great way of staying organized and reducing your workload during theme development and maintenance.

Wrap up

The tips and tricks in this article will help you create a consistent, logical, and design-friendly set of navigational links for your next theme design. In the process, you can also streamline production by consolidating your code into a single file and using conditional logic to deliver the appropriate code.

© 2009 Digging into WordPress | Permalink | 10 comments | Add to del.icio.us | Post tags: navigation, optimization, posts

When used properly, these page-navigation template tags enable your visitors to browse your site quickly and easily. Unfortunately, these different template tags have similar names, parameters, and functionality, thereby leaving many WordPress designers dazed and confused.

In this DiW article, we’ll dig into each of these different navigational tags and explain each of them in-depth, with plenty of juicy examples to help you take advantage of their full functionality.

Here are the three sets of template tags we’ll be exploring (click on a tag name to jump to that section):

• Index and archive navigation: posts_nav_link()
• Index and archive navigation: previous_posts_link() and next_posts_link()
• Single-view posts navigation: previous_post_link() and next_post_link()

posts_nav_link() — paired links for index, category, and archive pages

[ ↑ ] The posts_nav_link() template tag provides a combined pair of “next” and “previous” navigational links for any type of paged archive view. Basically, this tag creates paired navigational links for anything other than single-post views. This includes index, category, archive, tag, and search pages. Best results when used either before or after the loop. Here is an example of the tag showing its three accepted parameters:

<?php posts_nav_link('sep','prelabel','nxtlabel'); ?>

Default usage

Here is the default usage of this template tag, followed by its corresponding output:

<?php posts_nav_link(); ?>

« Previous Page — Next Page »

Parameters

Values for each of the following parameters are strings that may be specified in alphanumeric characters or (X)HTML markup:

<?php posts_nav_link('sep','prelabel','nxtlabel'); ?>

• sep — text/markup that is displayed between the links
• prelabel — text/markup that is used as the link text for the previous page
• nxtlabel — text/markup that is used as the link text for the next page

Caution: it’s all backward

Keep in mind that the default implementation of the posts_nav_link() template tag generates links that are essentially backward in order: the “Previous Page” navigation link points to newer posts, while the “Next Page” navigation link points to older posts. Exactly the opposite of what you would expect. Normally, previous posts are older and next posts are newer. To fix this backward behavior, we could simply customize the link text of either navigation link like so:

<?php posts_nav_link(' &bull; ','&laquo; Go forward in time','Go back in time &raquo;'); ?>

This would then generate the following links on your archive pages:

« Go forward in time • Go back in time »

This reflects reality to a greater degree, however the links still seem to appear out of order. It just seems counter-intuitive to have the “Go forward” link on the left side of the page and the “Go back” link on the right side of the page. It seems more intuitive and natural to assume the reverse, link left to go back and link right to go forward. Just like reading a book.

Fortunately, there are two ways to get the links to appear in the reverse (i.e., correct) order. Both methods require us to separate the navigational links so that they may be repositioned with the “Go back” link on the left side of the page and the “Go forward” link on the right. How we go about separating the links depends on the template tag that is used. There is a workaround the posts_nav_link() tag, but it is far easier to simply use the previous_posts_link() and next_posts_link() tags instead. We’ll get to the easy way in the next section; for now, let’s look at the workaround for the posts_nav_link() tag.

To separate the navigational links created by the posts_nav_link() tag, we use two instances of it on the page. In the first instance, we kill the “Go forward” link, and in the second instance we kill the “Go back” link. The result is the following code, which provides us with two properly identified navigation links that may be situated in the correct order:

<?php posts_nav_link('','','Go back in time &raquo;'); ?> &bull; <?php posts_nav_link('','&laquo; Go forward in time',''); ?>

Perhaps the best way to understand this technique is to sequentially test each of the following navigation templates. Along the way, keep an eye on where the links are appearing on the page and where the links are pointing:

<?php posts_nav_link(); // default tag ?>

<?php posts_nav_link(' &bull; ','&laquo; Go forward in time','Go back in time &raquo;'); // switched text ?>

<?php posts_nav_link('','','Go back in time &raquo;'); ?> &bull; <?php posts_nav_link('','&laquo; Go forward in time',''); // switched text and reversed order ?>

“And that’s all I have to say about that,” as the man once said. Let’s break out of this nightmare and move on to some fresh examples.

Examples

Here are some examples to demonstrate the use and flexibility of the posts_nav_link() template tag:

Your basic navigation

Out of the box, the posts_nav_link() template tag displays your navigation links in reverse order, but you can still customize the text to make things a little clearer for your readers. One of the benefits of sticking with the default busted configuration is that you will never have to deal with empty markup elements that may appear when there are no newer or older posts to display. If squeaky-clean source code tickles your fancy, customize the default tag as needed and enjoy the results:

<?php posts_nav_link(' &bull; ','&laquo; Go forward in time','Go back in time &raquo;'); ?>

Keep ‘em separated

What if you want to display your “Previous” link on the left side of the page and the ”Next” link on the right side of the page? We can acheive this effect by using two instances of the posts_nav_link() template tag (note that this configuration also resolves the “backward-navigation” issue discussed above):

<div class="left">
	<?php posts_nav_link('','','&laquo; Older Posts'); ?>
</div>
<div class="right">
	<?php posts_nav_link('','Newer Posts &raquo;',''); ?>
</div>

Keep ‘em separated with images

Continuing with the previous example, let’s keep the navigation links separate, but use images instead of text:

<div class="left">
	<?php posts_nav_link('','','<img src="images/older.png" />'); ?>
</div>
<div class="right">
	<?php posts_nav_link('','<img src="images/newer.png" />',''); ?>
</div>

Remember, you can use any text or markup you need in this template tag, so knock yourself out and conjure up something fresh.

previous_posts_link() and next_posts_link() — separate links for index, category, and archive pages

[ ↑ ] The previous_posts_link() and next_posts_link() template tags provide separate “next” and “previous” navigational links for any type of paged archive view. Basically, this tag creates individual navigational links for anything other than single-post views. This includes index, category, archive, tag, and search pages. Best results when used either before or after the loop. Here is an example of these tags showing their two accepted parameters:

<?php previous_posts_link('label','max_pages'); ?>

<?php next_posts_link('label','max_pages'); ?>

Default usage

Here is the default usage of these template tags, followed by their corresponding output (bullet added for clarity):

<?php previous_posts_link(); ?> &bull; <?php next_posts_link(); ?>

« Previous Page • Next Page »

Parameters

Here are the accepted parameters for each of these template tags:

<?php previous_posts_link('label','max_pages'); ?>
<?php next_posts_link('label','max_pages'); ?>

• label — alphanumeric string and/or markup used for the link text
• max_pages — an integer that limits the number of pages on which the link is displayed. The default value is “0” for all pages.

These are backward too

Like the posts_nav_link() tag, the previous_posts_link() and next_posts_link() create links that do the opposite of what you expect them to do. The previous_posts_link() tag links to newer posts and the next_posts_link() tag links to older posts. Again, exactly the opposite of what you would expect.

Fortunately, these tags create links that are spearate from one another, enabling us to implement them according to conventional methods of navigation. Simply customize the link text such that it means the opposite of the tag’s name and then switch the tags’ order in the source code. Let’s look at a few examples to help clarify this technique.

Examples

Here are some examples to demonstrate the use and flexibility of the previous_posts_link() and next_posts_link() template tags:

Customized link text

To keep the navigation operating conventionally, simply switch the meaning of the link text to convey the opposite meaning of the template tag and then position the tags accordingly:

<?php next_posts_link('&laquo; Previous posts'); ?> <?php previous_posts_link('Next posts &raquo;'); ?>

Default WordPress theme

Even the default WordPress theme, Kubrick, uses this technique to display proper navigational links in the correct order and on opposite sides of the page:

<div class="navigation">
<div class="alignleft"><?php next_posts_link('&laquo; Older Entries') ?></div>
<div class="alignright"><?php previous_posts_link('Newer Entries &raquo;') ?></div>
</div>

Thus, we see how to use the previous_posts_link() and next_posts_link() template tags to easily display your post-archive navigational links appear in the conventional, intiuitive, and correct order. Problem solved.

Keep ‘em separated with images (best method)

Here’s the proper way to create navigational links using images instead of text:

<div class="left">
	<?php next_posts_link('<img src="images/older.png" />'); ?>
</div>
<div class="right">
	<?php previous_posts_link('<img src="images/newer.png" />'); ?>
</div>

And as before, you may use any text or markup with this template tag, making it possible to integrate into just about any design.

previous_post_link() and next_post_link() — separate links for single-view post navigation

[ ↑ ] The previous_post_link() and next_post_link() template tags provide separate links to the previous post and next post, respectively. In doing so, these tags enable visitors to navigate chronologically through your single post permalink pages. These tags may be used anywhere on the sinlge.php template page, either in or out of the loop. Here is an example of these tags showing their four accepted parameters:

<?php next_post_link('format','link','in_same_cat','excluded_categories'); ?>

<?php previous_post_link('format','link','in_same_cat','excluded_categories'); ?>

Default usage

Unlike other navigational tags, next_post_link() and previous_post_link() eliminate navigational confusion and ambiguity by using actual post titles for their link text. Here are some examples of the default usage of these tags, followed by their corresponding output (bullet added for clarity):

<?php previous_post_link(); ?> &bull; <?php next_post_link(); ?>

« Previous Post Title • Next Post Title »

Parameters

Here are the accepted parameters for each of these template tags:

<?php next_post_link('format','link','in_same_cat','excluded_categories'); ?>
<?php previous_post_link('format','link','in_same_cat','excluded_categories'); ?>

• format — format string for the link. Here you specify the text/HTML to appear before and after the link. The link itself is specified according to the link parameter by including the %link variable in the format string. For example, a format value of “Next: %link »” will result in the following output: “Next The Post Title »”
• link — link text to display. Anything specified here will be used as the %link variable in the format parameter (see previous). By default, this parameter returns the post title via the %title variable. For example, a link parameter with a value of “[[%title]]” will result in the following output: “[[The Post Title]] »”
• in_same_cat — boolean value indicating whether or not the next or previous post must be in the same category as the current post. If set to TRUE, only posts from the current category will be displayed. Options are: TRUE or FALSE (default).
• excluded_categories — string indicating any collection of category IDs from which the next post should not be listed. In all versions of WordPress except 2.2, multiple categories are separated via “ and ”, for example: ‘1 and 3 and 7’ Oddly enough, in WordPress version 2.2, a comma is used to concatenate multiple excluded categories, for example: ‘1, 3, 7’

Examples

Here are some examples to demonstrate the use and flexibility of the previous_post_link() and next_post_link() template tags:

Custom title with link description before/after post link

Here we are displaying custom link titles with the text “Previous post: ” and “Next post: ” appearing before the previous and next post, respectively:

<?php previous_post_link('Previous post: %link', '[ %title ]'); ?> &bull; 
<?php next_post_link('Next post: %link', '[ %title ]'); ?>

Links to posts within the same category, excluding one

Here is how to display next and previous post links only to posts that are in the same category as the current post unless the current post is in category 7. Any number of categories may be excluded from this “same-category” navigation by using “ and ” as a delimiter:

<?php previous_post_link('%link', '%title', TRUE, '7'); ?> &bull; 
<?php next_post_link('%link', '%title', TRUE, '7'); ?>

Display images as links

Instead of using text for the next/previous-post links, we can use a custom set of images:

<?php previous_post_link('%link', '<img src="images/older.png" />', TRUE, '7'); ?> &bull; 
<?php next_post_link('%link', '<img src="images/newer.png" />', TRUE, '7'); ?>

Indeed, there is much that may done with this set of template tags. If you know of any juicy tricks not covered here, share them in the comments!

One for the road

Every now and then, you may encounter an older WordPress theme that includes the following navigation tags:

<?php previous_post(); ?>
<?php next_post(); ?>

For the record, these are the now-deprecated predecessors of the previously discussed previous_post_link() and next_post_link() template tags. The deprecated versions provide navigation of single permalink post views and use essentially the same parameters as the current tags. Now you know! :)

References

• posts_nav_link()
• previous_posts_link()
• next_posts_link()
• previous_post_link()
• next_post_link()

© 2009 Digging into WordPress | Permalink | 30 comments | Add to del.icio.us | Post tags: navigation, tags