pagy 5.2.3 → 5.5.0

data/lib/pagy/extras/calendar.rb

@@ -4,43 +4,73 @@
 require 'pagy/calendar'
 
 class Pagy # :nodoc:
-  # Paginate based on calendar periods (year month week day)
+  # Paginate based on calendar periods (year month week day) plus the regular pagination
   module CalendarExtra
     # Additions for the Backend module
     module Backend
+      CONF_KEYS = %i[year month week day pagy active].freeze
+
       private
 
-      # Return Pagy object and items
-      def pagy_calendar(collection, vars = {})
-        pagy = Calendar.new(pagy_calendar_get_vars(collection, vars))
-        [pagy, pagy_calendar_get_items(collection, pagy)]
+      # Take a collection and a conf Hash with keys in [:year, :month: week, :day, :pagy: :active];
+      # The calendar is active by default, but it can be explicitly inactivated with `active: false`
+      # Return a hash with 3 items:
+      # 0. Array of pagy calendar unit objects
+      # 1. Pagy object
+      # 2. Array of results
+      def pagy_calendar(collection, conf)
+        unless conf.is_a?(Hash) && (conf.keys - CONF_KEYS).empty? && conf.all? { |k, v| v.is_a?(Hash) || k == :active }
+          raise ArgumentError, "keys must be in #{CONF_KEYS.inspect} and object values must be Hashes; got #{conf.inspect}"
+        end
+
+        conf[:pagy]          = {} unless conf[:pagy]  # use default Pagy object when omitted
+        calendar, collection = pagy_setup_calendar(collection, conf) unless conf.key?(:active) && !conf[:active]
+        pagy, result         = send(conf[:pagy][:backend] || :pagy, collection, conf[:pagy])  # use backend: :pagy when omitted
+        [calendar, pagy, result]
       end
 
-      # Sub-method called only by #pagy_calendar: here for easy customization of variables by overriding.
-      # You may want to override it in order to implement the dynamic set of the :minmax variable.
-      def pagy_calendar_get_vars(_collection, vars)
-        # vars[:minmax] ||= your_own_method_to_get_the_period_from(collection)
-        vars[:page] ||= params[vars[:page_param] || DEFAULT[:page_param]]
-        vars
+      # Setup and return the calendar objects and the filtered collection
+      def pagy_setup_calendar(collection, conf)
+        units      = Calendar::UNITS.keys & conf.keys
+        page_param = conf[:pagy][:page_param] || DEFAULT[:page_param]
+        units.each do |unit|  # set all the :page_param vars for later deletion
+          unit_page_param = :"#{unit}_#{page_param}"
+          conf[unit][:page_param] = unit_page_param
+          conf[unit][:page]       = params[unit_page_param]
+        end
+        calendar = {}
+        period   = pagy_calendar_period(collection)
+        units.each_with_index do |unit, index|
+          params_to_delete    = units[(index + 1), units.size].map { |sub| conf[sub][:page_param] } + [page_param]
+          conf[unit][:params] = lambda do |params|  # delete page_param from the sub-units
+                                  params_to_delete.each { |p| params.delete(p.to_s) } # Hash#except missing from 2.5 baseline
+                                  params
+                                end
+          conf[unit][:period] = period
+          calendar[unit]      = Calendar.create(unit, conf[unit])
+          period              = calendar[unit].active_period # set the period for the next unit
+        end
+        [calendar, pagy_calendar_filter(collection, calendar[units.last].from, calendar[units.last].to)]
       end
 
-      # This method should be implemented in the application and should return the records
-      # for the unit by selecting the records with DateTime from pagy.from to pagy.to
-      def pagy_calendar_get_items(_collection, _pagy)
-        # collection.your_own_method_to_get_the_items_with(pagy.from, pagy.to)
-        raise NoMethodError, 'The pagy_calendar_get_items method must be implemented in the application and must return ' \
-                             'the items for the unit by selecting the records with Time from pagy.from to pagy.to'
+      # This method must be implemented by the application.
+      # It must return the the starting and ending local Time objects defining the calendar :period
+      def pagy_calendar_period(*)
+        # return_period_array_using(collection)
+        raise NoMethodError, 'the pagy_calendar_period method must be implemented by the application and must return ' \
+                             'the starting and ending local Time objects array defining the calendar :period'
       end
-    end
 
-    # Additions for the Frontend module
-    module Frontend
-      # Change the text shown in the nav bar links to the actual unit of each page.
-      def pagy_labeler(pagy, num)
-        pagy.is_a?(Calendar) ? pagy.page_label(num) : num
+      # This method must be implemented by the application.
+      # It receives the main collection and must return a filtered version of it.
+      # The filter logic must be equivalent to {storage_time >= from && storage_time < to}
+      def pagy_calendar_filter(*)
+        # return_filtered_collection_using(collection, from, to)
+        raise NoMethodError, 'the pagy_calendar_filter method must be implemented by the application and must return the ' \
+                             'collection filtered by a logic equivalent to '\
+                             '{storage_time >= from && storage_time < to}'
       end
     end
   end
   Backend.prepend CalendarExtra::Backend
-  Frontend.prepend CalendarExtra::Frontend
 end

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

@@ -29,8 +29,8 @@ class Pagy # :nodoc:
         when :empty_page
           @offset = @items = @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)
+            edge = @order == :asc ? @final : @initial  # get the edge of the overflow side (neat, but any time would do)
+            @from = @to = edge                         # 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
@@ -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