; $Id: README.txt,v 1.1.2.1 2007-02-05 05:26:27 eaton Exp $

So, what the heck is this?
==========================
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!


The basics
==========
Once you've installed the Custom Pagers module, setting up a new pager is pretty straightforward. Go to 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.


Pager Visibility
================
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;
  }


Pager node list
===============
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*.

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 or 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.


Theming the pager
=================
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 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. $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.

The rest
========
That's it. That's what Custom Pagers does. Enjoy!

--Jeff Eaton
  jeff@viapositiva.net