wor-paginate 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2465192c522659e0f6e779d73cda2dfaa3fa47aca0966ebc9fd4292587143cea
-  data.tar.gz: d71ab589396a9f76e25849e63bec31a1fe5aafcd1dd54c3b9ca79104957cbee7
+  metadata.gz: 616213ea69272167621606631c90c60e4c14bdb5a2e31f933576ccc5d8dc04e8
+  data.tar.gz: 24486490fa441d027284f1ef4d53ec686d849dc21f0d12bbc81116ed51865c4e
 SHA512:
-  metadata.gz: 8ed75b64b43ffe168a35a09a054532c384d51470e3942964b8a60ac191644b264e8d42a59e73ceea3485a0cc7680162a74dcd9d81b5581a110bb8510f965dfcc
-  data.tar.gz: 93143a274cdbd3bbaffe3898fa4038de9173b6d916eab033e5ae13c8fcaceb63baefc8c7a4d0a6c6ffbb4fc2f6513c2d68769a533fdc05416d3d5336c256dfd8
+  metadata.gz: d3eb17ff497fae64cdc0edd117591ac02bc03b74669f82271475202e7d7d0d7c341c85804bbc93f7220751d28c45659265b1c68fd122557d8b558e00d7822d11
+  data.tar.gz: 8a76d0a58b6a8b9fb5af30e450de603a91fa8efd9de0f1e4a881cf813be5d19386b65fd60c7ed4d40d7b63c7a3ea4dd8d570f2a0f5ba08a7ebee3ce166e1fd82

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Change log
 
