If your theme design calls for links to the "previous" and "next" pages (a.k.a sibling pages), the easiest way to do so is by using the functionality of the built-in next_previous block. You could add the block to your page defaults, but sometimes you need to "hard-code" the links (for example, to have them in places where there's not an editable area; or to prevent users from "accidentally" removing them).

Here is how you can "hard-code" the next_previous block into your theme templates:

<?php
//initialize the block
$next_prev = BlockType::getByHandle('next_previous');

//set your options
$next_prev->controller->orderBy = 'display_asc';
$next_prev->controller->loopSequence = true;
$next_prev->controller->excludeSystemPages = true;

//get the pages
$prev_page = $next_prev->controller->getPreviousCollection();
$next_page = $next_prev->controller->getNextCollection();

//get url's to the pages
$nh = Loader::helper('navigation');
$prev_url = $nh->getLinkToCollection($prev_page);
$next_url = $nh->getLinkToCollection($next_page);
?>

<a href="<?php echo $prev_url; ?>">Previous Page</a>
<a href="<?php echo $next_url; ?>">Next Page</a>

Block Options

There are three options available:

  1. orderBy: Can either be 'display_asc' (the order that pages are listed in the sitemap) or 'chrono_desc' (newest pages first, based on publish date). If you don't specify this option, it defaults to 'chrono_desc'.
  2. loopSequence: Determines if the links should "wrap around" from the last to the first (or first to last) within this section of the sitemap. For example, if the current page is the last sibling in its section and loopSequence is set to true, then the "next" item will link to the first page in the section. If loopSequence is set to false, then the "next" item will just be false. If you don't specify this option, it defaults to false.
  3. excludeSystemPages: Determines if "system pages" (pages installed by C5 -- e.g. Login, Register, etc.) should be ignored. If you don't specify this option, it defaults to false.

Grabbing Page Titles

The getNextCollection() and getPreviousCollection() functions return normal C5 page objects, so if you want the titles of the pages you're linking to, you can get them like so:

$next_page = $next_prev->controller->getNextCollection();
$next_title = $next_page->getCollectionName();

The same concept applies to all of the page attributes (e.g. $next_page->getCollectionDatePublic(), $next_page->getDescription(), $next_page->getAttribute('my_custom_attribute'), etc.).

Gotchas

Pages that have the "Exclude From Nav" (exclude_nav) attribute checked will always be ignored! Unfortunately there is no way to disable this functionality when using the next_previous block.