smart_paginate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 70dd5154721fd339facb7008e3088db09d599160
+  data.tar.gz: 85b59219f3271aacfde2867f049ec9db8ba8f1c7
+SHA512:
+  metadata.gz: 06cf0656bfaa91e5f2fd57ec9f62477dbea410ed8e813536098f82cf426858a868b132082e127a0f302108af62d0aa26a4fe05710ec08fa60f084e75181df6b6
+  data.tar.gz: c19e2c4186646659811d5c78ca3d0527dc6f1c58ae81dd46f67c9ab2cc438a4172ce64155dfe70a00046f3897dae06c063fd41af3ac59a10d834711cd3877502

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.ruby-version
+.ruby-gemset

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,29 @@
+AllCops:
+  TargetRubyVersion: 2.2
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+
+Metrics/LineLength:
+  Enabled: false
+
+Style/BlockComments:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Style/Documentation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/MutableConstant:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,6 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.1.9
+  - 2.2.5
+before_install: gem install bundler -v 1.12.5

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in smart_paginate.gemspec
+gemspec
+
+gem 'rubocop', '~> 0.40.0', group: :test

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Peter Postma
+
+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,96 @@
+# SmartPaginate
+
+[![Build Status](https://travis-ci.org/ppostma/smart_paginate.svg?branch=master)](https://travis-ci.org/ppostma/smart_paginate)
+
+Simple, smart and clean pagination extension for Active Record and plain Ruby Arrays:
+
+- **Simple:** Easy to use, with a simple interface. It just does pagination, nothing more.
+- **Smart:** Can navigate through the pages without having to do an expensive count query. SmartPaginate will actually fetch one record more than needed and use it to determine if there's a next page.
+- **Clean:** The code is as minimal as possible while still useful. SmartPaginate does not auto include itself or monkey patch any classes.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'smart_paginate'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install smart_paginate
+
+## Usage
+
+### Active Record
+
+To enable pagination in an Active Record model, include the `SmartPaginate` concern in your class:
+
+```ruby
+class User
+  include SmartPaginate
+end
+```
+
+Then you can use the `paginate` scope to paginate results:
+
+```ruby
+users = User.order(:name).paginate(page: 1, per_page: 20)
+```
+
+After using `paginate`, the following methods will be available to query the next page, number of pages, etc:
+
+```ruby
+users.next_page?      # true when a next page exists
+users.next_page       # returns next page number
+users.previous_page?  # true when a previous page exists
+users.previous_page   # returns previous page number
+users.total_entries   # returns total number of entries (!)
+users.total_pages     # returns total number of pages (!)
+```
+
+**(!) Please note** that the `total_entries` and `total_pages` methods will do a `SELECT COUNT(*)` query to retrieve the total number of entries. This can be very expensive on a table with many records!
+
+### Array
+
+For paginating Arrays, use the class `SmartPaginate::PaginatingArray` to convert a plain Array to a paginatable Array:
+
+```ruby
+array = (1..100).to_a
+array = SmartPaginate::PaginatingArray(array)
+array.paginate(page: 1, per_page: 20)
+```
+
+### Helpers
+
+Because SmartPaginate was designed to be as simple and clean as possible, it does not provide any helpers to create pagination links in your views. It is however very easy to write your own, e.g. for Rails:
+
+```ruby
+module PaginateHelper
+  def paginate(collection, options = {})
+    content_tag(:div, class: "pagination") do
+      if collection.present?
+        options = options.merge(params)
+
+        concat link_to("Previous", url_for(options.merge(per_page: collection.per_page, page: collection.previous_page)), class: "previous_page") if collection.previous_page?
+        concat link_to("Next", url_for(options.merge(per_page: collection.per_page, page: collection.next_page)), class: "next_page") if collection.next_page?
+      end
+    end
+  end
+end
+```
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ppostma/smart_paginate.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task default: [:spec, :rubocop]

data/lib/smart_paginate/active_record.rb

@@ -0,0 +1,98 @@
+require "smart_paginate/paginate"
+require "active_support/concern"
+require "active_record"
+
+module SmartPaginate
+  module ActiveRecord
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def paginate(options = {})
+        page = SmartPaginate::Paginate.new(options.fetch(:page), options[:per_page])
+
+        rel = all.extending(RelationMethods)
+        # add one more to the limit so we can quickly determine if there are more pages present
+        rel = rel.limit(page.per_page + 1).offset(page.offset)
+        rel.current_page = page.current_page
+        rel.per_page = page.per_page
+        rel
+      end
+    end
+
+    module RelationMethods
+      attr_accessor :current_page, :per_page
+
+      # Override #count: make it return the number of entries that we expect
+      def count(*args)
+        if limit_value && per_page && limit_value > per_page
+          rel = except(:limit).limit(per_page)
+          rel.count
+        else
+          super(*args)
+        end
+      end
+
+      # Override #empty: check fetched records instead of counting
+      def empty?
+        load # make sure we have determined the number of fetched records
+
+        @number_of_records.zero?
+      end
+
+      # Override #load: fetch/slice records and determine number of records
+      def load
+        super
+        slice_records!(@records)
+
+        self
+      end
+
+      def next_page?
+        load # make sure we have determined the number of fetched records
+
+        @number_of_records > per_page # there's a next page when we've fetched more records than per_page
+      end
+
+      def previous_page?
+        current_page > 1
+      end
+
+      def next_page
+        current_page + 1 if next_page?
+      end
+
+      def previous_page
+        current_page - 1 if previous_page?
+      end
+
+      def total_pages
+        (total_entries / per_page.to_f).ceil
+      end
+
+      def total_entries
+        @total_entries ||= begin
+          load # make sure we have determined the number of fetched records
+
+          # if we know that there are no more records, then we can calculate total_entries
+          if @number_of_records <= per_page
+            offset_value + @number_of_records
+          else
+            rel = except(:limit, :offset)
+            rel.count
+          end
+        end
+      end
+
+      private
+
+      # remember total number of fetched records and slice records to per_page
+      def slice_records!(records)
+        @number_of_records ||= records.length
+
+        if @number_of_records > per_page
+          records.slice!(per_page)
+        end
+      end
+    end
+  end
+end

data/lib/smart_paginate/paginate.rb

@@ -0,0 +1,21 @@
+module SmartPaginate
+  class Paginate
+    attr_reader :current_page, :per_page
+
+    def initialize(current_page, per_page = nil)
+      @current_page = convert(current_page, 1)
+      @per_page = convert(per_page, 20)
+    end
+
+    def offset
+      (current_page - 1) * per_page
+    end
+
+    private
+
+    def convert(value, default_value)
+      value = value.to_i
+      value > 0 ? value : default_value
+    end
+  end
+end

data/lib/smart_paginate/paginating_array.rb

@@ -0,0 +1,37 @@
+require "smart_paginate/paginate"
+
+module SmartPaginate
+  class PaginatingArray < Array
+    attr_accessor :current_page, :per_page, :total_entries
+
+    def paginate(options = {})
+      page = SmartPaginate::Paginate.new(options.fetch(:page), options[:per_page])
+
+      array = self.slice(page.offset, page.per_page)
+      array.current_page = page.current_page
+      array.per_page = page.per_page
+      array.total_entries = length
+      array
+    end
+
+    def next_page?
+      (current_page * per_page) < total_entries
+    end
+
+    def previous_page?
+      current_page > 1
+    end
+
+    def next_page
+      current_page + 1 if next_page?
+    end
+
+    def previous_page
+      current_page - 1 if previous_page?
+    end
+
+    def total_pages
+      (total_entries / per_page.to_f).ceil
+    end
+  end
+end

data/lib/smart_paginate/version.rb

@@ -0,0 +1,3 @@
+module SmartPaginate
+  VERSION = "0.1.0"
+end

data/lib/smart_paginate.rb

@@ -0,0 +1,10 @@
+require "smart_paginate/active_record"
+require "smart_paginate/paginating_array"
+require "smart_paginate/version"
+require "active_support/concern"
+
+module SmartPaginate
+  extend ActiveSupport::Concern
+
+  include SmartPaginate::ActiveRecord
+end

data/smart_paginate.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'smart_paginate/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "smart_paginate"
+  spec.version       = SmartPaginate::VERSION
+  spec.authors       = ["Peter Postma"]
+  spec.email         = ["peter.postma@gmail.com"]
+
+  spec.summary       = "Simple, smart and clean pagination extension"
+  spec.description   = "Simple, smart and clean pagination extension for Active Record and plain Ruby Arrays."
+  spec.homepage      = "https://github.com/ppostma"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.4.0", ">= 3.4.0"
+  spec.add_development_dependency "sqlite3", "~> 1.3", ">= 1.3.11"
+
+  spec.add_dependency "activerecord", ">= 4.0.0", "< 4.3"
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: smart_paginate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Postma
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-06-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.11
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+description: Simple, smart and clean pagination extension for Active Record and plain
+  Ruby Arrays.
+email:
+- peter.postma@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/smart_paginate.rb
+- lib/smart_paginate/active_record.rb
+- lib/smart_paginate/paginate.rb
+- lib/smart_paginate/paginating_array.rb
+- lib/smart_paginate/version.rb
+- smart_paginate.gemspec
+homepage: https://github.com/ppostma
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Simple, smart and clean pagination extension
+test_files: []