Build Status


The Paginator extension allows rendering of a page template against portions of a collection. For instance, you might render your blog posts on a page, 10 at a time. The Paginator extension makes this possible.


Data Slicing

The data to paginate is retrieved from the site object, using the var_name provided in the configuration.

The first parameter to the extension is the name of a property from the site object. If you've used the Posts extension to place the posts into site.posts, then you would specify :posts as the name to paginate.

The extension slices the data from the site object based upon opts[:per_page], and assigns the resulting slices to page object under the same name.


Page association

The second parameter, specifying the simple name of the template to use, is then injected into the site, once for each slice produced by the behavior described above.

The first page injected into the site will match the name of the input template, with the appropriate output extension. Subsequent pages, if necessary, will be named page1.html, page2.html etc.


Pagination Templates

Since the Paginator extension adds additional properties to the page object, templates may take advantage of this fact to render more robust pages.

While the slice of objects assigned to the page is primary an array, it has additional properties to aid in rendering of the page.

Property Type Description
next_page Page Reference to the next page in the pagination sequence, or nil
previous_page Page Reference to the previous page in the pagination sequence, or nil
current_page Page Reference to the current page (should be equal to page)
current_page_index integer 0-based index of the current page in the pagination sequence
pages Array of Page The full sequence of pagination pages

It also provides a single extra method to draw pagination links for navigating through the sequence of pages.

Method Result Description
links String of HTML An HTML string including page navigation links

Parameters, input_template, opts)

Parameter Description
var_name The name of the variable to pagination from `site` into each `page`.
input_template Simple path (without extension) to the template to use for each page.
opts Opts for pagination and linking


per_page Number of items per page.
window_size The number of pages on either side of the first, last or around the current page when drawing links.


Generic Installation do
  extension, input_template, opts)

Simple Installation do
  extension :posts, 
                                                  :per_page=>5 )

Typical Usage

Assuming you've configured the pipeline as: do
  extension '/news', :posts )
  extension :posts, '/news/index', :per_page=>5 )

Pages under /news/** matching the date-based file-naming scheme will be considered to be blog posts, and made available as site.posts

In turn, the paginator will examine site.posts and slice it into chunks of 5, assigning each slice to a new page. The new pages are fed from the site template that matches /news/index.html.haml or other appropriate extension.

The first generate page will be /news/index.html. The second, if required will be /news/page2.html and so on.

The /news/index.html.haml template may look akin to

- for post in page.posts
      %a{:href=>post.url}= post.title
      = post.content

= page.posts.links

See Also