# Pagy::Frontend

In 
Core

This module provides a few methods to deal with the navigation aspect of the pagination.

You will usually include it in some helper module, making its methods available (and overridable) in your views. (source)

You can extend this module with a few more nav helpers (see the extras doc for more details)

# Synopsis

View Helper
include Pagy::Frontend

# optional overriding of some sub-method
def pagy_nav(...)
   ...
end
View
<%== pagy_nav(@pagy, **vars) %>
<%== pagy_info(@pagy, **vars) %>

# Methods

All the methods in this module are prefixed with the "pagy_" string in order to avoid any possible conflict with your own methods when you include the module in your helper. The methods prefixed with the "pagy_get_" string are sub-methods/getter methods that are intended to be overridden and not used directly.

Please, keep in mind that overriding any method is very easy with Pagy. Indeed you can do it right where you are using it: no need of monkey-patching or tricky gimmickry.

This method takes the Pagy object and returns the HTML string with the pagination links, which are wrapped in a nav tag and are ready to use in your view. For example:

View
<%== pagy_nav(@pagy, **vars) %>

The method accepts also a few optional keyword arguments variables:

  • :pagy_id: the id HTML attribute to the nav tag (omitted by default)
  • :link_extra: the verbatim string added to the a tag (e.g. 'data-remote="true"')
  • :nav_aria_label: an already pluralized string for the aria-label attribute of the nav, that will be used in place of the default pagy.aria_label.nav
  • :nav_i18n_key: the i18n dictionary key to lookup the default pagy.aria_label.nav pluralized value (ignored if nav_aria_label is defined)
  • :size which use the passed size Array instead of the :size variable of the instance

See also ARIA Attributes.

This method provides the info about the content of the current pagination. For example:

<%== pagy_info(@pagy, **vars) %>

Will produce something like:

Displaying items 476-500 of 1000 in total

The method accepts also a few optional keyword arguments variables:

  • :pagy_id: the id HTML attribute to the span tag wrapping the info
  • :item_name an already pluralized string that will be used in place of the default item/items
  • :item_i18n_key the key to lookup in a dictionary

Notice the :item_i18n_key can be passed also to the constructor or be a global variable (i.e. Pagy::DEFAULT[:item_i18n_key]

View
<%== pagy_info(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %>
<%== pagy_info(@pagy, item_i18n_key: 'activerecord.model.product' %>

Displaying Products 476-500 of 1000 in total

(see Customizing the item name)

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.

See also How to customize the URL and How to customize the params.

This method is called internally to get a very specialized and fast proc that produce the HTML links for the pages.

For standard usage you may just need to read How to customize the link attributes, for advanced usage see below.

# Advanced Usage

You need this section only if you are going to override a pagy_nav* helper AND you need to customize the HTML attributes of the link tags.

This method returns a specialized proc that you call to produce the page links. The reason it is a two steps process instead of a single method call is performance. Indeed the method calls the potentially expensive pagy_url_for only once and generates the proc, then calling the proc will just interpolates the strings passed to it.

Here is how you should use it: in your helper call the method to get the proc (just once):

link = pagy_link_proc( pagy [, extra_attributes_string ] )

Then call the "link" proc to get the links (multiple times):

link.call( page_number [, text [, extra_attributes_string ] ] )

# Extra attribute strings

If you need to add some HTML attribute to the page links, you can pass some extra attribute string at many levels, depending on the scope you want your attributes to be added.

  1. For all pagy objects: set the global variable :link_extra:

    pagy.rb (initializer)
    Pagy::DEFAULT[:link_extra] = 'data-remote="true"'
    View
    link = pagy_link_proc(pagy)
    link.call(2)
    #=> <a href="...?page=2" data-remote="true">2</a>
  2. For one Pagy object: pass the :link_extra variable to a Pagy constructor (Pagy.new or pagy controller method):

    Controller
    @pagy, @records = pagy(my_scope, link_extra: 'data-remote="true"')
  3. For all the link.call: pass an extra attributes string to the pagy_link_proc:

    View
    link = pagy_link_proc(pagy, 'class="page-link"')
    link.call(2)
    #=> <a href="...?page=2" data-remote="true" class="page-link">2</a>
    link.call(3)
    #=> <a href="...?page=3" data-remote="true" class="page-link">3</a>
  4. For a single link.call: pass an extra attributes string when you call the proc:

    View
    link.call(page_number, 'aria-label="my-label"')
    #=> <a href="...?page=2" data-remote="true" class="page-link" aria-label="my-label">2</a>

# CAVEATS

We use only strings for performance, so the attribute strings get concatenated level after level, but not merged!

This method is similar to the I18n.t and its equivalent rails t helper. It is called internally from the helpers in order to get the interpolated strings out of a YAML dictionary file. (see the Pagy::I18n doc for details)