+### V0.3.0
+* [#94](https://github.com/Wolox/wor-paginate/pull/94) Add Panko formatter - [@blacksam07](https://github.com/blacksam07).
+* [#96](https://github.com/Wolox/wor-paginate/pull/96) Dynamic Adapters - [@juanpablo-rojas](https://github.com/juanpablo-rojas).
+
 ### V0.2.0
 * [#95](https://github.com/Wolox/wor-paginate/pull/95) Added total_count option to overwrite the count in render_paginated  - [@juanpablo-rojas](https://github.com/juanpablo-rojas).
 * [#93](https://github.com/Wolox/wor-paginate/pull/93) Infinite scroll - [@mnmallea](https://github.com/mnmallea).

data/Gemfile

@@ -23,6 +23,7 @@ group :development, :test do
   gem 'faker', '~> 1.7.0'
   gem 'generator_spec', '~> 0.9.0'
   gem 'kaminari', '~> 0.17.0'
+  gem 'panko_serializer', '~> 0.7.2'
   gem 'rake', '~> 10.0'
   gem 'rspec', '~> 3.0'
   gem 'rspec-rails', '~> 3.6.0'

data/README.md

@@ -14,6 +14,7 @@ Wor::Paginate
       - [Custom serializers](#custom-serializers)
       - [Custom options](#custom-options)
       - [Custom formatters](#custom-formatters)
+      - [Custom adapters](#custom-adapters)
     - [Working with Kaminari or will_paginate](#working-with-kaminari-or-will_paginate)
     - [Test helpers](#test-helpers)
   - [Contributing](#contributing)
@@ -170,7 +171,7 @@ end
 ```
 
 
-#### Custom formatters
+### Custom formatters
 A formatter is an object that defines the output of the render_paginated method. In case the application needs a different format for a request, it can be passed to the `render_paginated` method using the `formatter` option:
 ```ruby
 render_paginated DummyModel, formatter: CustomFormatter
@@ -180,7 +181,7 @@ or it can also be set as a default in the initializer.
 A new formatter can be created inheriting from the default one. The `format` method should be redefined returning something that can be converted to json.
 
 ```ruby
-class CustomFormatter < Wor::Paginate::Formatter
+class CustomFormatter < Wor::Paginate::Formatters::Base
   def format
     { page: serialized_content, current: current_page }
   end
@@ -195,6 +196,74 @@ Available helper methods are:
 * `paginated_content`: its class depends on the original content passed to render_paginated, it's the paginated but not yet serialized content.
 * `serialized_content`: array with all the items after going through the serializer (either the default or a supplied one)
 
+
+### Custom adapters
+An adapter is an object that defines how to show the rendered content, and how to calculate several methods of the pagination, such as 'total_count', 'total_pages', 'paginated_content' among others. In case the application needs a different adapter or a custom one, it can be passed to the `render_paginated` method using the `adapter` option:
+```ruby
+render_paginated DummyModel, adapter: CustomAdapter
+```
+or it can also be set as a default in the initializer.
+
+A new adapter can be created inheriting from the default Base Adapter. Some methods must be redefined in order to make the adapter "adaptable" to the content that will be rendered.
+Below is an example of a simple posible CustomAdapter that extends from the base Adapter.
+
+```ruby
+class CustomAdapter < Wor::Paginate::Adapters::Base
+  def required_methods
+    %i[count]
+  end
+
+  def paginated_content
+    @paginated_content ||= @content.first(5)
+  end
+
+  def total_pages
+    (total_count / @limit.to_f).ceil
+  end
+
+  def total_count
+    @content.count
+  end
+
+  delegate :count, to: :paginated_content
+end
+```
+Here's a brief explanation on every overwritten method in this CustomAdapter example:
+
+##### `#required_methods`
+These will be the methods (as symbols) that the content to be rendered has to support. The next expression will be evaluated for every method added here: `@content.respond_to? method`. All required_methods must answer `true` to the previous expression, in order to make the adapter "adaptable" for the content. For example, if we rendered an ActiveRecord::Relation, this CustomAdapter would be adaptable because an ActiveRecord::Relation responds to the `#count` method. At least one symbol has to be returned in this method, otherwise the adapter won't be able to render content. 
+
+##### `#paginated_content`
+This is how the content will be shown. As the content comes in the inherited instance variable `@content`, we can transform the content however we want. In the CustomAdapter example, will always be shown the first 5 records.
+
+##### `#total_pages`
+This could be defined as the number of pages, given the limit requested. As the other values, this can be a custom number of pages, depending on your needs. For this example, this number is just an integer calculation of the total pages, depending on the limit. Also, like `@content`, we are inheriting the `@limit` variable, which allows us to operate with it however we want.
+
+##### `#total_count`
+This will be the number that will tell us 'how many records is returning the request'. Again, we can customize it however we want. For this particular example this will be just the count of `@content`.
+
+##### `#count` method as delegate
+In the end of the CustomAdapter we are delegating the `#count` method to the `paginated_content`. This is because the Base Adapter delegates that method to the inherited adapter, so our custom adapter has to know "how to calculate" that method, that's why we are defining a `#count` method in the delegation (It is always mandatory to define the `#count` method in a custom adapter, whether is a method definition or a delegate).
+
+If the content is an ActiveRecord::Relation, for example, this adapter would work, because `paginated_content` would become an ActiveRecord::Relation, which actually knows "how to calculate" the count method. This works as a delegate, because ActiveRecord::Relation has an internal `#count` definition, but we would have to provide the needed method definition if it is a custom method, or we want a custom behaviour of a known method.
+
+##### Other available methods to overwrite
+`Wor::Paginate::Adapters::Base` also has implementations for `#next_page` and `#previous_page` methods (which calculate the number of the next and previous pages, respectively). If you want, you can also overwrite those methods, to calculate custom 'next' and 'previous' page numbers.
+
+To understand better the implementation of the Base Adapter and how you could overwrite methods in order to make a functional Custom Adapter, take a look at its definition in: [Base adapter Class](https://github.com/Wolox/wor-paginate/blob/master/lib/wor/paginate/adapters/base.rb).
+Keep in mind that an instance of your Custom Adapter must answer `true` to the `#adapt?` method inherited from the Base Adapter, in order to make it "adaptable" to the content.
+
+#### Adapters Operations
+There are also helper methods available to dynamically operate the gem's adapters, so you can configurate them, whether in the initializer or in an internal part of your application. Once you include the gem, you'll be provided with the following methods, inside the Config module:
+* `Wor::Paginate::Config.add_adapter(adapter)`: Add a specific adapter to the array of the gem's adapters. The 'adapter' variable must be a Class reference to an Adapter Class (that class has to have a similar structure as the CustomAdapter example above).
+* `Wor::Paginate::Config.remove_adapter(adapter)`: Remove an specific adapter from the array of the gem's adapters.
+* `Wor::Paginate::Config.clear_adapters`: This method empties the array of the gem's adapters.
+* `Wor::Paginate::Config.adapters`: Returns all the current internal adapters inside the gem.
+* `Wor::Paginate::Config.reset_adapters!`: This helper resets the gem's adapters to its default array of adapters. You can see how the array of default adapters looks like at the beggining of the `Wor::Paginate::Config` module: [Config module](https://github.com/Wolox/wor-paginate/blob/master/lib/wor/paginate/config.rb).
+
+When the gem paginates, it tries to adapt the content to the first adapter that is "adaptable" for the content (unless a custom adapter has been passed to render_paginated or a default_adapter has been defined in the initializer). So beware of which adapters (and in which order) are you leaving in the `Wor::Paginate::Config.adapters` array, because depending on those, the gem will try to adapt the content.
+
+
 ### Working with Kaminari or will_paginate
 If either Kaminari or will_paginate are required in the project, Wor::Paginate will use them for pagination with no code or configuration change.
 
@@ -232,6 +301,24 @@ describe YourController do
 end
 ```
 
+### Working with panko-serializer
+
+The default formatter is [Active Model Serializer](https://github.com/rails-api/active_model_serializers).
+If you want to change it, you should replace the formatter to another one. In this section, we are going to work with `PankoFormatter`
+
+#### example 
+```ruby
+Wor::Paginate.configure do |config
+  config.formatter = Wor::Paginate::Formatters::PankoFormatter
+end
+```
+and next pass the specific serializer that you can use in the specific endpoint
+
+```ruby
+  def index
+    render_paginated DummyModel, each_serializer: DummyModelPankoSerializer
+  end
+```
 ## Contributing
 
 1. Fork it

data/lib/generators/templates/wor_paginate.rb

@@ -6,10 +6,10 @@ Wor::Paginate.configure do |config|
   config.per_page_param = :limit
 
   # In case you want to use other format for your response, you can override our formatter here
-  # You can extend from Wor::Paginate::Formatter and override the 'format' method
+  # You can extend from Wor::Paginate::Formatters::Base and override the 'format' method
   # For more info about available methods for formatters see:
-  # https://github.com/Wolox/wor-paginate/blob/master/lib/wor/paginate/formatter.rb
-  # config.formatter = Wor::Paginate::Formatter
+  # https://github.com/Wolox/wor-paginate/blob/master/lib/wor/paginate/formatters/base.rb
+  # config.formatter = Wor::Paginate::Formatters::AmsFormatter
 
   # Configure a default adapter to use on pagination
   # config.default_adapter = nil
@@ -22,4 +22,19 @@ Wor::Paginate.configure do |config|
   # Wor::Paginate::Adapters::Kaminari
   # Wor::Paginate::Adapters::ActiveRecord
   # Wor::Paginate::Adapters::Enumerable
+
+  # Custom adapters
+
+  # config.adapters = [
+  # Adapters::KaminariAlreadyPaginated,
+  # Adapters::WillPaginateAlreadyPaginated,
+  # Adapters::WillPaginate,
+  # Adapters::Kaminari,
+  # Adapters::ActiveRecord,
+  # Adapters::Enumerable
+  # ]
+  # config.add_adapter(adapter)
+  # config.remove_adapter(adapter)
+  # config.clear_adapters
+  # config.reset_adapters!
 end

data/lib/wor/paginate.rb

@@ -5,10 +5,13 @@ require_relative 'paginate/adapters/kaminari'
 require_relative 'paginate/adapters/will_paginate'
 require_relative 'paginate/adapters/kaminari_already_paginated'
 require_relative 'paginate/adapters/will_paginate_already_paginated'
+require_relative 'paginate/exceptions/dependency_error'
 require_relative 'paginate/exceptions/no_pagination_adapter'
 require_relative 'paginate/exceptions/invalid_page_number'
 require_relative 'paginate/exceptions/invalid_limit_number'
-require_relative 'paginate/formatter'
+require_relative 'paginate/formatters/base'
+require_relative 'paginate/formatters/panko_formatter'
+require_relative 'paginate/formatters/ams_formatter'
 require_relative 'paginate/config'
 require_relative 'paginate/paginate'
 
@@ -17,7 +20,7 @@ module Wor
     def self.configure
       yield Config
 
-      return if ADAPTERS.include?(Config.default_adapter) || Config.default_adapter.nil?
+      return if Config.adapters.any? || Config.default_adapter.present?
 
       raise Exceptions::NoPaginationAdapter
     end

data/lib/wor/paginate/config.rb

@@ -6,11 +6,22 @@ module Wor
         default_page: 1,
         page_param: :page,
         per_page_param: :limit,
-        formatter: Wor::Paginate::Formatter,
+        formatter: Wor::Paginate::Formatters::Base,
         max_limit: 50,
         default_adapter: nil
       }.freeze
 
+      DEFAULT_ADAPTERS = {
+        kaminari_paginated: Adapters::KaminariAlreadyPaginated,
+        will_paginate_paginated: Adapters::WillPaginateAlreadyPaginated,
+        will_paginate: Adapters::WillPaginate,
+        kaminari: Adapters::Kaminari,
+        active_record: Adapters::ActiveRecord,
+        enumerable: Adapters::Enumerable
+      }.freeze
+
+      @adapters = DEFAULT_ADAPTERS.values
+
       module_function
 
       DEFAULTS_CONFIGS.each do |key, value|
@@ -23,10 +34,30 @@ module Wor
         end
       end
 
+      def add_adapter(adapter)
+        @adapters << adapter
+      end
+
+      def remove_adapter(adapter)
+        @adapters.delete(adapter)
+      end
+
+      def clear_adapters
+        @adapters.clear
+      end
+
+      def adapters
+        @adapters
+      end
+
       # This is mostly useful for the tests
       def reset!
         DEFAULTS_CONFIGS.each { |k, v| send("#{k}=", v) }
       end
+
+      def reset_adapters!
+        @adapters = DEFAULT_ADAPTERS.values
+      end
     end
   end
 end

data/lib/wor/paginate/exceptions/dependency_error.rb

@@ -0,0 +1,11 @@
+module Wor
+  module Paginate
+    module Exceptions
+      class DependencyError < StandardError
+        def initialize(msg = 'Serializer dependency error')
+          super(msg)
+        end
+      end
+    end
+  end
+end

data/lib/wor/paginate/formatters/ams_formatter.rb

@@ -0,0 +1,31 @@
+module Wor
+  module Paginate
+    module Formatters
+      class AmsFormatter < Base
+        include ActiveSupport::Callbacks
+        define_callbacks :raise_dependency_error
+        set_callback :raise_dependency_error, :before, :serialized_content, unless: :ams_defined?
+
+        def serialized_content
+          return serializable_resource.new(paginated_content).as_json unless serializer.present?
+          raise_dependency_error unless serializer.respond_to?('_attributes_data')
+          paginated_content.map { |item| serializer.new(item, options) }
+        end
+
+        private
+
+        def serializable_resource
+          ActiveModelSerializers::SerializableResource
+        end
+
+        def ams_defined?
+          defined? serializable_resource
+        end
+
+        def raise_dependency_error
+          raise Wor::Paginate::Exceptions::DependencyError
+        end
+      end
+    end
+  end
+end

data/lib/wor/paginate/formatters/base.rb

@@ -0,0 +1,61 @@
+require 'wor/paginate/utils/uri_helper'
+
+module Wor
+  module Paginate
+    module Formatters
+      class Base
+        include Utils::UriHelper
+        attr_accessor :adapter, :content, :formatter, :options
+
+        def initialize(adapter, options = {})
+          @adapter = adapter
+          @options = options
+        end
+
+        def format # rubocop: disable Metrics/MethodLength
+          {
+            page: serialized_content,
+            count: count,
+            total_pages: total_pages,
+            total_count: options[:total_count] || total_count,
+            current_page: current_page,
+            previous_page: previous_page,
+            next_page: next_page,
+            next_page_url: page_url(next_page),
+            previous_page_url: page_url(previous_page)
+          }
+        end
+
+        protected
+
+        delegate :count, :total_count, :total_pages, :previous_page, :next_page, to: :adapter
+
+        def current_page
+          adapter.page.to_i
+        end
+
+        def paginated_content
+          @content ||= adapter.paginated_content
+        end
+
+        def serialized_content
+          paginated_content.as_json
+        end
+
+        def serializer
+          options[:each_serializer]
+        end
+
+        def page_url(page)
+          return nil unless page
+
+          replace_query_params(current_url, page: page)
+        end
+
+        def current_url
+          options[:_current_url]
+        end
+      end
+    end
+  end
+end

data/lib/wor/paginate/formatters/panko_formatter.rb

@@ -0,0 +1,20 @@
+module Wor
+  module Paginate
+    module Formatters
+      class PankoFormatter < Base
+        def serialized_content
+          raise Wor::Paginate::Exceptions::DependencyError unless valid_serializer
+          ActiveRecord::Base.transaction do
+            Panko::ArraySerializer.new(paginated_content, each_serializer: serializer).to_a
+          end
+        rescue ActiveRecord::StatementInvalid
+          retry
+        end
+
+        def valid_serializer
+          serializer.respond_to?('_descriptor') && defined?(Panko::Serializer)
+        end
+      end
+    end
+  end
+end

data/lib/wor/paginate/paginate.rb

@@ -2,17 +2,6 @@ require_relative 'utils/preserve_records_helper'
 
 module Wor
   module Paginate
-    # The order of this array is important!
-    # In a future release we'll provide an interface to manipulate it
-    ADAPTERS = [
-      Adapters::KaminariAlreadyPaginated,
-      Adapters::WillPaginateAlreadyPaginated,
-      Adapters::WillPaginate,
-      Adapters::Kaminari,
-      Adapters::ActiveRecord,
-      Adapters::Enumerable
-    ].freeze
-
     def render_paginated(content, options = {})
       return render_paginate_with_include(content, options) if includes?(options)
 
@@ -21,18 +10,15 @@ module Wor
 
     def paginate(content, options = {})
       current_url = request.original_url
-
       if (preserve_records = options[:preserve_records])
         content, current_url = Wor::Paginate::Utils::PreserveRecordsHelper
                                .new(content, current_url,
                                     preserve_records.is_a?(Hash) ? preserve_records : {}).call
       end
-
       adapter = find_adapter_for_content(content, options)
       raise Exceptions::NoPaginationAdapter if adapter.blank?
 
-      formatter_class(options).new(adapter, options.merge(_current_url: current_url))
-                              .format
+      formatter_class(options).new(adapter, options.merge(_current_url: current_url)).format
     end
 
     def render_paginate_with_include(content, options)
@@ -40,15 +26,20 @@ module Wor
     end
 
     def formatter_class(options)
-      options[:formatter].presence || Formatter
+      options[:formatter].presence || Config.formatter
     end
 
     def find_adapter_for_content(content, options)
+      return instance_adapter(options[:adapter], content, options) unless options[:adapter].nil?
+
       adapters = []
       adapters << Config.default_adapter if Config.default_adapter.present?
-      adapters += ADAPTERS
-      adapters.map { |adapter| adapter.new(content, page(options), limit(options)) }
-              .find(&:adapt?)
+      adapters += Config.adapters
+      adapters.map { |adapter| instance_adapter(adapter, content, options) }.find(&:adapt?)
+    end
+
+    def instance_adapter(adapter, content, options)
+      adapter.new(content, page(options), limit(options))
     end
 
     def page(options)

data/lib/wor/paginate/rspec.rb

@@ -29,7 +29,7 @@ end
 RSpec::Matchers.define :be_paginated do
   match do |actual_response|
     response = parse_response(actual_response)
-    formatter = @custom_formatter || Wor::Paginate::Formatter
+    formatter = @custom_formatter || Wor::Paginate::Formatters::Base
     @formatted_keys = formatter.new(MockedAdapter.new, _current_url: 'http://exaple.com/').format.as_json.keys
     response.keys == @formatted_keys
   end

data/lib/wor/paginate/version.rb

@@ -1,5 +1,5 @@
 module Wor
   module Paginate
-    VERSION = '0.2.0'.freeze
+    VERSION = '0.3.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wor-paginate
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - icoluccio
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2020-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -74,10 +74,13 @@ files:
 - lib/wor/paginate/adapters/will_paginate.rb
 - lib/wor/paginate/adapters/will_paginate_already_paginated.rb
 - lib/wor/paginate/config.rb
+- lib/wor/paginate/exceptions/dependency_error.rb
 - lib/wor/paginate/exceptions/invalid_limit_number.rb
 - lib/wor/paginate/exceptions/invalid_page_number.rb
 - lib/wor/paginate/exceptions/no_pagination_adapter.rb
-- lib/wor/paginate/formatter.rb
+- lib/wor/paginate/formatters/ams_formatter.rb
+- lib/wor/paginate/formatters/base.rb
+- lib/wor/paginate/formatters/panko_formatter.rb
 - lib/wor/paginate/paginate.rb
 - lib/wor/paginate/rspec.rb
 - lib/wor/paginate/utils/preserve_modes.rb
@@ -106,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Simplified pagination for Rails API controllers

data/lib/wor/paginate/formatter.rb

@@ -1,66 +0,0 @@
-require_relative 'utils/uri_helper'
-
-module Wor
-  module Paginate
-    class Formatter
-      include Utils::UriHelper
-      attr_accessor :adapter, :content, :formatter, :options
-
-      def initialize(adapter, options = {})
-        @adapter = adapter
-        @options = options
-      end
-
-      def format # rubocop: disable Metrics/MethodLength
-        {
-          page: serialized_content,
-          count: count,
-          total_pages: total_pages,
-          total_count: options[:total_count] || total_count,
-          current_page: current_page,
-          previous_page: previous_page,
-          next_page: next_page,
-          next_page_url: page_url(next_page),
-          previous_page_url: page_url(previous_page)
-        }
-      end
-
-      protected
-
-      delegate :count, :total_count, :total_pages, :previous_page, :next_page, to: :adapter
-
-      def current_page
-        adapter.page.to_i
-      end
-
-      def paginated_content
-        @content ||= adapter.paginated_content
-      end
-
-      def serialized_content
-        if serializer.present?
-          return paginated_content.map { |item| serializer.new(item, options) }
-        end
-        if defined? ActiveModelSerializers::SerializableResource
-          ActiveModelSerializers::SerializableResource.new(paginated_content).as_json
-        else
-          paginated_content.as_json
-        end
-      end
-
-      def serializer
-        options[:each_serializer]
-      end
-
-      def page_url(page)
-        return nil unless page
-
-        replace_query_params(current_url, page: page)
-      end
-
-      def current_url
-        options[:_current_url]
-      end
-    end
-  end
-end