The old pagination used in Rails 1.2.3 has been removed from the code in 2.0, but it is still supported via the plugin classic_pagination. However, there are good reasons to kiss her goodbye:

• first, a practical one: the classic_pagination plugin exists just for temporary compatibility; there is no guarantee that it will be maintained.
• second, the plugin forces the programmer to jump through some hoops: see listing 11.10 (or in the final version the method ‘paginate’ in application.rb), which, depending on the argument class, calls the plugin (‘super’) or does ‘manual pagination’; the writer’s comment (which aptly captures the absurdity of the situation) is: “Paginate by hand”.
• third, it has issues of performances when the number of pages is large.
• finally, a design opinion: this code is a bit uncharacteristic for Rails; the class chosen for Pagination is the ActionController, but the logic seems instead more related to ActiveRecord and ActionView (as pagination is a ‘presentation’ of ‘Model’ instances). The only advantage that I see in having this in the Controller is that the params method is available (while in a Model, it is not); so, a parameter such as ‘params[:page]’ does not need to be passed (in a scale from 0 to 10, weight=1 !).

There are several plugins that replace pagination; I examine here one of the most praised, will_paginate.

Let us start from the good news; give a look at the listing we just mentioned, 11.10 (method ‘paginate’ in application.rb): well, it just disappears! there is simply no need for it. It is remarkable that at the introduction of that method (start of chapter 11.1.4), the book comments:

# what we would really like to do is this:
def search
  if params[:q]
    ..
    @pages, @users = paginate(@users)
  end
end

Well, with will_paginate that wish becomes reality! if the collection on which we want to paginate has already been computed, eg in @users, we can just write:

@users = @users.paginate(:page => params[:page], :per_page => 10)

And to paginate on a model we could write (example):

@specs = Spec.paginate(:page => curr_page, :per_page => 10)

But wait a moment: the old pagination returned two objects (see above, @pages, @users), one to manage the pagination, the other with the results for the current page; now, we have only one object, @specs in the example!

The answer is: indeed we have just one object, and it is a bit smarter; it knows both the result of the search and the one for the pagination! (removing the confusion around those 2 objects was such a gift!).

All right; let us now proceed methodically and show how the code in chapters 10&11 can be changed. First, delete the old plugin and install will_paginate (see http://rock.errtheblog.com/will_paginate):

Let’s start recoding a few methods; the new code is:

def index  
  @title = "Community"
  @letters = ("A".."Z").to_a
  if params[:id] 
    @initial  = params[:id] 
    curr_page = params[:page]
    specs  = Spec.search_on_last_name(@initial)
    users  = specs.collect { |spec| spec.user }
    @users = users.paginate(:page => curr_page, :per_page => 10)
    end
end

Here the pagination is done in the last step, on users (not any longer on specs). So, the search method invoked is just a model search method:

# search specs based on last_name initial
def self.search_on_last_name(name_initial)
  find(:all, :conditions => ["last_name like ?", name_initial + '%'], 
             :order => "last_name, first_name")
end

Now, the partials which present the paginated users: first, the _user_table.rhtml (or _user_table.html.erb if you use the rails 2.0 naming convention; both are supported in 2.0); I show what changes from the old to the new version:

  <% if paginated? %>
    <tr>
      <td colspan="4" align="right">
      Pages: <%= pagination_links(@pages, :params => params) %>
    </td>
    </tr>
  <% end %>

  <tr>
    <td colspan="4" align="right">
      <%= will_paginate @users %>
    </td>
  </tr>

Finally, we have to recode the _result_summary.rhtml file, that displays the total number of results and the ones displayed in the page. Here I did not find really friendly methods (I mean methods that avoid the business of ‘offset +- 1’); so we will pretend that the friendly methods exist, and then we will add them to the plugin:

<% if @users %>
  <p>
  Found <%= pluralize(@users.total_entries, "match") %>.
  <% if @users.paginated? %>
    Displaying users <%= @users.first_item %>–<%= @users.last_item %>.
  <% end %>
  </p>
<% end %>

Now we add to the plugin the new methods added, by reopening.. ehm, which is the will_paginate class? let’s ask Ruby! bring up the rails console:

ruby script/console
>> Spec.paginate(:all, :page => 1).class
>> WillPaginate::Collection

All right, so we need to reopen the WillPaginate::Collection class; we have learnt how to reopen a class in a recent post (on Session); thus, under the lib directory we write a file (that must be required) that will do:

class WillPaginate::Collection 

  def first_item; offset + 1; end

  def last_item ; first_item + length - 1; end

  def paginated?; total_entries > size; end 
end

[Note: in case anyone finds similar methods in will_paginate, let me know and I will edit this post. The point here is just to centralize the treacherous +-1 and >,>= operations].

All this work pays handsomely when we add the search for users across spec/faq/user (chapter 11). As mentioned at the beginning, the long and twisted method ‘paginate’ (listing 11.10) in application.rb disappears! we just need to change one call from the community controller in the action ‘search’:

  @pages, @users = paginate(@users)

  @users = @users.paginate(:page => params[:page], :per_page => 10)

This single call builds the paginated @users, that can be fed to the View search.html.erb (which calls the same partials that we have seen above). With one shot (ie, one line), we have solved the problem; nice!

And, to finish chapter 11, we port the pagination for the A/S/L search: the old code is:

  specs = Spec.find_by_asl(params)
  @pages, @users = paginate(specs.collect { |spec| spec.user })

  specs = Spec.find_by_asl(params)
  users  = specs.collect { |spec| spec.user }
  @users = users.paginate(:page => params[:page], :per_page => 10)

Notice that we could concatenate statements, for example:

  specs  = Spec.find_by_asl(params)
  @users = specs.collect { |spec| spec.user }.paginate(:page => params[:page], :per_page => 10)

This is very much in vogue in Ruby/Rails as it is a compact notation, which eliminates intermediate local variables (and if you really want to impress your friends, you can even concatenate the 3 statements!).

Personally, I still like lines of code of about 80 characters (instead of 100, or 140 with the 3 lines concatenated; which is not unusual in Rails internal code!). In any case, the important is to understand all these types of notations.

Last observations:

• All the code presented above was tested ok (using the web browser, and running the test suite).
• RailsSpace uses pagination again later, in chapter 15, for posts in blogs; the modification should be easy, if you have read this post (so, we leave it as an exercise to the motivated reader :-).
• Finally: for more on will_paginate, see the brilliant screencast from Ryan Bates at http://media.railscasts.com/videos/051_will_paginate.mov