Add ApiPagination::Configuration

Add a configuration object that handles names of Total and Per-Page
headers, as well as allows for the manual setting of the paginator that
ApiPagination will use. It's up to the user to make WillPaginate and
Kaminari play nicely together if they include both. Closes #33

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

Author: davidcelis

CONTRIBUTING.md

@@ -3,6 +3,6 @@
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes and tests (`git commit -am 'Add some feature'`)
-4. Run the tests (`PAGINATOR=kaminari bundle exec rspec; PAGINATOR=will_paginate bundle exec rspec`)
+4. Run the tests (`PAGINATOR=Kaminari bundle exec rspec; PAGINATOR=WillPaginate bundle exec rspec`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request

README.md

@@ -25,6 +25,23 @@ gem 'will_paginate'
 gem 'api-pagination'
 ```
 
+## Configuration (optional)
+
+By default, api-pagination will detect whether you're using Kaminari or WillPaginate, and name headers appropriately. If you want to change any of the configurable settings, you may do so:
+
+```ruby
+ApiPagination.configure do |config|
+  # If you have both gems included, you can choose a paginator.
+  config.paginator = :kaminari # or :will_paginate
+
+  # By default, this is set to 'Total'
+  config.total_header = 'X-Total'
+
+  # By default, this is set to 'Per-Page'
+  config.per_page_header = 'X-Per-Page'
+end
+```
+
 ## Rails
 
 In your controller, provide a pageable collection to the `paginate` method. In its most convenient form, `paginate` simply mimics `render`:
@@ -116,27 +133,6 @@ Per-Page: 10
 # ...
 ```
 
-If you want, you can customize the name of `Total` and `Per-Page` headers.  
-All you need to do is to set the `total_header` or `per_page_header` on `ApiPagination`.  
-If nothing is setted it defaults to `Total` and `Per-Page`.
-
-```ruby
-ApiPagination.total_header = 'X-Total-Count'
-ApiPagination.per_page_header = 'X-Per-Page'
-```
-
-```bash
-$ curl --include 'https://localhost:3000/movies?page=5'
-HTTP/1.1 200 OK
-Link: <http://localhost:3000/movies?page=1>; rel="first",
-  <http://localhost:3000/movies?page=173>; rel="last",
-  <http://localhost:3000/movies?page=6>; rel="next",
-  <http://localhost:3000/movies?page=4>; rel="prev"
-X-Total-Count: 4321
-X-Per-Page: 10
-# ...
-```
-
 [kaminari]: https://github.com/amatsuda/kaminari
 [will_paginate]: https://github.com/mislav/will_paginate
 

lib/api-pagination.rb

@@ -1,34 +1,20 @@
+require 'api-pagination/configuration'
 require 'api-pagination/version'
 
 module ApiPagination
   class << self
-    attr_reader :paginator
-    attr_writer :total_header, :per_page_header
-
     def paginate(collection, options = {})
       options[:page]     = options[:page].to_i
       options[:page]     = 1 if options[:page] <= 0
       options[:per_page] = options[:per_page].to_i
 
-      case ApiPagination.paginator
+      case ApiPagination.config.paginator
       when :kaminari
-        if Kaminari.config.max_per_page && options[:per_page] > Kaminari.config.max_per_page
-          options[:per_page] = Kaminari.config.max_per_page
-        elsif options[:per_page] <= 0
-          options[:per_page] = Kaminari.config.default_per_page
-        end
-        collection = Kaminari.paginate_array(collection) if collection.is_a?(Array)
-        collection.page(options[:page]).per(options[:per_page])
+        paginate_with_kaminari(collection, options)
       when :will_paginate
-        options[:per_page] = WillPaginate.per_page if options[:per_page] <= 0
-
-        if defined?(Sequel::Dataset) && collection.kind_of?(Sequel::Dataset)
-          collection.paginate(options[:page], options[:per_page])
-        else
-          collection.paginate(:page => options[:page], :per_page => options[:per_page])
-        end
+        paginate_with_will_paginate(collection, options)
       else
-        raise StandardError, "Unknown paginator: #{ApiPagination.paginator}"
+        raise StandardError, "Unknown paginator: #{ApiPagination.config.paginator}"
       end
     end
 
@@ -47,18 +33,48 @@ def pages_from(collection)
     end
 
     def total_from(collection)
-      case ApiPagination.paginator
+      case ApiPagination.config.paginator
         when :kaminari      then collection.total_count.to_s
         when :will_paginate then collection.total_entries.to_s
       end
     end
 
-    def total_header
-      @total_header ||= 'Total'
+    def paginator
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.paginator"
+      config.paginator
     end
 
     def per_page_header
-      @per_page_header ||= 'Per-Page'
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.per_page_header"
+      config.per_page_header
+    end
+
+    def total_header
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.total_header"
+      config.total_header
+    end
+
+    private
+
+    def paginate_with_kaminari(collection, options)
+      if Kaminari.config.max_per_page && options[:per_page] > Kaminari.config.max_per_page
+        options[:per_page] = Kaminari.config.max_per_page
+      elsif options[:per_page] <= 0
+        options[:per_page] = Kaminari.config.default_per_page
+      end
+
+      collection = Kaminari.paginate_array(collection) if collection.is_a?(Array)
+      collection.page(options[:page]).per(options[:per_page])
+    end
+
+    def paginate_with_will_paginate(collection, options)
+      options[:per_page] = WillPaginate.per_page if options[:per_page] <= 0
+
+      if defined?(Sequel::Dataset) && collection.kind_of?(Sequel::Dataset)
+        collection.paginate(options[:page], options[:per_page])
+      else
+        collection.paginate(:page => options[:page], :per_page => options[:per_page])
+      end
     end
   end
 end

lib/api-pagination/configuration.rb

@@ -0,0 +1,97 @@
+module ApiPagination
+  class Configuration
+    attr_reader :paginator
+
+    attr_accessor :total_header
+
+    attr_accessor :per_page_header
+
+    def configure(&block)
+      yield self
+    end
+
+    def initialize
+      @total_header    = 'Total'
+      @per_page_header = 'Per-Page'
+      set_paginator
+    end
+
+    def paginator=(paginator)
+      case paginator
+      when :kaminari
+        use_kaminari
+      when :will_paginate
+        use_will_paginate
+      else
+        raise StandardError, "Unknown paginator: #{paginator}"
+      end
+    end
+
+    private
+
+    def set_paginator
+      if defined?(Kaminari) && defined?(WillPaginate::CollectionMethods)
+        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:
+
+ApiPagination.configure do |config|
+  config.paginator = Kaminari
+end
+
+WARNING
+      elsif defined?(Kaminari)
+        use_kaminari and return
+      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
+      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
+      require 'kaminari/models/array_extension'
+      @paginator = :kaminari
+    end
+
+    def use_will_paginate
+      WillPaginate::CollectionMethods.module_eval do
+        def first_page?() !previous_page end
+        def last_page?() !next_page end
+      end
+
+      @paginator = :will_paginate
+    end
+  end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+    alias :configuration :config
+  end
+end

lib/api-pagination/hooks.rb

@@ -1,77 +1,17 @@
-module ApiPagination
-  class Hooks
-    def self.init!
-      begin; require 'rails'; rescue LoadError; end
-      if defined?(ActionController::Base)
-        require 'rails/pagination'
-        ActionController::Base.send(:include, Rails::Pagination)
-      end
-
-      begin; require 'rails-api'; rescue LoadError; end
-      if defined?(ActionController::API)
-        require 'rails/pagination'
-        ActionController::API.send(:include, Rails::Pagination)
-      end
-
-      begin; require 'grape'; rescue LoadError; end
-      if defined?(Grape::API)
-        require 'grape/pagination'
-        Grape::API.send(:include, Grape::Pagination)
-      end
-
-      # Kaminari and will_paginate conflict with each other, so we should check
-      # to see if either is already active before attempting to load them.
-      if defined?(Kaminari) && defined?(WillPaginate::CollectionMethods)
-        STDERR.puts <<-EOC
-Warning: api-pagination relies on either Kaminari or WillPaginate, but these
-gems conflict.  Please ensure only one of them is active at any given time.
-
-EOC
-        return
-      elsif defined?(Kaminari)
-        initialize_kaminari! and return
-      elsif defined?(WillPaginate::CollectionMethods)
-        initialize_will_paginate! and return
-      end
-      # If neither is loaded, we can safely attempt these requires.
-      unless ApiPagination.paginator == :will_paginate
-        begin
-          require 'kaminari'
-          initialize_kaminari! and return
-        rescue LoadError
-        end
-      end
-
-      begin
-        require 'will_paginate'
-        initialize_will_paginate! and return
-      rescue LoadError
-      end
-
-      STDERR.puts <<-EOC
-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'
-
-EOC
-    end
-
-    def self.initialize_kaminari!
-      require 'kaminari/models/array_extension'
-      ApiPagination.instance_variable_set(:@paginator, :kaminari)
-    end
-
-    def self.initialize_will_paginate!
-      WillPaginate::CollectionMethods.module_eval do
-        def first_page?() !previous_page end
-        def last_page?() !next_page end
-      end
+begin; require 'rails'; rescue LoadError; end
+if defined?(ActionController::Base)
+  require 'rails/pagination'
+  ActionController::Base.send(:include, Rails::Pagination)
+end
 
-      ApiPagination.instance_variable_set(:@paginator, :will_paginate)
-    end
-  end
+begin; require 'rails-api'; rescue LoadError; end
+if defined?(ActionController::API)
+  require 'rails/pagination'
+  ActionController::API.send(:include, Rails::Pagination)
 end
 
-ApiPagination::Hooks.init!
+begin; require 'grape'; rescue LoadError; end
+if defined?(Grape::API)
+  require 'grape/pagination'
+  Grape::API.send(:include, Grape::Pagination)
+end

lib/grape/pagination.rb

@@ -20,8 +20,8 @@ def paginate(collection)
             links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
           end
 
-          total_header    = ApiPagination.total_header
-          per_page_header = ApiPagination.per_page_header
+          total_header    = ApiPagination.config.total_header
+          per_page_header = ApiPagination.config.per_page_header
 
           header 'Link',          links.join(', ') unless links.empty?
           header total_header,    ApiPagination.total_from(collection)

lib/rails/pagination.rb

@@ -39,8 +39,8 @@ def _paginate_collection(collection, options={})
         links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
       end
 
-      total_header    = ApiPagination.total_header
-      per_page_header = ApiPagination.per_page_header
+      total_header    = ApiPagination.config.total_header
+      per_page_header = ApiPagination.config.per_page_header
 
       headers['Link']          = links.join(', ') unless links.empty?
       headers[total_header]    = ApiPagination.total_from(collection)

spec/grape_spec.rb

@@ -69,15 +69,15 @@
 
     context 'with custom response headers' do
       before do
-        ApiPagination.total_header    = 'X-Total-Count'
-        ApiPagination.per_page_header = 'X-Per-Page'
+        ApiPagination.config.total_header    = 'X-Total-Count'
+        ApiPagination.config.per_page_header = 'X-Per-Page'
 
         get '/numbers', count: 10
       end
 
       after do
-        ApiPagination.total_header    = nil
-        ApiPagination.per_page_header = nil
+        ApiPagination.config.total_header    = 'Total'
+        ApiPagination.config.per_page_header = 'Per-Page'
       end
 
       let(:total) { last_response.header['X-Total-Count'].to_i }