#

# pagy(:✳) Paginators

# The `pagy` Method

The pagy method provides a common interface to all paginators. Include it where you are going to paginate a collection (usually in ApplicationController):

include Pagy::Method

You can use it to paginate ANY collection, with ANY technique. For example:

@pagy, @records = pagy(:offset, collection, **options)
@pagy, @records = pagy(:keyset, set, **options)
@pagy, @records = pagy(...)

:offset, :keyset, etc. are symbols identifying the paginator. They implement the specific pagination.
@pagy is the pagination istance. It provides all the instance helper methods to use in your code.
@records are the records belonging to the requested page.

The pagy method expects to find the rack request at self.request, however, you can also use pagy outside controllers or views, or even with a non-rack app.

# Paginators

Read also the Choose Wisely Guide to ensure good performance and smooth workflow.

The paginators are symbolic names of different pagination types/contexts (e.g., :offset, :keyset, countless, etc.). You pass the name to the pagy method and pagy will internally instantiate and handle the appropriate paginator class.

Avoid instantiating Pagy classes directly

Instantiate paginator classes only if the documentation explicitly suggests it.

Paginators and classes are autoloaded only if used!

Unused code consumes no memory.

Paginators can inherit and override options

See Options

Common Options for Paginators

Individual paginators may offer additional options, which are documented with the paginator itself.

limit: 10
- Specifies the number of items per page (default: 20)
max_pages: 500
- Restricts pagination to only :max_pages. (Ignored by Pagy::Calendar::* unit instances)
page: 3
- Set it only to force the current :page. (It is set automatically from the request param).
client_max_limit: 1_000
- Set the maximum :limit that the client is allowed to request. Higher requested :limits are silently capped. (If falsey, the client cannot request the :limit)

request: rake_request || hash

Pagy tries to find the Rake::Request at self.request. Set it only when it's not directly available in your code (e.g., Hanami, standalone app, test,...). For example:

hash_request = { base_url: 'http://www.example.com',
                 path:     '/path',
                 params:   { 'param1' => 1234 }, # The string-keyed params hash from the request
                 cookie:   'xyz' }               # The 'pagy' cookie, only for keynav  

See URL Options

Common Readers for Paginators

Individual paginators may offer additional readers, which are documented with the paginator itself.

page
- The current page
limit
- The items per page
options
- The options of the object
next
- The next page

Common Exceptions for Paginators

Individual paginators may raise specific exceptions, which are documented with the paginator itself.

Pagy::OptionError
- A subclass of ArgumentError that offers information to rescue invalid options.
- For example: rescue Pagy::OptionError => e
  - e.pagy the pagy object
  - e.option the offending option symbol (e.g. :page)
  - e.value the value of the offending option (e.g. -3)

# Records may repeat in different pages be missing

Don't Paginate Unordered PostgreSQL Collections!

@pagy, @records = pagy(:offset, unordered)

# behind the scenes, pagy selects the page of records with: 
unordered.offset(pagy.offset).limit(pagy.limit)

Citation: PostgreSQL Documentation

When using LIMIT, always include an ORDER BY clause to constrain the result rows into a unique order. Otherwise, the subset of rows retrieved may be unpredictable.

Ensure the PostgreSQL collection is ordered!

# Results will be consistent and predictable with #order
ordered         = unordered.order(:id)
@pagy, @records = pagy_offset(ordered)

#