pagy 0.8.6 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e60b4173be015ffca66290f5a3cf17ac3a310300384661aa5e2fa247ce58f68
-  data.tar.gz: 358cdc2134cc73f7f289de33cb02c821158797ee8dd21e88e05cf690085e0143
+  metadata.gz: 8867ae39673157a4e3256e40bb71a435d4bc45418ece6c510ac4913fc8d2c917
+  data.tar.gz: f5cd6d9d8becbdd00c9878f4c10472302e2813b3163fe33bc21bd71c240544e3
 SHA512:
-  metadata.gz: c7b4d97d281802fe983e2a748524cad6971bf9df58baa0cf34f1e35a0647ace2644b50b56e76727b2fe231043ed8a34cbc84bf206350596e81fe95c15b3a6e2f
-  data.tar.gz: '083afad91cdb22b2a6e036c25c5fca9cfe147747c3a348b86a9d471c165417f06a3622b88e3b25160fe893b25e533ac2c468434744d1e0f0f677ee274df87ff7'
+  metadata.gz: 27619900377812a56104aa89542ebe6b6ab2201231b725ca1e708b3b02e0f540265d525e2bbe9647fa993338e6fe0003a0380818daaabc7405671910215fa064
+  data.tar.gz: 726345048bbd3056b6612d4acbe11bdf76e6abb515b3948cf165668da05dc99071d2086ec235466281be1543b344f81de4f6422941db883d537534b9369499ac

data/lib/locales/pagy.yml

@@ -17,5 +17,8 @@ en:
         one: "item"
         other: "items"
     compact:
-      page: Page
-      of: of
+      page: "Page"
+      of: "of"
+    items:
+      show: "Show"
+      items: "items per page"

data/lib/pagy.rb

@@ -2,11 +2,11 @@
 
 require 'pathname'
 
-class Pagy ; VERSION = '0.8.6'
+class Pagy ; VERSION = '0.9.0'
 
   class OutOfRangeError < StandardError; end
 
-  # root pathname to get the path of pagy files like templates or dictionaries
+  # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root; Pathname.new(__FILE__).dirname end
 
   # default vars
@@ -14,11 +14,11 @@ class Pagy ; VERSION = '0.8.6'
 
   attr_reader :count, :page, :items, :vars, :pages, :last, :offset, :from, :to, :prev, :next
 
-  # merge and validate the options, do some simple aritmetic and set the instance variables
+  # Merge and validate the options, do some simple aritmetic and set the instance variables
   def initialize(vars)
