Keyvan Nayyeri

Probably you've seen a common part of many blogging engines which is a simple navigator for individual posts that lets you navigate to the next and previous posts when viewing an individual post. This usually appears on top or under the post body and I've experienced that a reasonable number of bloggers would like to use it.

I don't know what's the exact name of this control in blogging engines but I named it Post Navigator for my Graffiti implementation.

Here I want to show you how did I write this extension for Graffiti. For those who want to dig into the Graffiti API, especially fetching data for posts based on custom queries, this example may be helpful.

Introduction

Post Navigator is a simple extension that shows links to the previous and next posts in a Graffiti application. This is usually useful for sites that use Graffiti as a blog engine (like mine).

Obviously the implementation of such an extension has a simple process of finding the next and previous posts and doing some extra work to generate the appropriate output. I'll detail this process in a moment but for now keep in mind that the best way to recognize the next and previous posts is via the unique identifier of them. The previous post is the immediate post with smaller ID before the specified post and the next post is the immediate post with larger ID after the specified post. But there is an important point here and that is about unpublished posts so you need to select from published posts only.

Implementation

The implementation of Post Navigator is straightforward. In a nutshell you need to:

• Find the previous post.
• Find the next post.
• Generate the appropriate output for the previous and next posts based on user's choices.

My implementation is a simple Graffiti extension that is nothing but a single class that must be flagged with a Chalk attribute to become a Chalk extension. In addition to this, I also need two constants for the pattern of the previous and next post links and two objects of Post type for the previous and next posts.

So here is the initial part of the code:

After this the implementation consists of two public methods that generate the navigator HTML code and some private helper methods for it. I've provided two overloads for GetNavigator which returns the string value of the HTML code. One overload is simple and a quick shortcut to use the other one and simplify the usage. The other one is the fully customizable overload that lets you pass the post as well as Boolean parameters to specify if you only want links to the previous posts or next posts and also some string parameters that let you customize the text value to be shown for the next and previous post links and a separator between them as well as two string values to append to these texts for customization and showing arrows or images. If user passes empty values for these string values then the code will apply the default behavior which is what I inspired from common blogging engines.

Here is the code for both overloads of GetNavigator:

The second overload simply calls GetPreviousPost and GetNextPost functions to get instances of the previous and next posts and then calls the GetHtmlCode function to return the string value of the final HTML code.

But the main part of the implementation is in GetPreviousPost and GetNextPost functions where we pass a Post object and get its previous and next posts. The logic behind both functions is same and there are minor differences to get the previous and next posts.

Here I have to thank Scott for helping me on this part of the code. After getting his help on applying Graffiti classes I still had a problem in selecting data so had to go back and forth and debug the code to find what's the exact reason. As you see I used an uncommon code for the Top property of Query class to solve an issue that I think it's related to Graffiti API. I will begin a private conversation with Scott about this after this post.

But how these methods are written? First I created a Table object for graffiti_Posts table to select data from it. Then I created a Query object for this table which adds a WHERE clause to the select method in order to filter posts with smaller IDs or larger IDs than the ID of the post. The other filter is for published posts and finally a call to PostCollection.FetchByQuery for the first item in the list always returns our desire post.

The Top property of the Query class is something to select top items in the list but I modified the default "100 PERCENT" value to be able to use the Query object and solve an issue.

The last piece of code is for GetHtmlCode function which returns the string value of the HTML output. I don't step in its details since it's nothing more than some case statements to decide what to add to the output.

Download

You can download the binary and source code of Post Navigator extension for Graffiti from here.

How to Use

Like all other Graffiti extensions you just need to copy the binary DLL file of the extension to the bin folder on your server and modify your theme files to use this extension.

As I outlined where was talking about the implementation, there are two ways to use this extension in your themes. After applying your own markup for the container section of the navigator you can use one of these approaches.

The first way is easier. You pass the post as well as two string values for the previous and next link texts. Here is an example:

$postNavigator.GetNavigator($post, "Previous", "Next")

The second way is a customized one and an example is presented here:

$postNavigator.GetNavigator($post, true, true, " | ", "", "", "« ", " »")

As the last note I have to say that you can pass many things as parameters to this extension like the HTML code that displays an image rather than a text value for the previous and next links or string value of the HTML code to link to the homepage of the site rather than a simple text separator.