#

# 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

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.

:offset
:countless
:keynav_js
:keyset
:calendar
:elasticsearch_rails
:meilisearch
:searchkick

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 query hash).
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: custom_request

Set this hash only in non-rack environments or when instructed by the docs. (It is set automatically from the request). For example:

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

Common URL options for all paginators and `@pagy` helpers

These options control give you full control over the URL composition.

absolute: true
- Makes the URL absolute.
fragment: '#...'
- URL fragment string. (It must include the leding "#"!)
jsonapi: true
- Enables JSON:API-compliant URLs, with nested query string (e.g., ?page[number]=2&page[size]=100)
limit_key: 'custom_limit'
- Set it to change the key string used for the :limit in URLs (default 'limit').
page_key: 'custom_page'
- Set it to change the key string used for the :page in URLs (default 'page').
path: '/custom_path'
- Overrides the request path in pagination URLs. Use the path only (not the absolute URL). (see Override the request path)
querify: tweak
- Set it to a Lambda to directly edit the passed string-keyed query hash itself. Its result is ignored.
```
tweak = ->(q) { q.except!('not_useful').merge!('custom' => 'useful') }
```

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)

warning

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.

success Ensure the PostgreSQL collection is ordered!

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

#