-    @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze })   # default vars + cleaned instance vars
-    { count:0, items:1, outset:0, page:1 }.each do |k,min|                # validate core variables
-      (@vars[k] && instance_variable_set(:"@#{k}", @vars.delete(k).to_i) >= min) \
+    @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze })   # default vars + cleaned vars
+    { count:0, items:1, outset:0, page:1 }.each do |k,min|                # validate instance variables
+      (@vars[k] && instance_variable_set(:"@#{k}", @vars[k].to_i) >= min) \
          or raise(ArgumentError, "expected :#{k} >= #{min}; got #{instance_variable_get(:"@#{k}").inspect}")
     end
     @pages  = @last = [(@count.to_f / @items).ceil, 1].max                # cardinal and ordinal meanings
@@ -31,7 +31,7 @@ class Pagy ; VERSION = '0.8.6'
     @next   = (@page+1 unless @page == @last)                             # nil if no next page
   end
 
-  # return the array of page numbers and :gap items e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+  # Return the array of page numbers and :gap items e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
   def series(size=@vars[:size])
     4.times{|i| (size[i]>=0 rescue nil) or raise(ArgumentError, "expected 4 items >= 0 in :size; got #{size.inspect}")}
     series = []

data/lib/pagy/backend.rb

@@ -1,30 +1,29 @@
 # See Pagy::Backend API documentation: https://ddnexus.github.io/pagy/api/backend
 
 class Pagy
-  # Defines a few generic methods to paginate a ORM collection out of the box,
-  # or any collection by overriding pagy_get_items in your controller
+  # Defines a few generic methods to paginate an ORM collection out of the box,
+  # or any collection by overriding pagy_get_items and/or pagy_get_vars in your controller
 
-  # See also the extras if you need specialized methods to paginate
-  # Arrays, ORM, and other TBD collections
+  # See also the extras if you need specialized methods to paginate Arrays or other collections
 
   module Backend ; private         # the whole module is private so no problem with including it in a controller
 
-    # return pagy object and items
+    # Return Pagy object and items
     def pagy(collection, vars={})
       pagy = Pagy.new(pagy_get_vars(collection, vars))
       return pagy, pagy_get_items(collection, pagy)
     end
 
-    # sub-method called only by #pagy: here for easy customization of variables by overriding
+    # Sub-method called only by #pagy: here for easy customization of variables by overriding
     def pagy_get_vars(collection, vars)
-      # return the merged variables to initialize the pagy object
-      { count: collection.count(:all),
+      # Return the merged variables to initialize the Pagy object
+      { count: collection.count(:all),        # works with AR, but may not work with other ORMs
         page:  params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
     end
 
-    # sub-method called only by #pagy: here for easy customization of record-extraction by overriding
+    # Sub-method called only by #pagy: here for easy customization of record-extraction by overriding
     def pagy_get_items(collection, pagy)
-      # this should work with ActiveRecord, Sequel, Mongoid...
+      # This should work with ActiveRecord, Sequel, Mongoid...
       collection.offset(pagy.offset).limit(pagy.items)
     end
 

data/lib/pagy/extras/array.rb

@@ -1,17 +1,17 @@
-# See the Pagy Extras documentation: https://ddnexus.github.io/pagy/extras
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/array
 
 class Pagy
   # Add specialized backend methods to paginate array collections
   module Backend ; private
 
-    # return pagy object and items
+    # Return Pagy object and items
     def pagy_array(array, vars={})
       pagy = Pagy.new(pagy_array_get_vars(array, vars))
       return pagy, array[pagy.offset, pagy.items]
     end
 
     def pagy_array_get_vars(array, vars)
-      # return the merged variables to initialize the pagy object
+      # Return the merged variables to initialize the Pagy object
       { count: array.count,
         page:  params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
     end

data/lib/pagy/extras/bootstrap.rb

@@ -1,4 +1,4 @@
-# See the Pagy Extras documentation: https://ddnexus.github.io/pagy/extras
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/bootstrap
 
 class Pagy
   # Add nav helper for bootstrap pagination

data/lib/pagy/extras/compact.rb

@@ -1,4 +1,4 @@
-# See the Pagy Extras documentation: https://ddnexus.github.io/pagy/extras
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/compact
 
 class Pagy
   # Add nav helpers for compact pagination

data/lib/pagy/extras/i18n.rb

@@ -1,4 +1,4 @@
-# See the Pagy Extras documentation: https://ddnexus.github.io/pagy/extras
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/i18n
 
 class Pagy
   # Use ::I18n gem
@@ -6,7 +6,7 @@ class Pagy
 
     ::I18n.load_path << Pagy.root.join('locales', 'pagy.yml')
 
-    # overrides the built-in pagy_t
+    # Override the built-in pagy_t
     def pagy_t(*args)
       I18n.t(*args)
     end

data/lib/pagy/extras/initializer_example.rb

@@ -17,23 +17,31 @@
 # See https://ddnexus.github.io/pagy/extras/compact
 # require 'pagy/extras/compact'
 
-# I18n: Uses the `I18n` gem instead of the pagy implementation
+# I18n: Use the `I18n` gem instead of the pagy implementation
 # See https://ddnexus.github.io/pagy/extras/i18n
 # require 'pagy/extras/i18n'
 
+# Items: Handle the page :items passed with the params
+# See https://ddnexus.github.io/pagy/extras/items
+# require 'pagy/extras/items'
+# Pagy::VARS[:items_param] = :items    # default
+# Pagy::VARS[:max_items]   = 100       # default
+
 # Responsive: On resize, the number of page links will adapt in real-time to the available window or container width
 # See https://ddnexus.github.io/pagy/extras/responsive
 # require 'pagy/extras/responsive'
+# See https://ddnexus.github.io/pagy/extras/responsive#breakpoints
+# Pagy::VARS[:breakpoints] = { 0 => [1,2,2,1], 350 => [2,3,3,2], 550 => [3,4,4,3] }    # example of width/size pairs
 
 
 # Pagy Variables
-# All the Pagy::VARS here are set for all the pagy instances but can be
-# overridden by just passing them to Pagy.new or the pagy controller method
+# All the Pagy::VARS here are set for all the Pagy instances but can be
+# overridden by just passing them to Pagy.new or the #pagy controller method
 
-# Core variables (See https://ddnexus.github.io/pagy/api/pagy#core-variables)
+# Instance variables (See https://ddnexus.github.io/pagy/api/pagy#instance-variables)
 # Pagy::VARS[:items] = 20                                   # default
 
-# Non Core Variables (See https://ddnexus.github.io/pagy/api/pagy#non-core-variables)
+# Other Variables (See https://ddnexus.github.io/pagy/api/pagy#other-variables)
 # Pagy::VARS[:size]       = [1,4,4,1]                       # default
 # Pagy::VARS[:page_param] = :page                           # default
 # Pagy::VARS[:params]     = {}                              # default
@@ -41,17 +49,12 @@
 # Pagy::VARS[:link_extra] = 'data-remote="true"'            # example
 # Pagy::VARS[:item_path]  = 'activerecord.models.product'   # example
 
-# Extras Non Core Variables
-# See https://ddnexus.github.io/pagy/extras/responsive#breakpoints
-# Pagy::VARS[:breakpoints] = { 0 => [1,2,2,1], 350 => [2,3,3,2], 550 => [3,4,4,3] }    # example of width/size pairs
-
-
 # Pagy::Frontend::I18N Constant
 # See https://ddnexus.github.io/pagy/api/frontend#i18n
 # Pagy::Frontend::I18N[:plurals] = -> (c) {([:zero, :one][c] || :other).to_s   # default
 # Pagy::Frontend::I18N.load_file('path/to/dictionary.yml')                     # load a custom file
 
 
-# Rails: extras assets path required by compact or responsive extras
+# Rails: extras assets path required by compact, items qnd responsive extras
 # See https://ddnexus.github.io/pagy/extras/compact and https://ddnexus.github.io/pagy/extras/responsive
 # Rails.application.config.assets.paths << Pagy.root.join('pagy', 'extras', 'javascripts')

data/lib/pagy/extras/items.rb

@@ -0,0 +1,44 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/items
+
+class Pagy
+
+  # Default variables for this extra
+  VARS[:items_param] = :items
+  VARS[:max_items]   = 100
+
+  # Handle a custom number of :items from params
+  module Backend ; private
+
+    alias_method :built_in_pagy_get_vars, :pagy_get_vars
+
+    def pagy_get_vars(collection, vars)
+      vars[:items] ||= (items = params[vars[:items_param] || VARS[:items_param]]) &&                           # :items from :items_param
+                       [items&.to_i, vars.key?(:max_items) ? vars[:max_items] : VARS[:max_items]].compact.min  # :items capped to :max_items
+      built_in_pagy_get_vars(collection, vars)
+    end
+
+  end
+
+  module Frontend
+
+    # this works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...)
+    def pagy_url_for(page, pagy)
+      p_vars = pagy.vars; params = request.GET.merge(p_vars[:page_param] => page, p_vars[:items_param] => p_vars[:items], **p_vars[:params])
+      "#{request.path}?#{Rack::Utils.build_nested_query(pagy_get_params(params))}#{p_vars[:anchor]}"
+    end
+
+    # return the items selector HTML. For example "Show [20] items per page"
+    def pagy_items_selector(pagy, id=caller(1,1)[0].hash)
+      pagy = pagy.clone; p_vars = pagy.vars; p_items = p_vars[:items]; p_vars[:items] = "#{MARKER}-items-"
+
+      tags = %(<span id="pagy-items-#{id}">)
+
+        tags << %(<a href="#{pagy_url_for("#{MARKER}-page-", pagy)}"></a>)
+        input = %(<input type="number" min="1" max="#{p_vars[:max_items]}" value="#{p_items}" style="padding: 0; text-align: center; width: #{p_items.to_s.length+1}rem;">)
+        tags << %(#{pagy_t('pagy.items.show'.freeze)} #{input} #{pagy_t('pagy.items.items'.freeze)})
+
+      tags << %(</span><script>PagyItems('#{id}', '#{MARKER}', #{pagy.from});</script>)
+    end
+
+  end
+end

data/lib/pagy/extras/javascripts/pagy-compact.js

@@ -1,3 +1,5 @@
+// See the Pagy documentation: https://ddnexus.github.io/pagy/extras/compact
+
 function PagyCompact(id, marker, page){
   var pagyNav = document.getElementById('pagy-nav-'+id),
       input   = pagyNav.getElementsByTagName('input')[0],
@@ -11,5 +13,11 @@ function PagyCompact(id, marker, page){
     }
   };
 
-  input.addEventListener("focusout", this.go);
+  // select the content on click: easier for typing a number
+  input.addEventListener('click', function(){ this.select() });
+  // jump to page number from input when the input looses focus
+  input.addEventListener('focusout', this.go);
+  // … and when pressing enter inside the input
+  input.addEventListener('keyup', function(e){ if (e.which === 13) this.go() }.bind(this));
+
 }

data/lib/pagy/extras/javascripts/pagy-items.js

@@ -0,0 +1,26 @@
+// See the Pagy documentation: https://ddnexus.github.io/pagy/extras/items
+
+function PagyItems(id, marker, from){
+  var pagyNav = document.getElementById('pagy-items-'+id),
+      input   = pagyNav.getElementsByTagName('input')[0],
+      current = input.value,
+      link    = pagyNav.getElementsByTagName('a')[0];
+
+  this.go = function(){
+    var items = input.value;
+    if (current !== items) {
+      var page = Math.max(Math.ceil(from / items),1);
+      var href = link.getAttribute('href').replace(marker+'-page-', page).replace(marker+'-items-', items);
+      link.setAttribute('href', href);
+      link.click();
+    }
+  };
+
+  // select the content on click: easier for typing a number
+  input.addEventListener('click', function(){ this.select() });
+  // jump to page number from input when the input looses focus
+  input.addEventListener('focusout', this.go);
+  // … and when pressing enter inside the input
+  input.addEventListener('keyup', function(e){ if (e.which === 13) this.go() }.bind(this));
+
+}

data/lib/pagy/extras/javascripts/pagy-responsive.js

@@ -1,3 +1,5 @@
+// See the Pagy documentation: https://ddnexus.github.io/pagy/extras/resposive
+
 function PagyResponsive(id, items, widths, series){
   var pagyNav    = document.getElementById('pagy-nav-'+id),
       pagyBox    = pagyNav.firstChild || pagyNav,

data/lib/pagy/extras/responsive.rb

@@ -1,10 +1,10 @@
-# See the Pagy Extras documentation: https://ddnexus.github.io/pagy/extras
+# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/responsive
 
 require 'json'
 
 class Pagy
 
-  # default :breakpoints
+  # Default :breakpoints
   VARS[:breakpoints] = { 0 => [1,4,4,1] }
 
   # Helper for building the page_nav with javascript. For example:

data/lib/pagy/frontend.rb

@@ -26,7 +26,7 @@ class Pagy
     end
 
 
-    # return examples: "Displaying items 41-60 of 324 in total"  or "Displaying Products 41-60 of 324 in total"
+    # Return examples: "Displaying items 41-60 of 324 in total"  or "Displaying Products 41-60 of 324 in total"
     def pagy_info(pagy)
       name = pagy_t(pagy.vars[:item_path], count: pagy.count)
       path = pagy.pages == 1 ? 'pagy.info.single_page'.freeze : 'pagy.info.multiple_pages'.freeze
@@ -41,13 +41,14 @@ class Pagy
     end
 
 
-    # sub-method called only by #pagy_url_for: here for easy customization of params by overriding
+    # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding
     def pagy_get_params(params) params end
 
 
     MARKER = "-pagy-#{'pagy'.hash}-".freeze
 
-    # returns a performance optimized proc to generate the HTML links
+    # Returns a performance optimized proc to generate the HTML links
+    # Benchmarked on a 20 link nav: it is ~27x faster and uses ~13x less memory than rails' link_to
     def pagy_link_proc(pagy, link_extra=''.freeze)
       p_prev, p_next = pagy.prev, pagy.next
       a, b = %(<a href="#{pagy_url_for(MARKER, pagy)}" #{pagy.vars[:link_extra]} #{link_extra}).split(MARKER, 2)
@@ -62,7 +63,7 @@ class Pagy
     def I18N.load_file(file) I18N_DATA.replace(YAML.load_file(file).first[1]) end
 
     # Similar to I18n.t for interpolation and pluralization but without translation
-    # Use only for single-language apps: it is specialized for pagy and 5x faster than I18n.t
+    # Use only for single-language apps: it is specialized for Pagy and 5x faster than I18n.t
     # See also https://ddnexus.github.io/pagy/extras/i18n to use the standard I18n gem instead
     def pagy_t(path, vars={})
       value = I18N_DATA.dig(*path.to_s.split('.'.freeze)) or return %(translation missing: "#{path}")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.0
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-05 00:00:00.000000000 Z
+date: 2018-06-17 00:00:00.000000000 Z
 dependencies: []
 description: 'Agnostic pagination in plain ruby: it works with any framework, ORM
   and DB type, with all kinds of collections, even pre-paginated, scopes, Arrays,
@@ -29,7 +29,9 @@ files:
 - lib/pagy/extras/compact.rb
 - lib/pagy/extras/i18n.rb
 - lib/pagy/extras/initializer_example.rb
+- lib/pagy/extras/items.rb
 - lib/pagy/extras/javascripts/pagy-compact.js
+- lib/pagy/extras/javascripts/pagy-items.js
 - lib/pagy/extras/javascripts/pagy-responsive.js
 - lib/pagy/extras/responsive.rb
 - lib/pagy/extras/templates/nav.html.erb