SimplyPaginate
==============

SimplyPaginate is a Rails plugin for pagination. Loosely based on Mislav Marohnić
and PJ Hyett's work on will_paginate (http://github.com/mislav/will_paginate).

It is a very trimmed down version of will_paginate plus a few additions to suit my needs.



Requirements
============

Rails version 2.3.x

Gem dependencies:
  redgreen (for testing) [OPTIONAL]
  sqlite3-ruby (for testing) [OPTIONAL]



Installation
============

git submodule add git://github.com/pjg/simply_paginate.git vendor/plugins/simply_paginate
git commit -m "Add simply_paginate plugin as a submodule"



Example usage
=============

config/routes.rb
  map.comments_pages '/comments/page/:page', :controller => 'comments', :page => /[\d]{1,}/


app/controllers/comments_controller.rb
  def index
    @comments = Comment.paginate(:per_page => 50,
                                 :page => params[:page],
                                 :include => [:document],
                                 :conditions => {:is_hidden => false},
                                 :order => 'comments.id DESC')
  end


app/views/comments/index.html.erb
  <%= pagination_for @comments %>


Will render pagination links Flickr style:
  [« Previous page][1][2][3]...[154][Next page »]


To display the pagination summary:

app/views/comments/index.html.erb
  <p>Total: <%= @comments.total_entries %> comments. Showing: <%= @comments.current_results_first %> - <%= @comments.current_results_last %>.</p>


To customize the 'previous page' and 'next page' labels:

config/initializers/simply_paginate.rb
  SimplyPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous'
  SimplyPaginate::ViewHelpers.pagination_options[:next_label] = 'Next'


Integration with the act_as_ferret full text search:

app/controllers/search_controller.rb
  def index
    @query = params[:query]
    page = params[:page].blank? ? 1 : params[:page]
    @results = SimplyPaginate::Collection.create(page, 10) do |pager|
      pager.total_entries, results = Document.full_text_search(@query, :page => page)
      pager.replace results
    end
  end


It does work correctly with named scopes, for example the following will yield the expected results:

  Comment.visible.ordered.paginate(:page => 2, :per_page => 5)


It also works with Arrays:

  [1, 2, 3, 4 ,5].paginate(:page => 2, :per_page => 2)
  => [3, 4]



CAVEATS
=======

Unfortunately, there are some. Comment.all returns an array (instead of ActiveRecord::NamedScope::Scope), so doing one of the following:

  Comment.all.paginate(:per_page => 2)
  Comment.find(:all).paginate(:per_page => 2)
  >> Comment Load (26.5ms)   SELECT * FROM `comments`

is highly inefficient as it will first fetch all records from the database and only then paginate the returned Array. Use this instead:

  Comment.paginate(:per_page => 2)
  >> SQL (0.1ms)   SELECT count(*) AS count_all FROM `comments`
  >> Comment Load (0.3ms)   SELECT * FROM `comments` LIMIT 0, 2


I don't recommend using it with named scopes which use the :include parameter. For example, given:

  model Comment
    named_scope :with_document, :include => :document
  end

Don't do the following (as it will generate an ugly and very resource hungry count query):

  Comment.with_document.paginate(:page => params[:page], :per_page => 50)
  >> SQL (85.7ms)   SELECT count(DISTINCT `comments`.id) AS count_all FROM `comments` LEFT OUTER JOIN `documents` ON `documents`.id = `comments`.document_id
  >> Comment Load (0.1ms)   SELECT * FROM `comments` LIMIT 0, 50
  ...

Instead do it old school:

   Comment.paginate(:include => :document, :page => params[:page], :per_page => 50)
   >> SQL (0.2ms)   SELECT count(*) AS count_all FROM `comments`
   >> Comment Load (0.1ms)   SELECT * FROM `comments` LIMIT 0, 50
   ...

The difference in performance is striking (in part it is due to the fact, that MySQL keeps the table count at hand).



TESTING
=======

If you'd like to run tests, you must have the sqlite3 installed (both application and gem):

  aptitude install sqlite3 libsqlite3-dev
  gem install sqlite3-ruby



Copyright (c) 2008-2010 Paweł Gościcki, released under the MIT license