GoBecky.net Geek. Gimp. Goddess.

WordPress Plugin: Previous/Next Links By Category

I've only been using WordPress a short time now, but I do love it. In the process of tweaking my templates, I came across an issue that really needed a custom function to resolve, and I've decided to package my solution up as a plugin for anyone else who might have use of it.

The problem

By default, WordPress does not properly handle previous/next links by category when a single post exists in multiple categories (it simply repeats the links for the first category in the list). I came across Ricky Maxwell's Next Previous Posts in Same Category plugin (an adaptation of the Scriptygoddess classic), but it gives all of the previous links as a group, then all the next links. I wanted to display something more like this:

Category One
Previous Link
Next Link
Category Two
Previous Link
Next Link

The Solution: Previous/Next Links By Category

Previous/Next Links By Category creates one simple new function that can be used out-of-the-box to create a nested list of your previous/next links within categories. The function also takes a variety of optional parameters to customize its output if you're feeling adventurous.

Installation:

1. Download prev-next-by-cat.zip
2. Unpack the archive (if necessary)
3. Move the prev-next-by-cat.php file to your plugins directory (wp-content/plugins/)
4. Activate the plugin in your WordPress Dashboard

Usage:

You now have access to a new template tag: prevNextByCat()

The tag is intended to be used only in single post pages (permalink pages). The tag can be used anywhere in the template, including the sidebar.

By default, without any parameters, the function will output the following HTML:

<ul class="browse-cats">
    <li class="browse-cat-group"> <span class="browse-cat-header">Browse Category: First Category Name</span>
        <ul>
            <li class="cat-prev-link">&laquo; <a href="permalink">Previous Entry</a> </li>
            <li class="cat-next-link">&raquo; <a href="permalink">Next Entry</a> </li>
        </ul>
    </li>
    <li class="browse-cat-group"> <span class="browse-cat-header">Browse Category: Second Category Name</span>
        <ul>
            <li class="cat-prev-link">&laquo; <a href="permalink">Previous Entry</a> </li>
            <li class="cat-next-link">&raquo; <a href="permalink">Next Entry</a> </li>
        </ul>
    </li>
</ul>

Which outputs something like this:

• Browse Category: First Category Name
  • « Previous Entry
  • » Next Entry
• Browse Category: First Category Name
  • « Previous Entry
  • » Next Entry

You can use the built-in style definitions to tweak the display of the list.

Fancy Usage

If you're feeling adventurous and are somewhat comfortable with HTML, prevNextByCat() takes a variety of optional parameters that let you have total control over the output of your links. The syntax is as follows:

prevNextByCat($beforeOutput, $afterOutput, $beforeEachCat, $afterEachCat, $beforeCatHeader, $afterCatHeader, $beforePrevLink, $afterPrevLink, $beforeNextLink, $afterNextLink )

By default, the function uses these parameters to output the list format above. If you choose to change any or all of these parameters, this is what the function will spit out:

$beforeOutput
$beforeEachCat
$beforeCatHeader First Category Name $afterCatHeader
$beforePrevLink Prev Link $afterPrevLink
$beforeNextLink Next Link $afterNextLink
$afterEachCat
$afterOutput

This setup lends itself well to lists, but with a little wrangling you can get the layout to fit into pretty much any established structure you have.

Real-world Example Using Optional Params

This is how I call the plugin from the sidebar of my single.php template:

prevNextByCat('','','<div class=\'chunk\'>','</ul></p> </div>','<h3><span>Category</span> / ','</h3><p><ul>');

You can see the results on the sidebar of my permalink pages. This is what the HTML looks like:

<div class='chunk'>
<h3><span>Category</span> / (Cat 1 Name)</h3>
<ul>
    <li>&laquo; <a href="permalink">Previous Entry</a> </li>
    <li>&raquo; <a href="permalink">Next Entry</a> </li>
</ul>
</div>

That sequence repeats for every category a post belongs to.

Notes, Known Issues, and Future Improvements

• This plugin has been tested on WordPress v2.6.2.
• This is a very beta release, and I have no idea what it may do in circumstances different than my own. In particular, I don't know how it will handle sub-categories.
• If the post in question is the only post in a given category, instead of links the following text will appear after the category name: <div>No other entries in this category!</div> The handling of categories with only one post may become more flexible in a later release.
• For now, there is no way to exclude or include categories from being listed, although that will be added. For the time being, you can use WordPress's in_category() tag in an if statement. For example, I only want the plugin to run when the entry is not filed under the "General" category. So my template code actually looks like this:

if ( !(in_category(1) ) ) { 
prevNextByCat('','','<div class=\'chunk\'>','</ul></p> </div>','<h3><span>Category</span> / ','</h3><p><ul>');
}

Etc.

Feel free to leave a comment here with bug reports, feature requests, or just to let me know you're using the plugin.

And once more...

Download: prev-next-by-cat.zip

[...] I wrote a plugin that handles next/previous links when a post is in more than one category (by default, WP will only list the links for one category). I haven't tested it with 2.7 yet, but there's really no reason for it not to work. WordPress Plugin: Previous/Next Links By Category ? GoBecky.net [...]