#

# 💚 Paginators

# `pagy` method

The pagy method starts every pagination.

Include the Pagy::Method where you are going to use it (usually in ApplicationContoller):

include Pagy::Method

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

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

:offset, :keyset, etc. are symbols identifying the paginator to use, i.e. the internal method handling that type of pagination.
@pagy is the pagination istance. It provides methods for every UI components and helpers to use in your code.
@records are the records belonging to the requested page

# Paginators

The paginators are internal methods that provide different type of pagination for different types of collections, with a common API. They are passed to the pagy method by their symbolic name. (e.g, :offset, :keyset, countless, etc.)

Avoid instantiating Pagy classes directly

Instantiate implementing 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

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).
requestable_limit: 1_000
- Allow the client to set the :limit in the request query, up to 1_000 in the example

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',
                    queried:  { 'param1' => 1234 }, # The string-keyed hash queried from the request
                    cookie:   'xyz' }               # The 'pagy' cookie, only for keynav  

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

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 passed to the constructor.
- 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 (or sometimes 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)

#