Merge branch 'master' into 3-x-stable

Author: davidcelis

README.md

@@ -133,6 +133,25 @@ Per-Page: 10
 # ...
 ```
 
+## A Note on Kaminari and WillPaginate
+
+api-pagination requires either Kaminari or WillPaginate in order to function, but some users may find themselves in situations where their application includes both. For example, you may have included [ActiveAdmin][activeadmin] (which uses Kaminari for pagination) and WillPaginate to do your own pagination. While it's suggested that you remove one paginator gem or the other, if you're unable to do so, you _must_ configure api-pagination explicitly:
+
+```ruby
+ApiPagination.configure do |config|
+  config.paginator = :will_paginate
+end
+```
+
+If you don't do this, an annoying warning will print once your app starts seeing traffic. You should also configure Kaminari to use a different name for its `per_page` method (see https://github.com/activeadmin/activeadmin/wiki/How-to-work-with-will_paginate):
+
+```ruby
+Kaminari.configure do |config|
+  config.page_method_name = :per_page_kaminari
+end
+```
+
+[activeadmin]: https://github.com/activeadmin/activeadmin
 [kaminari]: https://github.com/amatsuda/kaminari
 [will_paginate]: https://github.com/mislav/will_paginate
 

lib/api-pagination/configuration.rb

@@ -1,7 +1,5 @@
 module ApiPagination
   class Configuration
-    attr_reader :paginator
-
     attr_accessor :total_header
 
     attr_accessor :per_page_header
@@ -13,11 +11,14 @@ def configure(&block)
     def initialize
       @total_header    = 'Total'
       @per_page_header = 'Per-Page'
-      set_paginator
+    end
+
+    def paginator
+      @paginator || set_paginator
     end
 
     def paginator=(paginator)
-      case paginator
+      case paginator.to_sym
       when :kaminari
         use_kaminari
       when :will_paginate
@@ -34,39 +35,26 @@ def set_paginator
         Kernel.warn <<-WARNING
 Warning: api-pagination relies on either Kaminari or WillPaginate, but both are
 currently active. If possible, you should remove one or the other. If you can't,
-you must configure api-pagination on your own. For example:
+you _must_ configure api-pagination on your own. For example:
 
 ApiPagination.configure do |config|
-  config.paginator = Kaminari
+  config.paginator = :kaminari
+end
+
+You should also configure Kaminari to use a different `per_page` method name as
+using these gems together causes a conflict; some information can be found at
+https://github.com/activeadmin/activeadmin/wiki/How-to-work-with-will_paginate
+
+Kaminari.configure do |config|
+  config.page_method_name = :per_page_kaminari
 end
 
 WARNING
       elsif defined?(Kaminari)
-        use_kaminari and return
+        return use_kaminari
       elsif defined?(WillPaginate::CollectionMethods)
-        use_will_paginate and return
-      end
-
-      begin
-        require 'kaminari'
-        use_kaminari and return
-      rescue LoadError
-      end
-
-      begin
-        require 'will_paginate'
-        use_will_paginate and return
-      rescue LoadError
+        return use_will_paginate
       end
-
-      Kernel.warn <<-WARNING
-Warning: api-pagination relies on either Kaminari or WillPaginate. Please
-install either dependency by adding one of the following to your Gemfile:
-
-gem 'kaminari'
-gem 'will_paginate'
-
-WARNING
     end
 
     def use_kaminari

lib/api-pagination/hooks.rb

@@ -15,3 +15,16 @@
   require 'grape/pagination'
   Grape::API.send(:include, Grape::Pagination)
 end
+
+begin; require 'kaminari';      rescue LoadError; end
+begin; require 'will_paginate'; rescue LoadError; end
+
+unless defined?(Kaminari) || defined?(WillPaginate::CollectionMethods)
+  Kernel.warn <<-WARNING.gsub(/^\s{4}/, '')
+    Warning: api-pagination relies on either Kaminari or WillPaginate. Please
+    install either dependency by adding one of the following to your Gemfile:
+
+    gem 'kaminari'
+    gem 'will_paginate'
+  WARNING
+end