completed args conversion also for pagy_url_for and pagy_metadata

CHANGELOG.md

@@ -4,16 +4,17 @@
 
 ### Changes
 
-- All the public helpers accept optional keyword arguments, for example:
+- Passing positional arguments (besides `@pagy`) to all the helpers is deprecated and it will be supported only until pagy 5.0
+- All the helpers accept more optional keyword arguments, for example:
   - `pagy*_nav(@pagy, pagy_id: 'my-id', link-extra: '...')`
   - `pagy*_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...', steps: {...})`
   - `pagy*_combo_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...')`
   - `pagy_items_selector_js(pagy, pagy_id: 'my-id', item_name: '...', i18n_key: '...')`
   - `pagy_info(@pagy, pagy_id: 'my-id', item_name: '...', i18n_key: '...')`
   - `pagy_prev_link(@pagy, text: '...', link_extra: '...')`
   - `pagy_next_link(@pagy, text: '...', link_extra: '...')`
-  - passing positional arguments (besides `@pagy`) to the public helpers is deprecated and it will be supported only until pagy 5.0 (with the exception is the internal `pagy_url_for` and `pagy_link_proc` methods that will keep using positional arguments)
-- Changed the argument order of `pagy_url_for(page, pagy)` to `pagy_url_for(pagy, page)` for consistency with the rest of the helpers. The legacy usage, has been deprecated and supported only until pagy 5.0.
+  - `pagy_link_proc(@pagy, link_extra: '...')`
+  - `pagy_url_for(pagy, page, absolute: nil)` (notice the inverted page/pagy order with the legacy`pagy_url_for(page, pagy, url=nil)`)
 
 ## Version 4.3.0
 

docs/api/frontend.md

@@ -76,7 +76,7 @@ Displaying Products <b>476-500</b> of <b>1000</b> in total
 
 _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_
 
-### pagy_url_for(pagy, page)
+### pagy_url_for(pagy, page, absolute: nil)
 
 This method is called internally in order to produce the url of a page by passing it its number. For standard usage it works out of the box and you can just ignore it.
 

docs/extras/items.md

@@ -73,7 +73,7 @@ This extra overrides the `pagy_get_vars` method of the `Pagy::Backend` module in
 
 This extra overrides the `pagy_countless_get_vars` method of the `Pagy::Backend` module (added by the `countless` extra) in order to set the `:items` variable, pulled from the request-params.
 
-### pagy_url_for(pagy, page)
+### pagy_url_for(pagy, page, absolute: nil)
 
 This extra overrides also the `pagy_url_for` method of the `Pagy::Frontend` module in order to add the `:items_param` param to the url of the links.
 

docs/extras/metadata.md

@@ -22,7 +22,7 @@ In your controller action:
 ```ruby
 pagy, records = pagy(Product.all)
 render json: { data: records,
-               pagy: pagy_metadata(pagy) }
+               pagy: pagy_metadata(pagy, ...) }
 ```
 
 ## Files
