Paging through a list of content one piece of content at a time, is common on web sites. Picture galleries. Message board forums. Web comics. All of them are easier when you can use simple previous/next links to navigate through the content without jumping back and forth between list views and detail views.
In Drupal, quite a few modules implement their own custom pager code. Book.module and Forum.module are two great examples, and if you're writing a custom module from scratch you can do it yourself. What happens, though, if you're using tools like Views and CCK to set up your content? Writing a custom module just to add the decorative bits (like prev/next pagers) is a pain. And that's where Custom Pagers comes in.
Custom Pagers lets you set up lists of nodes to page through, then configure where the user should see the paging options (on story nodes, on nodes by Bob, etc.) Visit a node that matches the criteria, and Custom Pagers will display themeable previous and next links. That's it!
Once you've installed the Custom Pagers module, setting up a new pager is pretty straightforward. Go to Administer > Site building > Custom Pagers (admin/build/custom_pagers) and add a new pager. Name your pager, and choose where it should appear visually on the page (above or below the body of the node you're looking at, in a sidebar block, etc.) That's the simple part.
The next step is a bit trickier: you have to choose WHEN the pager should appear on. The simplest way is to simply select a node type and leave it at that. Whenever the user views a node of that type? Boom. You get a pager. If you're flipping through all the images on your site, or all the comics on your site, or something along those lines, it's probably what makes the most sense.
If you need to do something tricky, though (like only showing the pager if the current node was posted on a Wednesday, or only showing the pager if the currently logged in user is an administrator), you can use a snippet of PHP pasted into the 'PHP' field. Anything you stick in there is expected to return a TRUE or FALSE. It has access to the $node variable, so you should be able to get what you need without too much trouble. The following snippet, for example, would make a pager appear if the node was authored by the currently logged in user, or if they're the global administrator.
global $user;
if (($user->uid == $node->uid) || ($user->uid == 1)) {
return TRUE;
}
else {
return FALSE;
}
The final step is a bit trickier. It's not that difficult, but it takes some thinking. The Custom Pager module needs to have a proper list of nodes before it can figure out what comes after the currently viewed node, what came before it, and so on. In the 'Pager node list' section, you'll tell it how to get that list.
The easiest way is to use a View that you've defined with the Views module. Build it however you need to in the normal Views UI, keeping in mind that the order nodes appear in the view (via sorts, filters, etc) is the order that you'll be paging through them. Sorting newest-to-oldest, for example, will make 'previous' point to tomorrow, and 'next' point to yesterday. Tinker with it a bit before launching your site and posting to digg.com -- it's easy to forget.
If you're a crazy hardcore Views kind of person, you can also pass in arguments to the View using the aptly named 'Views arguments' field. If you have Token.module installed, you can also pass in arguments based on values from the current node.
How is this useful? Say you publish a webcomic site in which every user has their own comic. You could create a view that lists all comic nodes, and includes an argument for 'Node: Author.' When you create your custom pager, you'd choose the 'comics' view, and put: [author-uid] in the View arguments field. Voila! One view, one pager, but each time you visit a comic, the pager will point to the previous and next comics *by the same author*.
NB: for such needs, you may also have a look at this alternative module: Views navigation.
Just as you can use PHP snippets to control the visibility of a pager, hack-minded folks can use snippets to generate the list of nodes to page through. Your snippet should return an array of node IDs, again in the order that they should be paged through. The following snippet is as simple as it gets, returning the ids of nodes 1, 2, 3, and 4:
return array(1, 2, 3, 4);
Obviously, more complex stuff is possible. But if you're a hackery type of person, you should be able to figure that stuff out. I trust you.
By default, Custom Pagers displays the titles of the previous and next nodes, as well as the total number of nodes, like so:
< Previous node 4 of 39 Next node >
Once you've got your pager showing up in the right place at the right time, pointing to the right previous and next nodes, you'll probably want to change how it looks. No sweat! You can override the way the pager is rendered in your theme.
The Drupal 7 version of this module provides an interface at Structure -> Custom Pagers (admin/structure/custom_pagers) that enables site administrators to add new Custom Pagers or configure existing ones. The controls are pretty basic. Just add a pager, give it a name, assign it a region within the content to render and select one or more content types to associate it with.
The only tricky part of using this module in Drupal 7 is when it comes to determining how the list of nodes for your pager should be generated. You can use PHP code to generate a list of nodes or you can associate it with a view that generates the list of nodes.
In Drupal 7 there is currently an issue with the Custom Pagers being incompatible with the Views API. This will prevent Custom Pagers from working if it uses a view to generate the list of nodes. Fortunately there is a solution in the form of a patch that can be found at the permalink in the following discussion: https://drupal.org/node/1288368#comment-6429832
Use a template file in your theme to control the output of your pager.
To theme all pagers, use custom-pager.tpl.php.
To theme pagers more selectively:
custom-pager-PAGER ID.tpl.php
custom-pager-NODE TYPE.tpl.php
custom-pager-PAGER POSITION.tpl.php
custom-pager-NODE TYPE-PAGER POSITION.tpl.php
custom-pager-PAGER ID-PAGER POSITION.tpl.php
The following function is where all the magic happens:
function theme_custom_pager($nav_array, $node, $pager)
Override that function in your theme and you'll be able to do whatever you'd like.
The following data is available to your theme function (D5) or template (D6).
$node is just a copy of the node that's currently being viewed, and $pager is a copy of the current pager object. It contains bits like the snippet of PHP code used for visibility checking, and the name of the pager. The most important parameter is $nav_array. It's an array with the following elements:
$nav_array['first'] = The id of the first node in the entire list.
$nav_array['prev'] = The id of the node that comes before the current one
$nav_array['next'] = The id of the node that comes after the current one
$nav_array['last'] = The id of the last node in the entire list.
$nav_array['full_list'] = An array containing all the node IDs in the list, in order.
$nav_array['current_index'] = The array index of the current node in that list.
What can you do with that stuff? Quite a bit, if you're creative. With just the node IDs, you can build links. Or, you can do a full node_load() and display the titles of nodes you're linking to, thumbnails of images, etc. In addition, with the full_list element and the current_index element, you can generate your own 'jump forward by 5' and 'jump back by 5' links. Lots of possibilities there, yep.
You can find examples of theming your pages on this handbook page.
This is a simplified guide on how to set up Custom Pagers module, using Views 2 in Drupal 6 (however similar steps/concepts would apply for
This is a page of example code and templates for custom pagers. Please add your own!
Drupal is a registered trademark of Dries Buytaert.
