Allow bypassing the implicit render in paginate

When using Rails, a common pattern would be to simply paginate a
collection and then render it using a custom serializer. Although this
is currently possible by calling `_paginate_collection` directly, it was
unintended. To better support custom serialization or things like
JBuilder, allow users to bypass the implicit render at the end of
`paginate` by passing their collection to it directly instead of via the
`:json` or `:xml` options:

```ruby
class MoviesController
  def index
    movies = paginate(Movie.all, per_page: 25)

    render json: MoviesSerializer.new(movies)
  end
end
```

If the call to `paginate` still mimics what a call to `render` looks
like, an implicit render will happen. If it looks more like the above,
the collection will simply be paginated and returned after the headers
are set up.

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

Author: davidcelis

README.md

@@ -25,7 +25,7 @@ gem 'api-pagination'
 
 ## Rails
 
-In your controller, provide a pageable collection to the `paginate` method:
+In your controller, provide a pageable collection to the `paginate` method. In its most convenient form, `paginate` simply mimics `render`:
 
 ```ruby
 class MoviesController < ApplicationController
@@ -47,18 +47,33 @@ class MoviesController < ApplicationController
 end
 ```
 
-`paginate` will:
+This will pull your collection from the `json` or `xml` option, paginate it for you using `params[:page]` and `params[:per_page]`, render Link headers, and call `ActionController::Base#render` with whatever you passed to `paginate`. This should work well with [ActiveModel::Serializers](https://github.com/rails-api/active_model-serializers). However, if you need more control over what is done with your paginated collection, you can pass the collection directly to `paginate` instead of in a way that mimics `render`:
 
-1. Pull your collection from `json:` or `xml:`
-2. Use `params[:page]` and `params[:per_page]` to paginate your collection for you
-3. Use the paginated collection to render `Link` headers
-4. Call `ActionController::Base#render` with whatever you passed to `paginate`.
+```ruby
+class MoviesController < ApplicationController
+  # GET /movies
+  def index
+    movies = paginate Movie.all
+
+    render json: MoviesSerializer.new(movies)
+  end
+
+  # GET /movies/:id/cast
+  def cast
+    actors = paginate Movie.find(params[:id]).actors, per_page: 10
+
+    render json: ActorsSerializer.new(actors)
+  end
+end
+```
+
+This will avoid implicitly calling `render` at the end. Instead, `paginate` will simply set up the headers and return your collection so you can do whatever you want with it.
 
-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.
+Note that 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 call `require 'will_paginate/array'` somewhere. Because this pollutes `Array`, it won't be done for you automatically.
 
 ## Grape
 
-Grape is similar, though `paginate` won't take options. Only your collection. In your API endpoint:
+With Grape, `paginate` is used to declare that your endpoint takes a `:page` and `:per_page` param. Inside your API endpoint, it simply takes your collection:
 
 ```ruby
 class MoviesAPI < Grape::API

lib/rails/pagination.rb

@@ -2,10 +2,15 @@ module Rails
   module Pagination
     protected
 
-    def paginate(options)
+    def paginate(*options_or_collection)
+      options    = options_or_collection.extract_options!
+      collection = options_or_collection.first
+
+      return _paginate_collection(collection, options) if collection
+
       collection = options[:json] || options[:xml]
+      collection = _paginate_collection(collection, options)
 
-      collection     = _paginate_collection(collection, options)
       options[:json] = collection if options[:json]
       options[:xml]  = collection if options[:xml]
 

spec/rails_spec.rb

@@ -53,6 +53,16 @@
         it_behaves_like 'an endpoint with a middle page'
       end
     end
+
+    context 'providing a block' do
+      it 'yields to the block instead of implicitly rendering' do
+        get :index_with_custom_render, :count => 100
+
+        json = { numbers: (1..10).map { |n| { number: n } } }.to_json
+
+        expect(response.body).to eq(json)
+      end
+    end
   end
 end
 

spec/support/numbers_controller.rb

@@ -39,14 +39,25 @@ def teardown(*methods)
 end
 
 Rails.application.routes.draw do
-  resources :numbers, :only => [:index]
+  resources :numbers, :only => [:index] do
+    get :index_with_custom_render, on: :collection
+  end
+end
+
+class NumbersSerializer
+  def initialize(numbers)
+    @numbers = numbers
+  end
+
+  def to_json(options = {})
+    { numbers: @numbers.map { |n| { number: n } } }.to_json
+  end
 end
 
 class NumbersController < ActionController::Base
   include Rails.application.routes.url_helpers
 
   def index
-    page = params.fetch(:page, 1).to_i
     total = params.fetch(:count).to_i
 
     if params[:with_headers]
@@ -57,4 +68,12 @@ def index
 
     paginate :json => (1..total).to_a, :per_page => 10
   end
+
+  def index_with_custom_render
+    total   = params.fetch(:count).to_i
+    numbers = (1..total).to_a
+    numbers = paginate numbers, :per_page => 10
+
+    render json: NumbersSerializer.new(numbers)
+  end
 end