© 2017-2019 Domizio DemichelisMIT License

➡ Chat Support on Gitter ➡

Overflow Extra

This extra allows for easy handling of overflowing pages. It internally rescues from the Pagy::OverflowError offering a few different ready to use modes, quite useful for UIs and/or APIs. It works with Pagy or Pagy::Countless instances.

Synopsis

See extras for general usage info.

In the pagy.rb initializer:

require 'pagy/extras/overflow'

# default :empty_page (other options :last_page and :exception )
Pagy::VARS[:overflow] = :last_page

# OR
require 'pagy/countless'
require 'pagy/extras/overflow'

# default :empty_page (other option :exception )
Pagy::VARS[:overflow] = :exception

Files

Variables

Variable Description Default
:overflow the modes in case of overflowing page (:last_page, :empty_page or :exception) :empty_page

As usual, depending on the scope of the customization, you have a couple of options to set the variables:

# globally
Pagy::VARS[:overflow] = :empty_page

# or for a single instance
@pagy, @records = pagy(scope, overflow: :empty_page)

Modes

These are the modes accepted by the :overflow variable:

:empty_page

This is the default mode; it will paginate the actual requested page, which - being overflowing - is empty. It is useful with APIs, where the client expects an empty set of results in order to stop requesting further pages.

Example for Pagy instance:

# no exception passing an overflowing page
pagy = Pagy.new(count: 100, page: 100)

pagy.overflow?          #=> true
pagy.vars[:page]        #=> 100 (requested page)
pagy.page               #=> 100 (actual empty page)
pagy.last == pagy.page  #=> false
pagy.last               #=> 5
pagy.last == pagy.prev  #=> true (the prev page is the last page relative to the overflowing page)
pagy.next               #=> nil
pagy.offset             #=> 0
pagy.from               #=> 0
pagy.to                 #=> 0
pagy.series             #=>  [1, 2, 3, 4, 5] (no string, so no current page highlighted in the UI)

Example for Pagy::Countless instance:

require 'pagy/countless'
require 'pagy/extras/overflow'

pagy = Pagy::Countless.new(count: 100, page: 100).finalize(0)

pagy.overflow?          #=> true
pagy.vars[:page]        #=> 100 (requested page)
pagy.page               #=> 100 (actual empty page)
pagy.last == pagy.page  #=> false
pagy.last               #=> nil
pagy.last == pagy.prev  #=> true (but nil)
pagy.next               #=> nil
pagy.offset             #=> 0
pagy.from               #=> 0
pagy.to                 #=> 0
pagy.series             #=>  [] (no pages)

:last_page

Notice: Not available for Pagy::Countless instances since for countless instances the last page is not known.

It is useful in apps with an UI, in order to avoid to redirect to the last page.

Regardless the overflowing page requested, Pagy will set the page to the last page and paginate exactly as if the last page has been requested. For example:

pagy = Pagy.new(count: 100, page: 100, overflow: :last_page)

pagy.overflow?          #=> true
pagy.vars[:page]        #=> 100 (requested page)
pagy.page               #=> 5   (current/last page)
pagy.last == pagy.page  #=> true

:exception

This mode raises the Pagy::OverflowError as usual, so you can rescue from and implement your own custom mode even in presence of this extra.

begin
  pagy = Pagy.new(count: 100, page: 100, overflow: :exception)
rescue Pagy::OverflowError => e
  ...
end

Methods

overflow?

Use this method in order to know if the requested page is overflowing. The original requested page is available as pagy.vars[:page] (useful when used with the :last_page mode, in case you want to give some feedback about the rescue to the user/client).