pager_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e79547244421e6ea67f19bdd6b4190b6b6e6086f
+  data.tar.gz: 0021669263b8652f59664122742e7469b94eedd1
+SHA512:
+  metadata.gz: c80c5b7ddfe46f0735df8ae3aa7522b3742f0750b7dd1777eaf6ede8db8abe7791c6192db1b407121048802eeacdafecb9c405500806afff1d6194c38fa6d2c7
+  data.tar.gz: cc86e17bdf752e4e496596c69d38c310f054d500b2a3f91aac7763814fc557536297bdc29b59270b87f7bbf1a55bc5a57c9af6506093970ecbd9533e969ca02f

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pager_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Abraham Kuri
+
+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,136 @@
+# Pager API
+
+![Pager](http://iplp.com/pagers/images/448/Gold+Alphanumeric+Pager+-+2871+-+3+-+400.jpg)
+
+API Pagination made it right. Pager API is a library to help you add `meta` information and the adecuate header with pagination information based on the [JSON API standard](http://jsonapi.org) for your Rails app.
+
+## Table of contents
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Bug tracker & feature request](#bug-tracker-&-feature-request)
+- [Documentation or Installation instructions](#documentation)
+- [Contributing](#contributing)
+- [Community](#community)
+- [Heroes](#heroes)
+- [License](#license)
+
+
+## Quick Start
+
+`pager_api` depends on [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate) to handle pagination. You need to add one of these to your Gemfile:
+
+```ruby
+# gem 'will_paginate'
+# gem 'kaminari'
+gem 'pager_api'
+```
+
+And then execute:
+
+```console
+% bundle
+```
+
+## Configuration
+
+**This step is totally optional**
+
+The gem comes with an installer for you to configure it, for example to switch between pagination handlers or whether or not to include the `Link` header or meta information. To install it you just need to run:
+
+```console
+% rails g pager_api:install
+```
+
+This will create a file under the `initializers` directory called `pager_api.rb`. You can easily configure it there to meet your needs.
+
+By default `pager_api` uses [Kaminari](https://github.com/amatsuda/kaminari).
+
+## Usage
+
+On your controller where you are providing a paginated collection, where you may have something like:
+
+```ruby
+class UsersController < ApplicationController
+
+	def index
+		users = User.page(params[:page]).per(15)
+		render json: users, meta: { pagination: { 
+											per_page: 15,
+											total_pages: 10,
+											total_objects: 150
+										} }
+	end
+end
+```
+
+With `pager_api` is really easy to achieve just by:
+
+```ruby
+class UsersController < ApplicationController
+
+	def index
+	   # You can have any scope for the User class in this case
+	   # You can even send the paginated collection
+		paginate User.unscoped, per_page: 15 
+	end
+end
+```
+
+This will output a json object like:
+
+```json
+{
+    "users": [
+    	...
+    ],
+    "meta": {
+        "pagination": {
+            "per_page": 15,
+            "total_pages": 1,
+            "total_objects": 15,
+            "links": {
+                "first": "/api/users?page=1",
+                "last": "/api/users?page=1"
+            }
+        }
+    }
+}
+```
+
+As you can see, the pagination metadata also includes the links information for the `first` and `last` page, but it will also create the `next` and the `prev` keys when necessary.
+
+By default it will also include a `Link` header with the following information:
+
+```
+# Link: <http://example.com/api/v1/users?page="2">; rel="next",
+# <http://example.com/api/v1//users?page="5">; rel="last",
+# <http://example.com/api/v1//users?page="1">; rel="first",
+# <http://example.com/api/v1/users?page="1">; rel="prev",
+```
+
+The header will be created with the corresponding `first`, `last`, `prev` and `next`.
+
+## Bug tracker & feature request
+
+Have a bug or a feature request? [Please open a new issue](https://github.com/IcaliaLabs/pager-api/issues). Before opening any issue, please search for existing issues.
+
+## Contributing
+
+Please submit all pull requests against a separate branch. Although it does not have tests yet, be a nice guy and add some for your feature. We'll be working hard to add them too.
+
+In case you are wondering what to attack, we have a milestone with the version to work, some fixes and refactors. Feel free to start one.
+
+Thanks!
+
+## Heroes
+
+**Abraham Kuri**
+
++ [http://twitter.com/kurenn](http://twitter.com/kurenn)
++ [http://github.com/kurenn](http://github.com/kurenn)
++ [http://klout.com/#/kurenn](http://klout.com/#/kurenn)
+
+## License
+
+Code and documentation copyright 2015 Icalia Labs. Code released under [the MIT license](LICENSE).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pager_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/pager_api/install_generator.rb

@@ -0,0 +1,13 @@
+module PagerApi
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__) 
+
+      desc "Creates a PagerApi initializer in your application"
+
+       def copy_initializer
+        template "pager_api.rb", "config/initializers/pager_api.rb"
+       end
+    end
+  end
+end

data/lib/generators/pager_api/templates/pager_api.rb

@@ -0,0 +1,21 @@
+# Use this module to configure pager the available options
+#
+# Made with love by @icalialabs
+
+PagerApi.setup do |config|
+
+  # Pagination Handler
+  # User this option to meet your pagination handler, whether is :kaminari or :will_paginate
+  # config.pagination_handler = :kaminari
+
+  # Includes Pagination information on Meta
+  #
+  # config.include_pagination_on_meta = true
+
+  # Includes Pagination information on a Link Header
+  #
+  # config.include_pagination_headers = true
+
+  # Set the Total-Count Header name
+  # config.total_count_header = "X-Total-Count"
+end

data/lib/pager_api/hooks.rb

@@ -0,0 +1,16 @@
+# Dynamic pagination handler call
+require "pager_api/pagination/#{PagerApi.pagination_handler}"
+
+begin; require 'kaminari';           rescue LoadError; end
+begin; require 'will_paginate';      rescue LoadError; end
+
+ActionController::Base.send(:include, "PagerApi::Pagination::#{PagerApi.pagination_handler.to_s.classify}".constantize)
+
+unless defined?(Kaminari) or defined?(WillPaginate)
+  Kernel.warn <<-WARNING.gsub(/^\s{4}/, '')
+    Warning: pager-api needs Kaminari or Will Paginate as a dependency.
+    You need to add it to your Gemfile
+
+    gem 'kaminari' or gem 'will_paginate'
+  WARNING
+end

data/lib/pager_api/pagination/kaminari.rb

@@ -0,0 +1,87 @@
+require 'pry'
+module PagerApi
+  module Pagination
+    module Kaminari
+
+      def paginate(*args)
+        options = args.extract_options!
+        collection = args.first
+
+        paginated_collection = paginate_collection(collection, options)
+
+        options[:json] = paginated_collection
+
+        options[:meta] = meta(paginated_collection, options) if PagerApi.include_pagination_on_meta?
+
+        pagination_headers(paginated_collection) if PagerApi.include_pagination_headers?
+
+        render options
+      end
+
+      private
+
+        # Link: <http://example.com/api/v1/users?page="2">; rel="next",
+        # <http://example.com/api/v1//users?page="5">; rel="last",
+        # <http://example.com/api/v1//users?page="1">; rel="first",
+        # <http://example.com/api/v1/users?page="1">; rel="prev",
+        def pagination_headers(collection)
+          links = (headers['Link'] || "").split(',').map(&:strip)
+          clean_url = request.original_url.sub(/\?.*$/, '')
+
+          paging_info = pages(collection)
+
+          paging_info.each do |key, value|
+            query_params = request.query_parameters.merge(page: value)
+            links << %Q( <#{clean_url}?#{query_params.to_param}>; rel="#{key}" )
+          end
+
+          headers['Link'] = links.join(", ") unless links.empty?
+          headers[PagerApi.total_count_header] = collection.total_pages
+
+          return nil
+        end
+
+        def pagination_links(collection)
+            current_uri = request.env['PATH_INFO']
+            meta_links = {}
+
+            pages(collection).each do |key, value|
+              query_params = request.query_parameters.merge(page: value)
+              meta_links[key] = "#{current_uri}?#{query_params.to_param}"
+            end
+
+            meta_links
+        end
+
+        def pages(collection)
+          {}.tap do |paging|
+            paging[:first] = 1
+            paging[:last] = collection.total_pages
+
+            paging[:prev] = collection.current_page - 1 unless collection.first_page?
+            paging[:next] = collection.current_page + 1 unless collection.last_page? or collection.current_page >= collection.total_pages
+          end
+        end
+
+        def paginate_collection(collection, options = {})
+          options[:page] = params[:page] || 1
+          options[:per_page] = options.delete(:per_page) || params[:per_page]
+
+          collection.page(options[:page]).per(options[:per_page])
+        end
+
+        def meta(collection, options = {})
+          {
+            pagination:
+            {
+              per_page: options[:per_page].to_i || params[:per_page].to_i || ::Kaminari.config.default_per_page,
+              total_pages: collection.total_pages,
+              total_objects: collection.total_count,
+              links: pagination_links(collection)
+            }
+          }
+        end
+
+    end
+  end
+end

data/lib/pager_api/pagination/will_paginate.rb

@@ -0,0 +1,85 @@
+module PagerApi
+  module Pagination
+    module WillPaginate
+
+      def paginate(*args)
+        options = args.extract_options!
+        collection = args.first
+
+        paginated_collection = paginate_collection(collection, options)
+
+        options[:json] = paginated_collection
+
+        options[:meta] = meta(paginated_collection, options) if PagerApi.include_pagination_on_meta?
+
+        pagination_headers(paginated_collection) if PagerApi.include_pagination_headers?
+
+        render options
+      end
+
+      private
+
+        # Link: <http://example.com/api/v1/users?page="2">; rel="next",
+        # <http://example.com/api/v1//users?page="5">; rel="last",
+        # <http://example.com/api/v1//users?page="1">; rel="first",
+        # <http://example.com/api/v1/users?page="1">; rel="prev",
+        def pagination_headers(collection)
+          links = (headers['Link'] || "").split(',').map(&:strip)
+          clean_url = request.original_url.sub(/\?.*$/, '')
+
+          paging_info = pages(collection)
+
+          paging_info.each do |key, value|
+            query_params = request.query_parameters.merge(page: value)
+            links << %Q( <#{clean_url}?#{query_params.to_param}>; rel="#{key}" )
+          end
+
+          headers['Link'] = links.join(", ") unless links.empty?
+          headers[PagerApi.total_count_header] = collection.total_pages
+
+          return nil
+        end
+
+        def pagination_links(collection)
+            current_uri = request.env['PATH_INFO']
+            meta_links = {}
+
+            pages(collection).each do |key, value|
+              query_params = request.query_parameters.merge(page: value)
+              meta_links[key] = "#{current_uri}?#{query_params.to_param}"
+            end
+
+            meta_links
+        end
+
+        def pages(collection)
+          {}.tap do |paging|
+            paging[:first] = 1
+            paging[:last] = collection.total_pages
+
+            paging[:prev] = collection.current_page - 1 unless collection.current_page == 1
+            paging[:next] = collection.current_page + 1 unless collection.current_page >= collection.total_pages
+          end
+        end
+
+        def paginate_collection(collection, options = {})
+          options[:page] = params[:page] || 1
+          options[:per_page] = options.delete(:per_page) || params[:per_page]
+
+          collection.paginate(options)
+        end
+
+        def meta(collection, options = {})
+          {
+            pagination:
+            {
+              per_page: options[:per_page] || params[:per_page] || ::WillPaginate.per_page,
+              total_pages: collection.total_pages,
+              total_objects: collection.total_entries,
+              links: pagination_links(collection)
+            }
+          }
+        end
+    end
+  end
+end

data/lib/pager_api/railtie.rb

@@ -0,0 +1,11 @@
+module PagerApi
+  class Railtie < Rails::Railtie
+
+    initializer "pager_api.action_dispatch" do |app|
+      ActiveSupport.on_load :action_controller do
+        require "pager_api/hooks"
+      end
+    end
+
+  end
+end

data/lib/pager_api/version.rb

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

data/lib/pager_api.rb

@@ -0,0 +1,35 @@
+module PagerApi
+
+  # pagination handler
+  mattr_accessor :pagination_handler
+  @@pagination_handler = :kaminari
+
+  # Meta tag information for pagination
+  mattr_accessor :include_pagination_on_meta
+  @@include_pagination_on_meta = true
+
+  # Links headeras with pagination information
+  mattr_accessor :include_pagination_headers
+  @@include_pagination_headers = true
+
+  # Total Count Header name
+  mattr_accessor :total_count_header
+  @@total_count_header = "X-Total-Count"
+
+  def self.include_pagination_on_meta?
+    @@include_pagination_on_meta
+  end
+
+  def self.include_pagination_headers?
+    @@include_pagination_headers
+  end
+
+  #Method to configure pager api
+  def self.setup
+    yield self
+  end
+
+end
+
+require "pager_api/version"
+require "pager_api/railtie"

data/pager_api.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pager_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pager_api"
+  spec.version       = PagerApi::VERSION
+  spec.authors       = ["Abraham Kuri"]
+  spec.email         = ["kurenn@icalialabs.com"]
+
+  spec.summary       = %q{A Rails pagination JSON handler, perfect for API}
+  spec.description   = %q{A super simple yet powerful gem to respond with paginated collections using the JSON API standard}
+  spec.homepage      = "https://github.com/IcaliaLabs/pager-api"
+  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.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: pager_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Abraham Kuri
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-08-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !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'
+description: A super simple yet powerful gem to respond with paginated collections
+  using the JSON API standard
+email:
+- kurenn@icalialabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/generators/pager_api/install_generator.rb
+- lib/generators/pager_api/templates/pager_api.rb
+- lib/pager_api.rb
+- lib/pager_api/hooks.rb
+- lib/pager_api/pagination/kaminari.rb
+- lib/pager_api/pagination/will_paginate.rb
+- lib/pager_api/railtie.rb
+- lib/pager_api/version.rb
+- pager_api.gemspec
+homepage: https://github.com/IcaliaLabs/pager-api
+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.5
+signing_key: 
+specification_version: 4
+summary: A Rails pagination JSON handler, perfect for API
+test_files: []
+has_rdoc: