What is the paginating find plugin?

It's a plugin to help clean up and clarify pagination code in your Rails application. After you've got the plugin installed, you can use it to transparently load batches of model objects using just one call to the #find method. It's equally easy to use the plugin for stepping through data via your app's UI, or loading large numbers of model instances little-by-little, to avoid consuming a ton of memory.

How do I install it?

The same way you install all Rails plugins. At the root of your Rails app, issue the command:

script/plugin install http://svn.cardboardrocket.com/paginating_find

How do I use it?

Here's a simple example which lists Cogs in pages of 10.

app/controllers/cogs_controller.rb:

class CogsController <  ApplicationController
  def index
    @cogs = Cog.find(:all,
                     :page => {:size => 10,
                               :current => params[:page]})
  end
end

app/views/cogs/index.rhtml:

<ol>
<% @cogs.each do |cog| %>
  <li><%= cog.name %></li>
<% end %>
</ol>
<%= paginating_links(@cogs) %>

How does the plugin change the behavior of the #find method?

The plugin does two simple things when you call #find:

1. It counts the number of model instances in the total record set to be returned.
2. It returns a special Enumerator that knows how to issue the find query, providing the correct LIMIT and OFFSET for any given logical page of model instances.

The enumerator returned by the plugin has a ton of extra methods to help you navigate the results or build pagination links in your UI.

Note that if you omit the :page option, the #find method operates as though the plugin is not installed.

What extra #find options can I use to control paging?

The following options can be specified in the :page hash provided in your call to the ActiveRecord::Base#find method. All options are truly optional.

:size	Number of records in each page of results. Defaults to the total record count or 10, whichever is smaller.
:current	The current page. Defaults to the first page: 1.
:first	The first page. Defaults to the first page: 1.
:auto	Automatically load the next page during invocation of #each. Defaults to false.
:count	Number of records used to determine #page_count. Specifying this option prevents the plugin from automatically running a count query, which may be helpful if the table to be queried is very large.

What are the licensing terms?

The plugin is licensed under the MIT License.

I installed the plugin but it's not doing what I expect! Where can I file a bug report?

The plugin has pretty fair unit test coverage, and has been in use for some time by a decent number of users. So many of the initial bugs have already worked themselves out. If you're fairly certain you've found a bug, then write a test case for it and send the report directly to me via email.