Paginator Navigator

This is a plugin that generates a Helper function called paginator_navigator. It works like normal pagination, except it addes page numbers, or the letters of the first and last object in the collection of each page, between the next and previous buttons. Here are a few examples of how to use it.

BASIC PAGINATION

[controller] def list @user_pages, @users = paginate_collection(User.find_custom_query, :page => params[:page]) end [/controller]

[view] ...

<%= paginator_navigator(@user_pages) %> ... [/view]

This would generate a list at the bottom of the page that looks something like this:

what the user sees (assumes they are on page 7 of 20)

<< Previous Page [2] ... 5 7 [9] ... 19 [Next Page >>]

Notice how it breaks up the pages to show the first and last few pages, and the pages surround the current page. The number of pages to show at each extreme or around the current page is controlled by the options.

DEFINING PAGINATION GROUPING SIZES

If you wanted the user to see the first and last 3 pages of the list, and only one page around the current page, you can use this example:

[view] ...

<%= paginator_navigator(@user_pages, nil, {:inner_bound_limit => 1, :outer_bound_limit => 3}) ... [/view]

This would generate a list at the bottom of the page that looks something like this:

what the user sees (assumes they are on page 7 of 20)

<< Previous Page 2 [4] ... 6 [8] ... 17 19 [Next Page >>]

Some of you may be wondering why nil had to be passed in for the last example. What is that for? I’m glad that you wondered that. That is to pass in the entire collection returned by your custom query back in the first example. But we need to get the results back first.

[controller] def list @user_pages, @users, @all_users = paginate_collection(User.find_custom_query, :page => params[:page]) end [/controller]

I’m storing the result of the collection created by User.find_custom_query into @all_users. This can be passed into the paginator_navigator, along with another option, to turn the list of page numbers into a list of page extremes. Here’s an example:

PAGINATION WITH LETTERS FROM EACH PAGE

[view] ...

<%= paginator_navigator(@user_pages, @all_users, {:inner_bound_limit => 1, :outer_bound_limit => 1, :paginate_by => ‘name’}) ... [/view]

NOTE: This example assumes that the User table has a column called name, and that User.find_custom_query has an order option in it. This next option is really only useful if User.find_custom_query is sorted by the same column that :paginate_by is using.

The example above would generate a list at the bottom of the page that looks something like this:

what the user sees (assumes they are on page 7 of 20)

<< Previous Page [Al..Br] ... Lu..Mi [Mi..Na] ... Tr..Va [Next Page >>]

Here you can see the first two letters of the name of the first and last user on each page. Also, when the user hovers over one of these links, they can see the full text of the names at each extreme. So hovering over the link that says [Lu..Mi] may show the following tool tip text:

[hover text]

[Lucas..Michael]

[/hover text]

That way the user knows exactly what is on each page.

If two letters are too much, or not enough for each link, another option can be passed to change the number of characters on each link, :chars_per_name

DEFININING THE NUMBER OF LETTERS TO SHOW ON EACH PAGE LINK

[view] ...

<%= paginator_navigator(@user_pages, @all_users, {:inner_bound_limit => 1, :outer_bound_limit => 1, :paginate_by => ‘name’, :chars_per_name}) ... [/view]

what the user sees (assumes they are on page 7 of 20)

<< Previous Page [A..B] ... L..M [M..N] ... T..V [Next Page >>]

STYLESHEET

I have included a basic stylesheet file for the results of the paginator_navigator helper. You’ll have to copy it from this plugin’s lib folder to your public/stylesheets folder, and add the appropriate stylesheet link for it in your layouts that use this helper. This file should be adjusted to fit the needs of your site.

<%= stylesheet_link_tag “paginator_navigator”, :media => “screen” %>