@@ -61,6 +61,6 @@ This is particularly useful when you want to build some dynamic pagination UI (e
 
 This extra adds a single method to the `Pagy::Backend` (available in your controllers).
 
-### pagy_metadata(pagy, url=false)
+### pagy_metadata(pagy, absolute: nil)
 
 This method returns a hash with the keys/values defined by the `:metadata` variable.  When true, the `url` boolean argument will cause all the `:*_url` metadata to be absolute instead of relative.

docs/how-to.md

@@ -78,7 +78,7 @@ This page contains the practical tips and examples to get the job done with Pagy
 
            ```ruby
            render json: { data: @records,
-                          pagy: pagy_metadata(@pagy) }
+                          pagy: pagy_metadata(@pagy, ...) }
            ```
 
     - Option C: if your app is an API service consumed by some client and doesn't provide any UI on its own, you don't need the `include Pagy::Frontend` in `ApplicationHelper`, instead:
@@ -260,7 +260,7 @@ The following is a Rails-specific alternative that supports fancy-routes (e.g. `
 
 ```ruby
 def pagy_url_for(pagy, page)
-  params = request.query_parameters.merge(:only_path => true, pagy.vars[:page_param] => page )
+  params = request.query_parameters.merge(pagy.vars[:page_param] => page )
   url_for(params)
 end
 ```

lib/pagy/extras/headers.rb

@@ -24,7 +24,7 @@ def pagy_headers_hash(pagy)
       countless = defined?(Pagy::Countless) && pagy.is_a?(Pagy::Countless)
       rels = { 'first' => 1, 'prev' => pagy.prev, 'next' => pagy.next }
       rels['last'] = pagy.last unless countless
-      url_str = pagy_url_for(pagy, PAGE_PLACEHOLDER, :url)
+      url_str = pagy_url_for(pagy, PAGE_PLACEHOLDER, absolute: true)
       hash    = { 'Link' => rels.filter_map do |rel, num|
                               next unless num
                               [ rel, url_str.sub(PAGE_PLACEHOLDER, num.to_s) ]

lib/pagy/extras/items.rb

@@ -37,13 +37,15 @@ module Frontend
 
     module UseItemsExtra
 
-      def pagy_url_for(pagy, page, url=nil)
+      def pagy_url_for(pagy, page,  deprecated_url=nil, absolute: nil)
+        absolute = Pagy.deprecated_arg(:url, deprecated_url, :absolute, absolute) if deprecated_url
         pagy, page = Pagy.deprecated_order(pagy, page) if page.is_a?(Pagy)
         p_vars = pagy.vars
         params = request.GET.merge(p_vars[:params])
         params[p_vars[:page_param].to_s]  = page
         params[p_vars[:items_param].to_s] = p_vars[:items]
-        "#{request.base_url if url}#{request.path}?#{Rack::Utils.build_nested_query(pagy_get_params(params))}#{p_vars[:anchor]}"
+        query_string = "?#{Rack::Utils.build_nested_query(pagy_get_params(params))}" unless params.empty?
+        "#{request.base_url if absolute}#{request.path}#{query_string}#{p_vars[:anchor]}"
       end
 
     end

lib/pagy/extras/metadata.rb

@@ -16,13 +16,14 @@ module Backend
 
     include Helpers
 
-    def pagy_metadata(pagy, url=nil)
+    def pagy_metadata(pagy, deprecated_url=nil, absolute: nil)
+      absolute = Pagy.deprecated_arg(:url, deprecated_url, :absolute, absolute) if deprecated_url
       names   = pagy.vars[:metadata]
       unknown = names - METADATA
       raise VariableError.new(pagy), "unknown metadata #{unknown.inspect}" \
             unless unknown.empty?
 
-      scaffold_url = pagy_url_for(pagy, PAGE_PLACEHOLDER, url)
+      scaffold_url = pagy_url_for(pagy, PAGE_PLACEHOLDER, absolute: absolute)
       {}.tap do |metadata|
         names.each do |key|
           metadata[key] = case key

lib/pagy/frontend.rb

@@ -13,13 +13,14 @@ class Pagy
 
   module Helpers
     # This works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...)
-    def pagy_url_for(pagy, page, url=nil)
+    def pagy_url_for(pagy, page, deprecated_url=nil, absolute: nil)
+      absolute = Pagy.deprecated_arg(:url, deprecated_url, :absolute, absolute) if deprecated_url
       pagy, page = Pagy.deprecated_order(pagy, page) if page.is_a?(Pagy)
       p_vars = pagy.vars
       params = request.GET.merge(p_vars[:params])
       params[p_vars[:page_param].to_s] = page
       query_string = "?#{Rack::Utils.build_nested_query(pagy_get_params(params))}" unless params.empty?
-      "#{request.base_url if url}#{request.path}#{query_string}#{p_vars[:anchor]}"
+      "#{request.base_url if absolute}#{request.path}#{query_string}#{p_vars[:anchor]}"
     end
 
     # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding

test/pagy/frontend_test.rb

@@ -132,22 +132,22 @@
     it 'renders basic url' do
       pagy = Pagy.new count: 1000, page: 3
       _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5'
-      _(view.pagy_url_for(pagy, 5, :url)).must_equal 'http://example.com:3000/foo?page=5'
+      _(view.pagy_url_for(pagy, 5, absolute: true)).must_equal 'http://example.com:3000/foo?page=5'
     end
     it 'renders url with params' do
       pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}
       _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4"
-      _(view.pagy_url_for(pagy, 5, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4"
+      _(view.pagy_url_for(pagy, 5, absolute: true)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4"
     end
     it 'renders url with anchor' do
       pagy = Pagy.new count: 1000, page: 3, anchor: '#anchor'
       _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6#anchor'
-      _(view.pagy_url_for(pagy, 6, :url)).must_equal 'http://example.com:3000/foo?page=6#anchor'
+      _(view.pagy_url_for(pagy, 6, absolute: true)).must_equal 'http://example.com:3000/foo?page=6#anchor'
     end
     it 'renders url with params and anchor' do
       pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor'
       _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4#anchor"
-      _(view.pagy_url_for(pagy, 5, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#anchor"
+      _(view.pagy_url_for(pagy, 5, absolute: true)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#anchor"
     end
   end