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

In general, you can expect pagination to work with the standard #find options, including :conditions, :group, :order, :limit, and :include. To activate paging, just specify the :page option. You may also provide additional paging options that will control the behavior of the enumerator returned by the #find method.

Simple Example
==============

# Get the first page of 'new' Cogs. Each page contains
# 10 cogs, and no more than 100 cogs will be returned.
cogs = Cog.find(:all, 
                :page,
                :conditions => ["category = 'new'"],
                :limit => 100)

# Print the name of each cog on the 1st page. Calling #each
# more than once will cause the 1st page to be printed for 
# each invocation.
cogs.each { |cog| puts cog.name }

# The next_page! method must be used to move to the 2nd page.
cogs.next_page!

# Print the name of each cog on the 2nd page
cogs.each { |cog| puts cog.name }

Scope Example
===============

# Get the second page of 'new' Cogs, using the #with_scope method. 
# Each page contains 15 cogs, and no more than 100 cogs will be returned.
Cog.with_scope(:find => {:conditions => "category = 'new'", :include => :widget}) do
  cogs = Cog.find(:all, 
                  :limit => 100,
                  :page => { :start => 1,
                             :current => 2,
                             :size => 15 })
end

# Print the name of each cog on the 2nd page.
cogs.each { |cog| puts cog.name }

# Move to the 3rd page of cogs. The options specified by 
# with_scope apply, even though a new page is loaded outside 
# the with_scope block.
cogs.next_page!

There is currently no advanced documentation for this plugin.