next_page 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27b21fc2e5c1a3e37922ea3b59773ed5e77de3a280174483a2c21bed5bfb71bb
+  data.tar.gz: 8e7543e8bd5189c1a2971eefe1fd410eaabbf1148eae011ee4d43b9e9a9f3b03
+SHA512:
+  metadata.gz: 306a91bf0c79a6f6a55a1cd43460129884789f475bd2555ddb7c526cf73be99a2e112cef046ef268549f1dd46f9f58b0c9408b121cea9d82ae38ae8bc82b15a4
+  data.tar.gz: 36b53d6be6024623ffe2297b675fbfd67b9da94a29312d44112cad0405a977c7a319bb3300525e480c1494bf28b75138e400d703ce3fe645825b975645720f81

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Todd Kummer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,87 @@
+# NextPage
+Basic pagination for Rails controllers.
+
+## Usage
+Module Pagination provides pagination for index methods. It assigns a limit and offset to the resource query and extends the relation with mixin NextPage::PaginationAttributes to provide helper methods for generating links.
+
+### Include the Module
+Add an include statement for the module into any controller that needs pagination:
+
+```ruby
+include NextPage::Pagination
+```
+
+There are two ways to paginate: using a before filter or by calling `paginate_resource` explicitly.
+
+### Before Filter
+Here's an example of using the before filter in a controller:
+
+```ruby
+before_action :apply_next_page_pagination, only: :index
+```
+
+This entry point uses the following conventions to apply pagination:
+- the name of the instance variable is the sames as the component (for example PhotosController -> @photos)
+- the name of the models is the controller name singularized (for example PhotosController -> Photo)
+
+Either can be overridden by calling method `paginate_with` in the controller. The two override options are
+`instance_variable_name` and `model_class`. For example, if the PhotosController used the model Picture and the
+instance variable name @photographs, the controller declares it as follows:
+
+```ruby
+paginate_with instance_variable_name: :photographs, model_class: 'Picture'
+```
+
+If the before filter is used, it will populate an instance variable. The action should NOT reset the variable, as
+that removes pagination.
+
+### Invoking Pagination Directly
+To paginate a resource pass the resource into method `paginate_resource` then store the return value back in the
+resource:
+
+```ruby
+@photos = paginate_resource(@photos)
+```
+
+
+### Default Limit
+The default size limit can be overridden with the `paginate_with` method for either type of paginagion. Pass option
+`default_limit` to specify an override:
+
+```ruby
+paginate_with default_limit: 25
+```
+
+All the options can be mixed and matches when calling `paginate_with`:
+
+```ruby
+paginate_with model_class: 'Photo', default_limit: 12
+paginate_with default_limit: 12, instance_variable_name: 'data'
+```
+
+### Link Helpers
+This gem does not do any rendering. It does provide helper methods for generating links. The resource will include the following additional methods:
+- current_page
+- next_page
+- total_pages
+- per_page
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'next_page'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install next_page
+```
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'NextPage'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'

data/lib/next_page/pagination.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module NextPage
+  # = Pagination
+  #
+  # Module Pagination provides pagination for index methods. It assigns a limit and offset
+  # to the resource query and extends the relation with mixin NextPage::PaginationAttributes.
+  #
+  # There are two ways to paginate: using a before filter or by calling `paginate_resource` explicitly.
+  #
+  # == Before Filter
+  # Here's an example of using the before filter in a controller:
+  #   before_action :apply_next_page_pagination, only: :index
+  #
+  # This entry point uses the following conventions to apply pagination:
+  # - the name of the instance variable is the same as the component (for example PhotosController -> @photos)
+  # - the name of the model is the controller name singularized (for example PhotosController -> Photo)
+  #
+  # Either can be overridden by calling method `paginate_with` in the controller. The two override options are
+  # `instance_variable_name` and `model_class`. For example, if the PhotosController used the model Picture and the
+  # instance variable name @photographs, the controller declares it as follows:
+  #   paginate_with instance_variable_name: :photographs, model_class: 'Picture'
+  #
+  # If the before filter is used, it will populate an instance variable. The action should NOT reset the variable, as
+  # that removes pagination.
+  #
+  # == Invoking Pagination Directly
+  # To paginate a resource pass the resource into method `paginate_resource` then store the return value back in the
+  # resource:
+  #
+  #   @photos = paginate_resource(@photos)
+  #
+  # == Default Limit
+  # The default size limit can be overridden with the `paginate_with` method for either type of pagination. Pass option
+  # `default_limit` to specify an override:
+  #
+  #   paginate_with default_limit: 25
+  #
+  # All the options can be mixed and matches when calling `paginate_with`:
+  #
+  #   paginate_with model_class: 'Photo', default_limit: 12
+  #   paginate_with default_limit: 12, instance_variable_name: 'data'
+  module Pagination
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def next_page_paginator #:nodoc:
+        @next_page_paginator ||= NextPage::Paginator.new(controller_name, controller_path)
+      end
+
+      # Configure pagination with any of the following options:
+      # - instance_variable_name: explicitly name the variable if it does not follow the convention
+      # - model_class: explicitly specify the model name if it does not follow the convention
+      # - default_limit: specify an alternate default
+      def paginate_with(instance_variable_name: nil, model_class: nil, default_limit: nil)
+        next_page_paginator.paginate_with(instance_variable_name, model_class, default_limit)
+      end
+    end
+
+    # Called with before_action in order to automatically paginate the resource.
+    def apply_next_page_pagination
+      self.class.next_page_paginator.paginate(self, params[:page])
+    end
+
+    # Invokes pagination directly, the result must be stored as the resource itself is not modified.
+    def paginate_resource(resource)
+      self.class.next_page_paginator.paginate_resource(resource, params[:page])
+    end
+
+    def render(*args) #:nodoc:
+      return super unless action_name == 'index' && request.headers[:Accept] == 'application/vnd.api+json'
+
+      options = args.first
+      return super unless options.is_a?(Hash) && options.key?(:json)
+
+      options[:meta] = options.fetch(:meta, {}).merge!(total_pages: options[:json].total_pages)
+      super
+    end
+  end
+end

data/lib/next_page/pagination_attributes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module NextPage
+  # = Pagination Attributes
+  #
+  # Module PaginationAttributes adds in methods required for pagination links: current_page, next_page, and total_pages.
+  # It reads the offset and limit on the query to determine the values.
+  module PaginationAttributes
+    def current_page
+      @current_page ||= offset_value + 1
+    end
+
+    def next_page
+      current_page + 1
+    end
+
+    def total_pages
+      @total_pages ||= unscope(:limit).count / per_page
+    end
+
+    def per_page
+      @per_page ||= limit_value
+    end
+  end
+end

data/lib/next_page/paginator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module NextPage
+  # = Paginator
+  #
+  # Class Paginator uses the controller information to determine the model and variable name for the
+  # request, then applies a limit and offset to the query based upon the parameters or the defaults. It also extends
+  # the resource with the NextPage::PaginationAttributes mixin.
+  #
+  # Configuration can be specified in the controller by calling `paginate_with`. The following overrides can be
+  # specified if necessary:
+  # - default_limit: limit to use if request does not specify (default value is 10)
+  # - instance_variable_name: default value is the controller name; for example, @photos in PhotosController
+  # - model_class: default derived from controller name (or path if nested); for example, Photo for PhotosController
+  class Paginator
+    DEFAULT_LIMIT = 10
+
+    def initialize(controller_name, controller_path)
+      @controller_name = controller_name
+      @controller_path = controller_path
+
+      @default_limit = DEFAULT_LIMIT
+    end
+
+    def paginate_with(instance_variable_name, model_class, default_limit)
+      @default_limit = default_limit if default_limit.present?
+      @instance_variable_name = instance_variable_name
+      @model_class = model_class.is_a?(String) ? model_class.constantize : model_class
+    end
+
+    def paginate(controller, page_params)
+      name = "@#{instance_variable_name}"
+      data = controller.instance_variable_get(name) || model_class.all
+
+      controller.instance_variable_set(name, paginate_resource(data, page_params))
+    end
+
+    def paginate_resource(data, page_params)
+      data.extend(NextPage::PaginationAttributes)
+
+      limit = page_size(page_params)
+      offset = page_number(page_params) - 1
+      data.limit(limit).offset(offset * limit)
+    end
+
+    private
+
+    def model_class
+      @model_class ||= @controller_name.classify.safe_constantize ||
+                       @controller_path.classify.safe_constantize ||
+                       raise('Could not determine model for pagination; please specify using `paginate_with` options.')
+    end
+
+    def instance_variable_name
+      @instance_variable_name ||= @controller_name
+    end
+
+    def page_size(page)
+      if page.present? && page[:size].present?
+        page[:size]&.to_i
+      else
+        @default_limit
+      end
+    end
+
+    def page_number(page)
+      if page.present? && page[:number].present?
+        page[:number]&.to_i
+      else
+        1
+      end
+    end
+  end
+end

data/lib/next_page/version.rb

@@ -0,0 +1,3 @@
+module NextPage
+  VERSION = '0.1.0'
+end

data/lib/next_page.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'next_page/pagination'
+require 'next_page/pagination_attributes'
+require 'next_page/paginator'
+
+# = Next Page
+module NextPage
+end

data/lib/tasks/next_page_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :next_page do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: next_page
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Todd Kummer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.2
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.2.2
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: guard-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.77'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.77'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+description: Provide basic pagination, including page size and number as well as helpers
+  for generating links.
+email:
+- todd@rockridgesolutions.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/next_page.rb
+- lib/next_page/pagination.rb
+- lib/next_page/pagination_attributes.rb
+- lib/next_page/paginator.rb
+- lib/next_page/version.rb
+- lib/tasks/next_page_tasks.rake
+homepage: https://github.com/RockSolt/next_page
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.8
+signing_key: 
+specification_version: 4
+summary: Pagination for Rails Controllers
+test_files: []