Change interface for Rails pagination

This fixes #7 but is also related to a more dire issue. `after_filter`
was misunderstood to provide access to the response before the body had
been written. In actuality, the response has already been fully
constructed by the time `after_filter` is called, which means that the
collection has already been queried and written as json (or XML). In
order to maintain a nice interface without using after_filter, the
method signature of `paginate` has changed to act like `render`:

```rails
class API::v1::PostsController < ApplicationController
  def index
    # Uncomment this line to change the default per_page from 10 to 25:
    # params[:per_page] ||= 25
    posts = Post.all

    paginate json: posts
  end
end
```

At the end, `paginate` simply passes its arguments on to `render` so all
of `render's` options are supported. The collection is assumed to live
either in the argument hash's `:json` key or an `:xml` key.

Signed-off-by: David Celis <me@davidcel.is>

Author: davidcelis

README.md

@@ -24,39 +24,41 @@ gem 'api-pagination'
 
 ## Rails
 
-In your controller:
+In your controller, provide a pageable collection to the `paginate` method:
 
 ```ruby
 class MoviesController < ApplicationController
-  # Uses the @movies and @actors variables set below.
-  # This method must take an ActiveRecord::Relation
-  # or some equivalent pageable set.
-  after_filter only: [:index] { paginate(:movies) }
-  after_filter only: [:cast]  { paginate(:actors) }
-
   # GET /movies
   def index
-    @movies = Movie.all # Movie.scoped if using ActiveRecord 3.x
+    movies = Movie.all # Movie.scoped if using ActiveRecord 3.x
 
-    render json: @movies
+    paginate json: movies
   end
 
   # GET /movies/:id/cast
   def cast
-    @movie  = Movie.find(params[:id])
-    @actors = @movie.actors
+    actors = Movie.find(params[:id]).actors
 
-    # Override how many Actors get returned.
-    params[:per_page] = 10
+    # Override how many Actors get returned. The default is 10.
+    params[:per_page] = 25
 
-    render json: @actors
+    paginate json: actors
   end
 end
 ```
 
+`paginate` will:
+
+* Pull your collection from `json:` or `xml:`
+* Use `params[:page]` and `params[:per_page]` to paginate your collection for you
+* Use the paginated collection to render `Link` headers
+* Call `ActionController::Base#render` with whatever you passed to `paginate`.
+
+The collection sent to `paginate` _must_ respond to your paginator's methods. For Kaminari, `Kaminari.paginate_array` will be called for you behind-the-scenes. For WillPaginate, you're out of luck unless you somewhere `require 'will_paginate/array'`. Because this pollutes `Array`, it won't be done for you automatically.
+
 ## Grape
 
-In your API endpoint:
+Grape is similar, though `paginate` won't take options. Only your collection. In your API endpoint:
 
 ```ruby
 class MoviesAPI < Grape::API

lib/rails/pagination.rb

@@ -2,8 +2,8 @@ module Rails
   module Pagination
     protected
 
-      def paginate(collection)
-        collection = instance_variable_get(:"@#{collection}")
+      def paginate(options)
+        collection = options[:json] || options[:xml]
 
         block = Proc.new do |collection|
           links = (headers['Link'] || "").split(',').map(&:strip)
@@ -19,7 +19,13 @@ def paginate(collection)
           headers['Total'] = ApiPagination.total_from(collection)
         end
 
-        ApiPagination.paginate(collection, params, &block)
+        collection = ApiPagination.paginate(collection, params, &block)
+
+        options[:json] = collection if options[:json]
+        options[:xml]  = collection if options[:xml]
+
+        render options
       end
   end
 end
+

spec/support/numbers_controller.rb

@@ -45,7 +45,7 @@ def teardown(*methods)
 class NumbersController < ActionController::Base
   include Rails.application.routes.url_helpers
 
-  after_filter :only => [:index] { paginate(:numbers) }
+  # after_filter :only => [:index] { paginate(:numbers) }
 
   def index
     page = params.fetch(:page, 1).to_i
@@ -57,7 +57,8 @@ def index
       headers['Link'] = %(<#{numbers_url}?#{query.to_param}>; rel="without")
     end
 
-    @numbers = (1..total).to_a
-    render :json => @numbers
+    numbers = (1..total).to_a
+
+    paginate :json => numbers
   end
 end