From d791a04d525b41b377d44ebd4777391d20895ebe Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Wed, 28 Apr 2021 20:30:28 +0700 Subject: [PATCH] deprecated :anchor variable in favor of :fragment --- docs/api/pagy.md | 18 +++++++++--------- docs/how-to.md | 8 ++++---- lib/config/pagy.rb | 2 +- lib/pagy.rb | 5 +++-- lib/pagy/deprecation.rb | 11 +++++++++-- lib/pagy/frontend.rb | 2 +- test/pagy/derecation_test.rb | 11 +++++++++-- test/pagy/extras/items_test.rb | 12 ++++++------ test/pagy/extras/metadata_test.rb | 2 +- test/pagy/frontend_test.rb | 20 ++++++++++---------- 10 files changed, 53 insertions(+), 38 deletions(-) diff --git a/docs/api/pagy.md b/docs/api/pagy.md index 8ad311dab..27eaf3445 100644 --- a/docs/api/pagy.md +++ b/docs/api/pagy.md @@ -81,15 +81,15 @@ They are all integers: ### Other Variables -| Variable | Description | Default | -|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| -| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` | -| `:page_param` | the name of the page param name used in the url. _(see [Customizing the page param](../how-to.md#customizing-the-page-param))_ | `:page` | -| `:params` | the arbitrary param hash to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_ | `{}` | -| `:anchor` | the arbitrary anchor string (including the "#") to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_ | `""` | -| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [Customizing the link attributes](../how-to.md#customizing-the-link-attributes))_ | `""` | -| `:i18n_key` | the i18n key to lookup the `item_name` that gets interpolated in a few helper outputs _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_ | `"pagy.item_name"` | -| `:cycle` | enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` | +| Variable | Description | Default | +|:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| +| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` | +| `:page_param` | the name of the page param name used in the url. _(see [Customizing the page param](../how-to.md#customizing-the-page-param))_ | `:page` | +| `:params` | the arbitrary param hash to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_ | `{}` | +| `:fragment` | the arbitrary fragment string (including the "#") to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_ | `""` | +| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [Customizing the link attributes](../how-to.md#customizing-the-link-attributes))_ | `""` | +| `:i18n_key` | the i18n key to lookup the `item_name` that gets interpolated in a few helper outputs _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_ | `"pagy.item_name"` | +| `:cycle` | enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` | There is no specific validation for non-instance variables. diff --git a/docs/how-to.md b/docs/how-to.md index d07217f70..db9c02c32 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -242,13 +242,13 @@ def pagy_get_params(params) end ``` -You can also use the `:params` and : `:anchor` variables to add arbitrary params to the URLs of the pages. For example: +You can also use the `:params` and : `:fragment` variables to add arbitrary params to the URLs of the pages. For example: ```ruby -@pagy, @records = pagy(some_scope, params: {custom: 'param'}, anchor: '#your-anchor') +@pagy, @records = pagy(some_scope, params: {custom: 'param'}, fragment: '#your-fragment') ``` -**IMPORTANT**: For performance reasons the `:anchor` string must include the `"#"`. +**IMPORTANT**: For performance reasons the `:fragment` string must include the `"#"`. ## Customizing the URL @@ -313,7 +313,7 @@ You have a few ways to do that: 3. you can override entirely the `:item_name` by passing an already pluralized string directly to the helper call: ```erb <%== pagy_info(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %> - <%== pagy_items_selector_js(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %> + <%== pagy_items_selector_js(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %> ``` **Notice**: The variables passed to a Pagy object have the precedence over the variables returned by the `pagy_get_vars`. The fastest way to set the `i18n_key` is passing a literal string to the `pagy` method, the most convenient way is using `pagy_get_vars`, the most flexible way is passing a pluralized string to the helper. diff --git a/lib/config/pagy.rb b/lib/config/pagy.rb index 2cb3dabac..c43c4a658 100644 --- a/lib/config/pagy.rb +++ b/lib/config/pagy.rb @@ -23,7 +23,7 @@ # Pagy::VARS[:size] = [1,4,4,1] # default # Pagy::VARS[:page_param] = :page # default # Pagy::VARS[:params] = {} # default -# Pagy::VARS[:anchor] = '#anchor' # example +# Pagy::VARS[:fragment] = '#fragment' # example # Pagy::VARS[:link_extra] = 'data-remote="true"' # example # Pagy::VARS[:i18n_key] = 'pagy.item_name' # default # Pagy::VARS[:cycle] = true # example diff --git a/lib/pagy.rb b/lib/pagy.rb index f64db7218..76bb2ee13 100644 --- a/lib/pagy.rb +++ b/lib/pagy.rb @@ -14,7 +14,7 @@ def self.root # default vars VARS = { page: 1, items: 20, outset: 0, size: [1, 4, 4, 1], page_param: :page, # rubocop:disable Style/MutableConstant - params: {}, anchor: '', link_extra: '', i18n_key: 'pagy.item_name', cycle: false } + params: {}, fragment: '', link_extra: '', i18n_key: 'pagy.item_name', cycle: false } attr_reader :count, :page, :items, :vars, :pages, :last, :offset, :from, :to, :prev, :next @@ -23,6 +23,7 @@ def self.root # Merge and validate the options, do some simple arithmetic and set the instance variables def initialize(vars) @vars = VARS.merge( vars.delete_if{|_,v| v.nil? || v == '' } ) + @vars[:fragment] = deprecated_var(:anchor, @vars[:anchor], :fragment, @vars[:fragment]) if @vars[:anchor] INSTANCE_VARS_MIN.each do |name,min| raise VariableError.new(self), "expected :#{name} >= #{min}; got #{@vars[name].inspect}" \ @@ -66,7 +67,7 @@ def series(size=@vars[:size]) series[series.index(@page)] = @page.to_s series end - + end require 'pagy/deprecation' diff --git a/lib/pagy/deprecation.rb b/lib/pagy/deprecation.rb index 27f99fb04..17f821026 100644 --- a/lib/pagy/deprecation.rb +++ b/lib/pagy/deprecation.rb @@ -2,14 +2,21 @@ class Pagy class << self - # deprecated pagy_url_for rgument order + # deprecated variables + def deprecated_var(var, val, new_var, new_val) + value = new_val || val + Warning.warn %([PAGY WARNING] deprecated use of `#{var}` var will not be supported in 5.0! Use `#{new_var}: #{value.inspect}` instead.) + value + end + + # deprecated pagy_url_for argument order def deprecated_order(pagy, page) Warning.warn '[PAGY WARNING] inverted use of pagy/page in pagy_url_for will not be supported in 5.0! Use pagy_url_for(pagy, page) instead.' [page, pagy] end - # deprecated arguments to remove in 5.0 + # deprecated posiitioal arguments def deprecated_arg(arg, val, new_key, new_val) value = new_val || val # we use the new_val if present Warning.warn %([PAGY WARNING] deprecated use of positional `#{arg}` arg will not be supported in 5.0! Use only the keyword arg `#{new_key}: #{value.inspect}` instead.) diff --git a/lib/pagy/frontend.rb b/lib/pagy/frontend.rb index 5de0267ec..265858a8e 100644 --- a/lib/pagy/frontend.rb +++ b/lib/pagy/frontend.rb @@ -21,7 +21,7 @@ def pagy_url_for(pagy, page, deprecated_url=nil, absolute: nil) params[p_vars[:page_param].to_s] = page params[p_vars[:items_param].to_s] = p_vars[:items] if defined?(UseItemsExtra) 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]}" + "#{request.base_url if absolute}#{request.path}#{query_string}#{p_vars[:fragment]}" end # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding diff --git a/test/pagy/derecation_test.rb b/test/pagy/derecation_test.rb index 0fb6d8ca5..c8c43b59b 100644 --- a/test/pagy/derecation_test.rb +++ b/test/pagy/derecation_test.rb @@ -3,7 +3,14 @@ require_relative '../test_helper' describe 'pagy/deprecation' do - + + describe 'Pagy.deprecated_var' do + it 'deprecate arg and returns right value' do + _ { _(Pagy.deprecated_var(:var, 'deprecated-val', :new_var, 'new-value')).must_equal 'new-value' }.must_output nil, \ + "[PAGY WARNING] deprecated use of `var` var will not be supported in 5.0! Use `new_var: \"new-value\"` instead." + end + end + describe 'Pagy.deprecated_arg' do it 'deprecate arg and returns right value' do _ { _(Pagy.deprecated_arg(:arg, 'deprecated-val', :new_key, 'new-value')).must_equal 'new-value' }.must_output nil, \ @@ -15,6 +22,6 @@ it 'deprecate arg order and returns them inverted' do _ { _(Pagy.deprecated_order('page', 'pagy')).must_equal %w[pagy page] }.must_output nil, \ "[PAGY WARNING] inverted use of pagy/page in pagy_url_for will not be supported in 5.0! Use pagy_url_for(pagy, page) instead." - end + end end end diff --git a/test/pagy/extras/items_test.rb b/test/pagy/extras/items_test.rb index 9d2a8229b..2a711ed3e 100644 --- a/test/pagy/extras/items_test.rb +++ b/test/pagy/extras/items_test.rb @@ -122,13 +122,13 @@ def test_items_vars_params(items, vars, params) pagy = Pagy.new count: 1000, page: 3, items_param: :custom _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&custom=20' 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&items=20#anchor' + it 'renders url with fragment' do + pagy = Pagy.new count: 1000, page: 3, fragment: '#fragment' + _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6&items=20#fragment' end - it 'renders url with params and anchor' do - pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor', items: 40 - _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4&items=40#anchor" + it 'renders url with params and fragment' do + pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, fragment: '#fragment', items: 40 + _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4&items=40#fragment" end end it 'renders items selector' do diff --git a/test/pagy/extras/metadata_test.rb b/test/pagy/extras/metadata_test.rb index 058e67286..14434a906 100644 --- a/test/pagy/extras/metadata_test.rb +++ b/test/pagy/extras/metadata_test.rb @@ -18,7 +18,7 @@ it 'returns the full pagy metadata' do pagy, _records = @controller.send(:pagy, @collection) _(@controller.send(:pagy_metadata, pagy)).must_equal( - {:scaffold_url=>"/foo?page=__pagy_page__", :first_url=>"/foo?page=1", :prev_url=>"/foo?page=2", :page_url=>"/foo?page=3", :next_url=>"/foo?page=4", :last_url=>"/foo?page=50", :count=>1000, :page=>3, :items=>20, :vars=>{:page=>3, :items=>20, :outset=>0, :size=>[1, 4, 4, 1], :page_param=>:page, :params=>{}, :anchor=>"", :link_extra=>"", :i18n_key=>"pagy.item_name", :cycle=>false, :steps=>false, :metadata=>[:scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url, :count, :page, :items, :vars, :pages, :last, :from, :to, :prev, :next, :series, :sequels], :count=>1000}, :pages=>50, :last=>50, :from=>41, :to=>60, :prev=>2, :next=>4, :series=>[1, 2, "3", 4, 5, 6, 7, :gap, 50], :sequels=>{"0"=>[1, 2, "3", 4, 5, 6, 7, :gap, 50]}} + {:scaffold_url=>"/foo?page=__pagy_page__", :first_url=>"/foo?page=1", :prev_url=>"/foo?page=2", :page_url=>"/foo?page=3", :next_url=>"/foo?page=4", :last_url=>"/foo?page=50", :count=>1000, :page=>3, :items=>20, :vars=>{:page=>3, :items=>20, :outset=>0, :size=>[1, 4, 4, 1], :page_param=>:page, :params=>{}, :fragment=>"", :link_extra=>"", :i18n_key=>"pagy.item_name", :cycle=>false, :steps=>false, :metadata=>[:scaffold_url, :first_url, :prev_url, :page_url, :next_url, :last_url, :count, :page, :items, :vars, :pages, :last, :from, :to, :prev, :next, :series, :sequels], :count=>1000}, :pages=>50, :last=>50, :from=>41, :to=>60, :prev=>2, :next=>4, :series=>[1, 2, "3", 4, 5, 6, 7, :gap, 50], :sequels=>{"0"=>[1, 2, "3", 4, 5, 6, 7, :gap, 50]}} ) end it 'checks for unknown metadata' do diff --git a/test/pagy/frontend_test.rb b/test/pagy/frontend_test.rb index 193d050cf..beb3c31c4 100644 --- a/test/pagy/frontend_test.rb +++ b/test/pagy/frontend_test.rb @@ -139,23 +139,23 @@ _(view.pagy_url_for(pagy, 5)).must_equal "/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, absolute: true)).must_equal 'http://example.com:3000/foo?page=6#anchor' + it 'renders url with fragment' do + pagy = Pagy.new count: 1000, page: 3, fragment: '#fragment' + _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6#fragment' + _(view.pagy_url_for(pagy, 6, absolute: true)).must_equal 'http://example.com:3000/foo?page=6#fragment' 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, absolute: true)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#anchor" + it 'renders url with params and fragment' do + pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, fragment: '#fragment' + _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4#fragment" + _(view.pagy_url_for(pagy, 5, absolute: true)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#fragment" end end describe '#pagy_get_params' do it 'overrides params' do overridden = MockView::Overridden.new - pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor' - _(overridden.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&b=4&k=k#anchor" + pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, fragment: '#fragment' + _(overridden.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&b=4&k=k#fragment" end end