pagy 5.2.2 → 5.4.0

data/lib/pagy/extras/foundation.rb

@@ -1,23 +1,23 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/foundation
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module FoundationExtra
     # Pagination for Foundation: it returns the html with the series of links to the pages
-    def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<nav#{p_id} class="pagy-foundation-nav" aria-label="Pagination"><ul class="pagination">)
       html << pagy_foundation_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<li>#{link.call item}</li>)                        # page link
-                when String  then %(<li class="current">#{pagy_labeler(pagy, item)}</li>)                  # active page
+                when String  then %(<li class="current">#{pagy.label_for(item)}</li>)                  # active page
                 when :gap    then %(<li class="ellipsis gap" aria-hidden="true"></li>) # page gap
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
@@ -27,17 +27,17 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for foundation: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_foundation_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_foundation_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => %(<ul class="pagination">#{pagy_foundation_prev_html pagy, link}),
-               'link'   => %(<li>#{link.call PAGE_PLACEHOLDER}</li>),
-               'active' => %(<li class="current">#{pagy.page}</li>),
+               'link'   => %(<li>#{link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER)}</li>),
+               'active' => %(<li class="current">#{LABEL_PLACEHOLDER}</li>),
                'gap'    => %(<li class="ellipsis gap" aria-hidden="true"></li>),
                'after'  => %(#{pagy_foundation_next_html pagy, link}</ul>) }
 
       %(<nav#{p_id} class="pagy-njs pagy-foundation-nav-js" aria-label="Pagination" #{
-          pagy_json_attr(pagy, :nav, tags, pagy.sequels(steps))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination for Foundation: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/{shared.rb → frontend_helpers.rb}

@@ -5,7 +5,8 @@ require 'digest'
 class Pagy # :nodoc:
   DEFAULT[:steps] = false # default false will use {0 => @vars[:size]}
 
-  module SharedExtra
+  # Private module documented in the main classes
+  module FrontendHelpers
     # Additions for the Pagy class
     module Pagy
       # `Pagy` instance method used by the `pagy*_nav_js` helpers.
@@ -17,12 +18,25 @@ class Pagy # :nodoc:
       #       "350" => [1, 2, :gap, 17, 18, 19, "20", 21, 22, 23, :gap, 49, 50],
       #       "550" => [1, 2, 3, :gap, 16, 17, 18, 19, "20", 21, 22, 23, 24, :gap, 48, 49, 50] }
       # Notice: if :steps is false it will use the single {0 => @vars[:size]} size
-      def sequels(steps = nil)
-        steps ||= @vars[:steps] || { 0 => @vars[:size] }
+      def sequels(steps: @vars[:steps] || { 0 => @vars[:size] })
         raise VariableError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
 
         {}.tap do |sequels|
-          steps.each { |width, size| sequels[width.to_s] = series(size) }
+          steps.each { |width, step_size| sequels[width.to_s] = series(size: step_size) }
+        end
+      end
+
+      # Support for the Calendar API
+      def label_sequels(*); end
+    end
+
+    # Additions for Calendar class
+    module Calendar
+      def label_sequels(sequels = self.sequels)
+        {}.tap do |label_sequels|
+          sequels.each do |width, series|
+            label_sequels[width] = series.map { |item| item == :gap ? :gap : label_for(item) }
+          end
         end
       end
     end
@@ -50,6 +64,7 @@ class Pagy # :nodoc:
       end
     end
   end
-  prepend SharedExtra::Pagy
-  Frontend.prepend SharedExtra::Frontend
+  prepend FrontendHelpers::Pagy
+  Calendar.prepend FrontendHelpers::Calendar if defined?(Calendar)
+  Frontend.prepend FrontendHelpers::Frontend
 end

data/lib/pagy/extras/i18n.rb

@@ -4,11 +4,22 @@
 class Pagy # :nodoc:
   # Use ::I18n gem
   module I18nExtra
-    def pagy_t(key, **opts)
-      ::I18n.t(key, **opts)
+    # Frontend overriding
+    module Frontend
+      def pagy_t(key, **opts)
+        ::I18n.t(key, **opts)
+      end
+    end
+
+    # Calendar overriding
+    module Calendar
+      def localize(time, opts)
+        ::I18n.l(time, **opts)
+      end
     end
   end
-  Frontend.prepend I18nExtra
+  Frontend.prepend I18nExtra::Frontend
+  Calendar.prepend I18nExtra::Calendar if defined?(Calendar)
 
   # Add the pagy locales to the I18n.load_path
   ::I18n.load_path += Dir[Pagy.root.join('locales', '*.yml')]

data/lib/pagy/extras/items.rb

@@ -1,7 +1,7 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/items
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   DEFAULT[:items_param] = :items

data/lib/pagy/extras/materialize.rb

@@ -1,20 +1,20 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/materialize
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module MaterializeExtra
     # Pagination for materialize: it returns the html with the series of links to the pages
-    def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<div#{p_id} class="pagy-materialize-nav pagination" role="navigation" aria-label="pager"><ul class="pagination">)
       html << pagy_materialize_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<li class="waves-effect">#{link.call item}</li>)                           # page link
                 when String  then %(<li class="active">#{link.call item}</li>)                                 # active page
@@ -27,18 +27,18 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for materialize: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_materialize_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_materialize_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       tags = { 'before' => %(<ul class="pagination">#{pagy_materialize_prev_html pagy, link}),
-               'link'   => %(<li class="waves-effect">#{mark = link.call(PAGE_PLACEHOLDER)}</li>),
+               'link'   => %(<li class="waves-effect">#{mark = link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER)}</li>),
                'active' => %(<li class="active">#{mark}</li>),
                'gap'    => %(<li class="gap disabled"><a href="#">#{pagy_t 'pagy.nav.gap'}</a></li>),
                'after'  => %(#{pagy_materialize_next_html pagy, link}</ul>) }
 
       %(<div#{p_id} class="pagy-njs pagy-materialize-nav-js" role="navigation" aria-label="pager" #{
-          pagy_json_attr(pagy, :nav, tags, pagy.sequels(steps))}></div>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></div>)
     end
 
     # Javascript combo pagination for materialize: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/navs.rb

@@ -1,24 +1,24 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/navs
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module NavsExtra
     # Javascript pagination: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => pagy_nav_prev_html(pagy, link),
-               'link'   => %(<span class="page">#{link.call(PAGE_PLACEHOLDER)}</span> ),
-               'active' => %(<span class="page active">#{pagy.page}</span> ),
+               'link'   => %(<span class="page">#{link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER)}</span> ),
+               'active' => %(<span class="page active">#{LABEL_PLACEHOLDER}</span> ),
                'gap'    => %(<span class="page gap">#{pagy_t 'pagy.nav.gap'}</span> ),
                'after'  => pagy_nav_next_html(pagy, link) }
 
       %(<nav#{p_id} class="pagy-njs pagy-nav-js pagination" aria-label="pager" #{
-          pagy_json_attr(pagy, :nav, tags, pagy.sequels(steps))}></nav>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></nav>)
     end
 
     # Javascript combo pagination: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/overflow.rb

@@ -15,25 +15,25 @@ class Pagy # :nodoc:
 
       # Add rescue clause for different behaviors
       def initialize(vars)
-        @overflow ||= false                            # still true if :last_page re-run the method after an overflow
+        @overflow ||= false                                 # still true if :last_page re-run the method after an overflow
         super
       rescue OverflowError
-        @overflow = true                               # add the overflow flag
+        @overflow = true                                    # add the overflow flag
         case @vars[:overflow]
         when :exception
-          raise                                        # same as without the extra
+          raise                                             # same as without the extra
         when :last_page
-          requested_page = @vars[:page]                # save the requested page (even after re-run)
-          initialize vars.merge!(page: @last)          # re-run with the last page
-          @vars[:page] = requested_page                # restore the requested page
+          requested_page = @vars[:page]                     # save the requested page (even after re-run)
+          initialize vars.merge!(page: @last)               # re-run with the last page
+          @vars[:page] = requested_page                     # restore the requested page
         when :empty_page
-          @offset = @in = @from = @to = 0              # vars relative to the actual page
-          if defined?(Calendar) && is_a?(Calendar)     # only for Calendar instances
-            edge = @order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but it would work with any time)
-            @utc_from = @utc_to = edge.getutc          # set both to the edge utc time (a query with >= && < will get no record)
+          @offset = @items = @from = @to = 0                # vars relative to the actual page
+          if defined?(Calendar) && is_a?(Calendar)          # only for Calendar instances
+            edge = @time_order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but any time would do)
+            @utc_from = @utc_to = edge.getutc               # set both to the edge utc time (a >=&&< query will get no records)
           end
-          @prev = @last                                # prev relative to the actual page
-          extend Series                                # special series for :empty_page
+          @prev = @last                                     # prev relative to the actual page
+          extend Series                                     # special series for :empty_page
         else
           raise VariableError.new(self, :overflow, 'to be in [:last_page, :empty_page, :exception]', @vars[:overflow])
         end
@@ -41,9 +41,9 @@ class Pagy # :nodoc:
 
       # Special series for empty page
       module Series
-        def series(size = @vars[:size])
+        def series(*)
           @page = @last                                # series for last page
-          super(size).tap do |s|                       # call original series
+          super.tap do |s|                       # call original series
             s[s.index(@page.to_s)] = @page             # string to integer (i.e. no current page)
             @page = @vars[:page]                       # restore the actual page
           end
@@ -63,7 +63,7 @@ class Pagy # :nodoc:
         when :exception
           raise                                        # same as without the extra
         when :empty_page
-          @offset = @in = @from = @to = 0              # vars relative to the actual page
+          @offset = @items = @from = @to = 0            # vars relative to the actual page
           @vars[:size] = []                            # no page in the series
           self
         else

data/lib/pagy/extras/semantic.rb

@@ -1,23 +1,23 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/semantic
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module SemanticExtra
     # Pagination for semantic: it returns the html with the series of links to the pages
-    def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="item" #{link_extra}))
 
       html = +%(<div#{p_id} class="pagy-semantic-nav ui pagination menu">)
       html << pagy_semantic_prev_html(pagy, link)
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then link.call item
-                when String  then %(<a class="item active">#{pagy_labeler(pagy, item)}</a>)
+                when String  then %(<a class="item active">#{pagy.label_for(item)}</a>)
                 when :gap    then %(<div class="disabled item">#{pagy_t 'pagy.nav.gap'}</div>)
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
@@ -27,17 +27,17 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for semantic: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_semantic_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_semantic_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: %(class="item" #{link_extra}))
       tags = { 'before' => pagy_semantic_prev_html(pagy, link),
-               'link'   => link.call(PAGE_PLACEHOLDER),
-               'active' => %(<a class="item active">#{pagy.page}</a>),
+               'link'   => link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER),
+               'active' => %(<a class="item active">#{LABEL_PLACEHOLDER}</a>),
                'gap'    => %(<div class="disabled item">#{pagy_t('pagy.nav.gap')}</div>),
                'after'  => pagy_semantic_next_html(pagy, link) }
 
       %(<div#{p_id} class="pagy-njs pagy-semantic-nav-js ui pagination menu" role="navigation" #{
-        pagy_json_attr(pagy, :nav, tags, pagy.sequels(steps))}></div>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></div>)
     end
 
     # Combo pagination for semantic: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/extras/standalone.rb

@@ -37,15 +37,18 @@ class Pagy # :nodoc:
     # it works exactly as the regular #pagy_url_for, relying on the params method and Rack.
     # If there is a defined pagy.vars[:url] variable it does not need the params method nor Rack.
     def pagy_url_for(pagy, page, absolute: nil)
-      vars = pagy.vars
-      return super unless (url = vars[:url])
+      return super unless pagy.vars[:url]
 
-      params                     = vars[:params].clone  # safe when it gets reused
-      params[vars[:page_param]]  = page
-      params[vars[:items_param]] = vars[:items] if vars[:items_extra]
-
-      query_string = "?#{QueryUtils.build_nested_query(pagy_massage_params(params))}"
-      "#{url}#{query_string}#{vars[:fragment]}"
+      vars                = pagy.vars
+      page_param          = vars[:page_param].to_s
+      items_param         = vars[:items_param].to_s
+      params              = pagy.params.is_a?(Hash) ? pagy.params.clone : {}  # safe when it gets reused
+      params[page_param]  = page
+      params[items_param] = vars[:items] if vars[:items_extra]
+      query_string        = "?#{QueryUtils.build_nested_query(pagy_deprecated_params(pagy, params))}"  # remove in 6.0
+      # params              = pagy.params.call(params) if pagy.params.is_a?(Proc)                      # add in 6.0
+      # query_string        = "?#{Rack::Utils.build_nested_query(params)}"                             # add in 6.0
+      "#{vars[:url]}#{query_string}#{vars[:fragment]}"
     end
   end
   # In ruby 3+ `UrlHelpers.prepend StandaloneExtra` would be enough instead of using the next 2 lines

data/lib/pagy/extras/trim.rb

@@ -12,9 +12,9 @@ class Pagy # :nodoc:
       link_proc = super(pagy, link_extra: link_extra)
       return link_proc unless pagy.vars[:trim_extra]
 
-      lambda do |num, text = num, extra = ''|
-        link = +link_proc.call(num, text, extra)
-        return link unless num == 1
+      lambda do |page, text = pagy.label_for(page), extra = ''|
+        link = +link_proc.call(page, text, extra)
+        return link unless page == 1
 
         pagy_trim(pagy, link)
       end

data/lib/pagy/extras/uikit.rb

@@ -1,22 +1,22 @@
 # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/uikit
 # frozen_string_literal: true
 
-require 'pagy/extras/shared'
+require 'pagy/extras/frontend_helpers'
 
 class Pagy # :nodoc:
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
   module UikitExtra
     # Pagination for uikit: it returns the html with the series of links to the pages
-    def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
 
       html = +%(<ul#{p_id} class="pagy-uikit-nav uk-pagination uk-flex-center">#{pagy_uikit_prev_html pagy, link})
-      pagy.series.each do |item|
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<li>#{link.call item}</li>)
-                when String  then %(<li class="uk-active"><span>#{pagy_labeler(pagy, item)}</span></li>)
+                when String  then %(<li class="uk-active"><span>#{pagy.label_for(item)}</span></li>)
                 when :gap    then %(<li class="uk-disabled"><span>#{pagy_t 'pagy.nav.gap'}</span></li>)
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
@@ -26,17 +26,17 @@ class Pagy # :nodoc:
     end
 
     # Javascript pagination for uikit: it returns a nav and a JSON tag used by the Pagy.nav javascript
-    def pagy_uikit_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)
+    def pagy_uikit_nav_js(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra: link_extra)
       tags = { 'before' => pagy_uikit_prev_html(pagy, link),
-               'link'   => %(<li>#{link.call(PAGE_PLACEHOLDER)}</li>),
-               'active' => %(<li class="uk-active"><span>#{PAGE_PLACEHOLDER}</span></li>),
+               'link'   => %(<li>#{link.call(PAGE_PLACEHOLDER, LABEL_PLACEHOLDER)}</li>),
+               'active' => %(<li class="uk-active"><span>#{LABEL_PLACEHOLDER}</span></li>),
                'gap'    => %(<li class="uk-disabled"><span>#{pagy_t 'pagy.nav.gap'}</span></li>),
                'after'  => pagy_uikit_next_html(pagy, link) }
 
       %(<ul#{p_id} class="pagy-njs pagy-uikit-nav-js uk-pagination uk-flex-center" #{
-        pagy_json_attr(pagy, :nav, tags, pagy.sequels(steps))}></ul>)
+        pagy_json_attr(pagy, :nav, tags, (sequels = pagy.sequels(**vars)), pagy.label_sequels(sequels))}></ul>)
     end
 
     # Javascript combo pagination for uikit: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript

data/lib/pagy/frontend.rb

@@ -6,7 +6,8 @@ require 'pagy/i18n'
 
 class Pagy
   # Used for search and replace, hardcoded also in the pagy.js file
-  PAGE_PLACEHOLDER = '__pagy_page__'
+  PAGE_PLACEHOLDER  = '__pagy_page__'
+  LABEL_PLACEHOLDER = '__pagy_label__'
 
   # Frontend modules are specially optimized for performance.
   # The resulting code may not look very elegant, but produces the best benchmarks
@@ -14,7 +15,7 @@ class Pagy
     include UrlHelpers
 
     # Generic pagination: it returns the html with the series of links to the pages
-    def pagy_nav(pagy, pagy_id: nil, link_extra: '')
+    def pagy_nav(pagy, pagy_id: nil, link_extra: '', **vars)
       p_id   = %( id="#{pagy_id}") if pagy_id
       link   = pagy_link_proc(pagy, link_extra: link_extra)
       p_prev = pagy.prev
@@ -26,10 +27,10 @@ class Pagy
               else
                 %(<span class="page prev disabled">#{pagy_t('pagy.nav.prev')}</span> )
               end
-      pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer then %(<span class="page">#{link.call item}</span> )
-                when String  then %(<span class="page active">#{pagy_labeler(pagy, item)}</span> )
+                when String  then %(<span class="page active">#{pagy.label_for(item)}</span> )
                 when :gap    then %(<span class="page gap">#{pagy_t('pagy.nav.gap')}</span> )
                 else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
@@ -64,20 +65,15 @@ class Pagy
       p_next      = pagy.next
       left, right = %(<a href="#{pagy_url_for pagy, PAGE_PLACEHOLDER}" #{
                         pagy.vars[:link_extra]} #{link_extra}).split(PAGE_PLACEHOLDER, 2)
-      lambda do |num, text = pagy_labeler(pagy, num), extra_attrs = ''|
-        %(#{left}#{num}#{right}#{ case num
-                                  when p_prev then ' rel="prev"'
-                                  when p_next then ' rel="next"'
-                                  else             ''
-                                  end } #{extra_attrs}>#{text}</a>)
+      lambda do |page, text = pagy.label_for(page), extra_attrs = ''|
+        %(#{left}#{page}#{right}#{ case page
+                                   when p_prev then ' rel="prev"'
+                                   when p_next then ' rel="next"'
+                                   else             ''
+                                   end } #{extra_attrs}>#{text}</a>)
       end
     end
 
-    # Allow customization of the output by overriding (used by the calendar extra)
-    def pagy_labeler(_pagy, num)
-      num
-    end
-
     # Similar to I18n.t: just ~18x faster using ~10x less memory
     # (@pagy_locale explicitly initialized in order to avoid warning)
     def pagy_t(key, **opts)

data/lib/pagy/url_helpers.rb

@@ -7,18 +7,32 @@ class Pagy
     # It supports all Rack-based frameworks (Sinatra, Padrino, Rails, ...).
     # For non-rack environments you can use the standalone extra
     def pagy_url_for(pagy, page, absolute: nil)
-      vars                            = pagy.vars
-      params                          = request.GET.merge(vars[:params].transform_keys(&:to_s))
-      params[vars[:page_param].to_s]  = page
-      params[vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
-
-      query_string = "?#{Rack::Utils.build_nested_query(pagy_massage_params(params))}"
+      vars                = pagy.vars
+      page_param          = vars[:page_param].to_s
+      items_param         = vars[:items_param].to_s
+      params              = pagy.params.is_a?(Hash) ? pagy.params.transform_keys(&:to_s) : {}
+      params              = request.GET.merge(params)
+      params[page_param]  = page
+      params[items_param] = vars[:items] if vars[:items_extra]
+      query_string        = "?#{Rack::Utils.build_nested_query(pagy_deprecated_params(pagy, params))}"  # remove in 6.0
+      # params              = pagy.params.call(params) if pagy.params.is_a?(Proc)                       # add in 6.0
+      # query_string        = "?#{Rack::Utils.build_nested_query(params)}"                              # add in 6.0
       "#{request.base_url if absolute}#{request.path}#{query_string}#{vars[:fragment]}"
     end
 
-    # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding
-    def pagy_massage_params(params)
-      params
+    private
+
+    # Transitional code to handle params deprecations. It will be removed in version 6.0
+    def pagy_deprecated_params(pagy, params)    # remove in 6.0
+      if pagy.params.is_a?(Proc)                # new code
+        pagy.params.call(params)
+      elsif respond_to?(:pagy_massage_params)   # deprecated code
+        Warning.warn '[PAGY WARNING] The pagy_massage_params method has been deprecated and it will be ignored from version 6. ' \
+                     'Set the :params variable to a Proc with the same code as the pagy_massage_params method.'
+        pagy_massage_params(params)
+      else
+        params                                  # no massage params
+      end
     end
   end
 end

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.2.2'
+  VERSION = '5.4.0'
 
   # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root
@@ -24,7 +24,7 @@ class Pagy
               i18n_key:   'pagy.item_name',
               cycle:      false }
 
-  attr_reader :count, :page, :items, :vars, :pages, :last, :offset, :in, :from, :to, :prev, :next
+  attr_reader :count, :page, :items, :vars, :pages, :last, :offset, :in, :from, :to, :prev, :next, :params
 
   # Merge and validate the options, do some simple arithmetic and set the instance variables
   def initialize(vars)
@@ -32,6 +32,7 @@ class Pagy
     setup_vars(count: 0, page: 1, outset: 0)
     setup_items_var
     setup_pages_var
+    setup_params_var
     raise OverflowError.new(self, :page, "in 1..#{@last}", @page) if @page > @last
 
     @offset = (@items * (@page - 1)) + @outset
@@ -43,7 +44,7 @@ class Pagy
   end
 
   # 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])
+  def series(size: @vars[:size])
     return [] if size.empty?
     raise VariableError.new(self, :size, 'to contain 4 items >= 0', size) \
           unless size.is_a?(Array) && size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier
@@ -70,6 +71,15 @@ class Pagy
     series
   end
 
+  # Allow the customization of the output (overridden by the calendar extra)
+  def label_for(page)
+    page.to_s
+  end
+
+  def label
+    @page.to_s
+  end
+
   protected
 
   # Apply defaults, cleanup blanks and set @vars
@@ -94,6 +104,12 @@ class Pagy
   def setup_pages_var
     @pages = @last = [(@count.to_f / @items).ceil, 1].max
   end
+
+  # Setup and validates the params
+  def setup_params_var
+    raise VariableError.new(self, :params, 'must be a Hash or a Proc', @params) \
+          unless (@params = @vars[:params]).is_a?(Hash) || @params.is_a?(Proc)
+  end
 end
 
 require 'pagy/backend'

data/lib/templates/foundation_nav.html.erb

@@ -13,7 +13,7 @@
 <% end                         -%>
 <% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
 <%   if    item.is_a?(Integer) -%>    <li><%== link.call(item) %></li>
-<%   elsif item.is_a?(String)  -%>    <li class="current"><%= pagy_labeler(pagy, item) %></li>
+<%   elsif item.is_a?(String)  -%>    <li class="current"><%= pagy.label_for(item) %></li>
 <%   elsif item == :gap        -%>    <li class="ellipsis gap" aria-hidden="true"></li>
 <%   end                       -%>
 <% end                         -%>

data/lib/templates/foundation_nav.html.haml

@@ -22,7 +22,7 @@
 
       - elsif item.is_a?(String)                      # current page
         %li.current
-          = pagy_labeler(pagy, item)
+          = pagy.label_for(item)
 
       - elsif item == :gap                            # page gap
         %li.ellipsis.gap{"aria-hidden" => true}

data/lib/templates/foundation_nav.html.slim

@@ -22,7 +22,7 @@ nav.pagy-foundation-nav role="navigation" aria-label="Pagination"
 
       - elsif item.is_a?(String)                 # current page
         li.current
-          = pagy_labeler(pagy, item)
+          = pagy.label_for(item)
 
       - elsif item == :gap                       # page gap
         li.ellipsis.gap aria-hidden="true"

data/lib/templates/uikit_nav.html.erb

@@ -5,7 +5,7 @@
 <% end                         -%>
 <% pagy.series.each do |item|  -%>
 <%   if    item.is_a?(Integer) -%>   <li><%== link.call(item) %></li>
-<%   elsif item.is_a?(String)  -%>   <li class="uk-active"><span><%== pagy_labeler(pagy, item) %></span></li>
+<%   elsif item.is_a?(String)  -%>   <li class="uk-active"><span><%== pagy.label_for(item) %></span></li>
 <%   elsif item == :gap        -%>   <li class="uk-disabled"><span><%== pagy_t('pagy.nav.gap') %></span></li>
 <%   end                       -%>
 <% end                         -%>

data/lib/templates/uikit_nav.html.haml

@@ -14,7 +14,7 @@
 
     - elsif item.is_a?(String)
       %li.uk-active
-        %span!= pagy_labeler(pagy, item)
+        %span!= pagy.label_for(item)
 
     - elsif item == :gap
       %li.uk-disabled