When a list is longer than one page, the bundled pagination model gives you the data for "newer / older" links and numbered page links. As always, you write the HTML.

<!-- render.cms.news('order=newest') -->
<article>…</article>
<!-- /render.cms.news('order=newest') -->

<!-- render.pagination.links('cms.news') -->
<nav class="pager">
  <!-- print.+class.prev_state --><!-- [email protected]_url --><a class="prev" href="#">&larr; Newer</a><!-- /[email protected]_url --><!-- /print.+class.prev_state -->

  <!-- render.pagination.pages('cms.news') -->
  <!-- print.+class.state --><!-- [email protected] --><a class="page" href="#"><!-- print.number -->1<!-- /print.number --></a><!-- /[email protected] --><!-- /print.+class.state -->
  <!-- /render.pagination.pages('cms.news') -->

  <!-- print.+class.next_state --><!-- [email protected]_url --><a class="next" href="#">Older &rarr;</a><!-- /[email protected]_url --><!-- /print.+class.next_state -->
</nav>
<!-- /render.pagination.links('cms.news') -->

pagination.links('cms.news') returns one row:

pagination.pages('cms.news') returns one row per page:

Both return nothing when everything fits on one page, so the pager disappears.

Pages are addressed as /news (page 1), /news/news_page/2, /news/news_page/3… (the first part is the page showing the list). This doesn't work on the home page, where /news_page/2 is a 404: give a paginated list its own page. The number of items per page comes from news_page_size, else raster_page_size, else 10 (see The CMS).

If the list uses filters, give pagination the same filters as a second argument so it counts the right items:

<!-- render.cms.news('featured=1&order=newest') --> … <!-- /render.cms.news('featured=1&order=newest') -->
<!-- render.pagination.links('cms.news', 'featured=1') --> … <!-- /render.pagination.links('cms.news', 'featured=1') -->

Filters from the URL (/news/news_items/tag/php) are picked up automatically, and so is a filter that reads the query string: with category=?category in both, the page links keep ?category=….

Pagination can ask one of your models instead. Pass 'model.method'. Raster calls the method with true as its only argument, and expects the total and the page size back:

class guestbook {
    function entries($count = false) {
        $perpage = 20;
        $db = database::instance('guestbook');
        $total = (int)$db->entry_count()[0]['n'];
        if ($count === true) return array('total' => $total, 'perpage' => $perpage);

        $page = max(1, (int)util::get('page'));
        return $db->entries_page($perpage, ($page - 1) * $perpage);
    }
}

-- models/guestbook/sql/entry_count.sql
SELECT COUNT(*) AS n FROM entry

-- models/guestbook/sql/entries_page.sql
SELECT name, message FROM entry ORDER BY id DESC LIMIT ? OFFSET ?

<!-- render.guestbook.entries --> … <!-- /render.guestbook.entries -->
<!-- render.pagination.pages('guestbook.entries') --> … <!-- /render.pagination.pages('guestbook.entries') -->

For your own models the pages are addressed with a query string, ?page=2, which your method reads with util::get('page').

Note that pages with a query string are not stored in the page cache and can't be part of a static export.