add pagination properly according to json-api

.rspec

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

README.md

@@ -4,7 +4,7 @@
 
 ## Requirement
 
-It is based on [will_paginate](https://github.com/mislav/will_paginate).
+`JbuilderPagination` relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
 
 ## Installation
 
@@ -24,21 +24,42 @@ Or install it yourself as:
 
 ## Usage
 
+###### Kaminari examples
+```ruby
+#array
+@posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
+
+#active_record
+@posts = Post.page(3).per(1)
+```
+
+###### WillPaginate examples
+
+```ruby
+#array
+@posts = [1,2,3].paginate(page: 3, per_page: 1)
+
+#active_record
+@posts = Post.page(3).per_page(1)
+```
+
+And then in your `*.json.jbuilder`
+
 ```ruby
 json.links do
-  json.pages! @servers, url: "https://api.example.com/v1/servers"
+  json.pages! @posts, url: "http://example.com/posts", query_parameters: { additional: 'parameters' }
 end
 
 # =>
-#  "links": {
-#      "pages": {
-#          "first": "https://api.example.com/v1/servers/v1/servers?page=1&per_page=1",
-#          "prev": "https://api.example.com/v1/servers/v1/servers?page=1&per_page=1",
-#          "last": "https://api.example.com/v1/servers/v1/servers?page=3&per_page=1",
-#          "next": "https://api.example.com/v1/servers/v1/servers?page=3&per_page=1"
-#      }
-#  },
+#    "links": {
+#      "self": "http://example.com/posts?page[number]=3&page[size]=1&additional=parameters",
+#      "first": "http://example.com/posts?page[number]=1&page[size]=1&additional=parameters",
+#      "prev": "http://example.com/posts?page[number]=2&page[size]=1&additional=parameters",
+#      "next": "http://example.com/posts?page[number]=4&page[size]=1&additional=parameters",
+#      "last": "http://example.com/posts?page[number]=13&page[size]=1&additional=parameters"
+#    }
 ```
+The options `url` and  `query_parameters` are opcionals.
 
 In case there is no pagination at all, `links` will be omitted.
 

lib/jbuilder/pagination/pages.rb

@@ -1,29 +1,41 @@
 class Jbuilder
+  ONE_PAGE = 1
+
   def pages!(collection, options={})
-    return unless collection
+    return unless collection && is_paginated?(collection)
 
-    pages do
-      pages_from(collection).map do |k, v|
-        _set_value k, "#{options[:url]}?page=#{v}&per_page=#{collection.per_page}"
-      end
+    pages_from(collection).map do |key, value|
+      params = query_parameters(options).merge(page: { number: value, size: collection.size }).to_query
+      _set_value key, "#{options.fetch(:url, nil)}?#{params}"
     end
   end
 
   private
 
   def pages_from(collection)
-    return {} if collection.total_pages == 1
-
     {}.tap do |pages|
-      unless collection.current_page == 1
-        pages[:first] = 1
-        pages[:prev]  = collection.current_page - 1
+      pages[:self] = collection.current_page
+      return pages if collection.total_pages == ONE_PAGE
+
+      unless collection.current_page == ONE_PAGE
+        pages[:first] = ONE_PAGE
+        pages[:prev]  = collection.current_page - ONE_PAGE
       end
 
       unless collection.current_page == collection.total_pages
+        pages[:next] = collection.current_page + ONE_PAGE
         pages[:last] = collection.total_pages
-        pages[:next] = collection.current_page + 1
       end
     end
   end
+
+  def query_parameters(options)
+    @query_parameters ||= options.fetch(:query_parameters, {})
+  end
+
+  def is_paginated?(collection)
+    collection.respond_to?(:current_page) &&
+      collection.respond_to?(:total_pages) &&
+      collection.respond_to?(:size)
+  end
 end

lib/jbuilder/pagination/version.rb

@@ -1,5 +1,5 @@
 module Jbuilder
   class Pagination
-    VERSION = "0.0.1"
+    VERSION = "1.0.0"
   end
 end

spec/fixtures/links.json

@@ -1 +1 @@
-{"links":{"pages":{"first":"https://api.example.com/v1/servers?page=1&per_page=1","prev":"https://api.example.com/v1/servers?page=1&per_page=1","last":"https://api.example.com/v1/servers?page=3&per_page=1","next":"https://api.example.com/v1/servers?page=3&per_page=1"}}}
+{"links":{"self":"https://api.example.com/v1/servers?page%5Bnumber%5D=2&page%5Bsize%5D=1","first":"https://api.example.com/v1/servers?page%5Bnumber%5D=1&page%5Bsize%5D=1","prev":"https://api.example.com/v1/servers?page%5Bnumber%5D=1&page%5Bsize%5D=1","next":"https://api.example.com/v1/servers?page%5Bnumber%5D=3&page%5Bsize%5D=1","last":"https://api.example.com/v1/servers?page%5Bnumber%5D=3&page%5Bsize%5D=1"}}

spec/fixtures/links_with_additional_params.json

@@ -0,0 +1 @@
+{"links":{"self":"https://api.example.com/v1/servers?page%5Bnumber%5D=2&page%5Bsize%5D=1&test=test","first":"https://api.example.com/v1/servers?page%5Bnumber%5D=1&page%5Bsize%5D=1&test=test","prev":"https://api.example.com/v1/servers?page%5Bnumber%5D=1&page%5Bsize%5D=1&test=test","next":"https://api.example.com/v1/servers?page%5Bnumber%5D=3&page%5Bsize%5D=1&test=test","last":"https://api.example.com/v1/servers?page%5Bnumber%5D=3&page%5Bsize%5D=1&test=test"}}

spec/jbuilder/pagination/pages_spec.rb

@@ -2,32 +2,43 @@
 
 describe 'Jbuilder#pages!' do
   context 'when there is pagination for collection' do
-    let(:collection) { OpenStruct.new(current_page: 2, total_pages: 3, per_page: 1) }
+    let(:collection) { OpenStruct.new(current_page: 2, total_pages: 3, size: 1) }
     let(:response_json) { File.read("spec/fixtures/links.json").chomp }
 
-    it "returns full link pagination" do
-      expect(build_json_for(collection)).to eq(response_json)
-    end
+    it { expect(build_json_for(collection)).to eq(response_json) }
+  end
+
+  context 'when there is additional params' do
+    let(:collection) { OpenStruct.new(current_page: 2, total_pages: 3, size: 1) }
+    let(:response_json) { File.read("spec/fixtures/links_with_additional_params.json").chomp }
+    let(:additional) { { test: 'test' } }
+
+    it { expect(build_json_for(collection, query_parameters: additional )).to eq(response_json) }
   end
 
   context 'when there is no pagination for collection' do
-    let(:collection) { OpenStruct.new(current_page: 1, total_pages: 1) }
+    let(:collection) { OpenStruct.new(current_page: 1, total_pages: 1, size: 1) }
+    let(:response_json) { {links: {self: "https://api.example.com/v1/servers?page%5Bnumber%5D=1&page%5Bsize%5D=1" } }.to_json }
 
-    it "returns empty link pagination" do
-      expect(build_json_for(collection)).to eq("{}")
-    end
+    it { expect(build_json_for(collection)).to eq(response_json) }
   end
 
   context 'when collection is nil' do
-    it "returns empty link pagination" do
-      expect(build_json_for(nil)).to eq("{}")
-    end
+    it { expect(build_json_for(nil)).to eq("{}") }
+  end
+
+  context 'when there is a collection but it does not respond to all methods required' do
+    let(:collection) { OpenStruct.new(current_page: 1, total_pages: 1) }
+
+    it { expect(build_json_for(collection)).to eq("{}") }
   end
 
-  def build_json_for(collection)
+  def build_json_for(collection, options = {})
     Jbuilder.encode do |json|
       json.links do
-        json.pages! collection, url: "https://api.example.com/v1/servers"
+        json.pages! collection,
+          url: "https://api.example.com/v1/servers",
+          query_parameters: options.fetch(:query_parameters, {})
       end
     end
   end