From 75329b45a56cabeea843120502e3340b6f21f81d Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Wed, 13 Mar 2019 12:43:24 +0700 Subject: [PATCH 1/3] better configuration example and documentation for responsive breakpoints (#140) --- docs/extras/plain.md | 46 ++++++++++++++++++++++++++++++++++++++------ lib/config/pagy.rb | 4 ++-- 2 files changed, 42 insertions(+), 8 deletions(-) diff --git a/docs/extras/plain.md b/docs/extras/plain.md index db6bbfb8c..df155bc83 100644 --- a/docs/extras/plain.md +++ b/docs/extras/plain.md @@ -53,7 +53,7 @@ Other extras provide also the following framework-styled helpers: Renders a compact navigation with a style similar to the `pagy_nav` helper. -It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_plain_compact_nav*` call in the same line for the same page. +It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_responsive_nav` or `pagy_*_compact_nav` call in the same line for the same page. **Notice**: passing an explicit id is also a bit faster than having pagy to generate one. @@ -61,7 +61,7 @@ It can take an extra `id` argument, which is used to build the `id` attribute of With the `responsive` navs (implemented by this extra or by other frontend extras) the number of page links will adapt in real-time to the available window or container width. -Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav might look like by resizing the browser window at different widths: +Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav might look like by resizing the browser window/container at different widths: ![pagy-responsive](../assets/images/pagy-responsive-g.png) @@ -69,7 +69,7 @@ Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav ```ruby # set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance) -Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} +Pagy::VARS[:breakpoints] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] } ``` Use the responsive helper(s) in any view: @@ -96,21 +96,55 @@ The `:breakpoints` variable is a non-core variable used by the `responsive` navs For example: ```ruby -Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} +Pagy::VARS[:breakpoints] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] } ``` -The above statement means that from `0` to `450` pixels width, Pagy will use the `[1,2,2,1]` size, from `450` to `750` it will use the `[3,4,4,3]` size and over `750` it will use the `[4,5,5,4]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section) +The above statement means that from `0` to `540` pixels width, Pagy will use the `[1,0,0,1]` size, from `540` to `720` it will use the `[2,3,3,4]` size and over `720` it will use the `[3,4,4,3]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section). **IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing. **Notice**: Each added breakpoint slowers down Pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate. +#### Setting the right breakpoints + +Setting the width and the size of your breakpoint is what could create a nice transition between sizes... or some apparently erratic behavior. + +Here is what you should consider. + +The transition from one breakpoint/size to another depends by the width available to your nav. That width is the _internal available width_ of its container (excluding eventual horizontal padding), so the pagy breakpoint widths that you set should reflect the container internal available widths. + +The container width can change as a continous range (normal behavior for a div) or in discrete steps (for example when using bootstrap the container has classes like `sm-md-lg`). + +##### Continous Width-ranges + +For continous width-range containers you should ensure that the resulting navs can be contained in the breakpoint widths that you set. In other words if you create a size as `[20,20,20,20]`, is pretty obvious that it could not be contained in a `540` width, so assign reasonable sizes based on the available widths. + +##### Discrete Step Widths + +If you use frameworks like bootstrap (but the same applies to many others) you can assign classes to your container that will snap to specific widths (e.g. `sm-md-lg`). In that case you should sync the quantity and widths of the pagy brakpoints to the quantity and internal container widths of the bootstrap classes. + +**IMPORTANT**: The pagy breakpoint widths should not be the same bootstrap breakpoints widths, but the container internal available widths. + +For example: if you assign the following classes: + +``` +sm = Small ≥576px +Max container width 540px + +md = Medium ≥768px +Max container width 720px + +lg = Large ≥992px +Max container width 960px +``` +You should use the `0`, `540` and `720` width (or less if there is padding), and assign consistent sizes. + ## Methods ### pagy_plain_responsive_nav(pagy, ...) Similar to the `pagy_nav` helper, with added responsiveness. -It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_plain_responsive_nav*` call in the same line for the same file. +It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_responsive_nav` or `pagy_*_compact_nav` call in the same line for the same file. **Notice**: passing an explicit id is also a bit faster than having pagy to generate one. diff --git a/lib/config/pagy.rb b/lib/config/pagy.rb index 029029a9a..52ba66660 100644 --- a/lib/config/pagy.rb +++ b/lib/config/pagy.rb @@ -60,8 +60,8 @@ # Breakpoints var used by the responsive nav helpers # See https://ddnexus.github.io/pagy/extras/plain#breakpoints -# Pagy::VARS[:breakpoints] = { 0 => [1,2,2,1], 350 => [2,3,3,2], 550 => [3,4,4,3] } # example of width/size pairs - +# width/size pairs: example for bootstrap4 sm-md-lg internal container widths +# Pagy::VARS[:breakpoints] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] } # Feature Extras From e9f467a49233a1c31233108a536e9a8a61cc1917 Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Wed, 13 Mar 2019 19:05:38 +0700 Subject: [PATCH 2/3] fix for pagy_url_for not working with multiple pagy in the same request --- lib/pagy/frontend.rb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/pagy/frontend.rb b/lib/pagy/frontend.rb index 44f23d327..8f855e253 100644 --- a/lib/pagy/frontend.rb +++ b/lib/pagy/frontend.rb @@ -13,10 +13,12 @@ class Pagy module Helpers # This works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...) def pagy_url_for(page, pagy, path_or_url=:path) - p_vars = pagy.vars; params = request.GET; params[p_vars[:page_param].to_s] = page; params.merge!(p_vars[:params]) + p_vars = pagy.vars; params = request.GET.merge(p_vars[:params]); params[p_vars[:page_param].to_s] = page "#{request.send(path_or_url)}?#{Rack::Utils.build_nested_query(pagy_get_params(params))}#{p_vars[:anchor]}" end + + # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding def pagy_get_params(params) params end end From 7f928177266e194c1ed7cca0fbe1a77283cdc761 Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Wed, 13 Mar 2019 21:17:03 +0700 Subject: [PATCH 3/3] version 2.1.1 --- lib/pagy.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/pagy.rb b/lib/pagy.rb index 5f815e7ec..a46d99365 100644 --- a/lib/pagy.rb +++ b/lib/pagy.rb @@ -4,7 +4,7 @@ require 'pathname' -class Pagy ; VERSION = '2.1.0' +class Pagy ; VERSION = '2.1.1' class OverflowError < StandardError; attr_reader :pagy; def initialize(pagy) @pagy = pagy end; end