© 2018 Domizio DemichelisMIT License

Plain Extra

This extra adds a couple of nav helpers to the Pagy::Frontend module: pagy_plain_compact_nav and pagy_plain_responsive_nav. It also adds the :pagy_plain_nav alias (pointing to the :pagy_nav for naming consistency). These are the plain/unstyled nav helpers for pagination.

Other extras (e.g. bootstrap, bulma, foundation, materialize, semantic) provide framework-styled versions of the same nav, responsive and compact helpers, so you may not need this extra if you use one of those.

Synopsis

See extras for general usage info.

In the pagy.rb initializer:

require 'pagy/extras/plain'

Configure javascript.

Files

Compact navs

The compact navs (implemented by this extra or by other frontend extras) add an alternative pagination UI that combines the pagination feature with the navigation info in a single compact element.

It is especially useful for small size screens, but it is used also with wide layouts since it is even faster than the classic nav of links, because it needs to render just a minimal HTML string.

Synopsis

Use the responsive helper(s) in any view:

<%== pagy_plain_compact_nav(@pagy) %>

Other extras provide also the following framework-styled helpers:

<%== pagy_bootstrap_compact_nav(@pagy) %>
<%== pagy_bulma_compact_nav(@pagy) %>
<%== pagy_foundation_compact_nav(@pagy) %>
<%== pagy_materialize_compact_nav(@pagy) %>
<%== pagy_semantic_compact_nav(@pagy) %>

Methods

pagy_plain_compact_nav(pagy, …)

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_*_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.

Responsive navs

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 bootstrapextra) of how the same pagination nav might look like by resizing the browser window/container at different widths:

pagy-responsive

Synopsis

# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance)
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:

<%== pagy_plain_responsive_nav(@pagy) %>

Other extras provide also the following framework-styled helpers:

<%== pagy_bootstrap_responsive_nav(@pagy) %>
<%== pagy_bulma_responsive_nav(@pagy) %>
<%== pagy_foundation_responsive_nav(@pagy) %>
<%== pagy_materialize_responsive_nav(@pagy) %>
<%== pagy_semantic_responsive_nav(@pagy) %>

Variables

:breakpoints

The :breakpoints variable is a non-core variable used by the responsive navs. It allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the Pagy :size variables to be applied for that width. For example:

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 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 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 you should 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 their 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_*_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.