:icon-check-circle:  Upgrade to 43

Pagy version 43 is a complete redesign of the legacy code. Its improvements make pagination a lot simpler and powerful, but require a quite different way to use it.

!!!success Follow this guide to upgrade your app in just a few minutes. Cherry-pick only what applies to your app: you can safely skip all the rest. !!!

Steps

Replace the pagy.rb config file...

• Rename your pagy.rb initializer as pagy-old.rb
• Add the new pagy.rb initializer in its place
• Cut/remove the Pagy::DEFAULT[...] lines from pagy-old.rb and paste/add them to pagy.rb
• Replace all the Pagy::DEFAULT[...] entries with Pagy::OPTIONS[...] in pagy.rb

In the next steps we will use the pagy-old.rb as the blueprint to guide most of the changes, and we will edit the new pagy.rb as needed.

Remove your used extras...

The new version doesn't use the extras anymore. They got integrated in the core code, and a few have been discontinued.

• Search any active require 'pagy/extras/* in the pagy-old.rb file...
• When you find one, follow the specific section below to upgrade your code.
• As you proceed, remove each entry from the pagy-old.rb.

==- Extras

::: ==- array

{.compact}

==- arel

{.compact}

==- pagy

• All the old helpers are now @pagy instance methods with more explicit names.

{.compact}

==- bootstrap

• All the old helpers are now @pagy instance methods with more explicit names.

{.compact}

• FYI: The redundant pagy-bootstrap class has been removed from the input_nav_js body.

==- bulma

• All the old helpers are now @pagy instance methods with more explicit names.

{.compact}

• FYI: The is-centered CSS class has been removed.
• FYI: The previous/next links have been moved at the beginning and end of the pagination.

==- countless

{.compact}

==- calendar

{.compact}

• If your pagy-old.rb file contains any localization configuration, then uncomment and customize the following line in the pagy.rb initializer: Pagy::Calendar.localize_with_rails_i18n_gem(*your_locales).
  • Note: In non-Rails applications, calendar localization requires adding rails-i18n to your Gemfile.
• Remove any existing Pagy::Calendar::*::DEFAULT. Pass the options to each unit when you paginate.

==- elasticsearch_rails

• Active and passive modes are now handled by the same pagy method:

{.compact}

• Customization of the pagy_search method name has been discontinued:
  • Remove any existing :elasticsearch_rails_pagy_search variable from your code.
  • Replace your custom method name with the standard pagy_search method.

==- meilisearch

• Active and passive modes are now handled by the same pagy method:

{.compact}

• Customization of the pagy_search method name has been discontinued:
  • Remove any existing :meilisearch_pagy_search variable from your code.
  • Replace your custom method name with the standard pagy_search method.

==- searchkick

• Active and passive modes are now handled by the same pagy method:

{.compact}

• Customization of the pagy_search method name has been discontinued:
  • Remove any existing :searchkick_pagy_search variable from your code.
  • Replace your custom method name with the standard pagy_search method.

==- headers

{.compact}

• Notice that the :limit header default is now 'page-limit (it was 'page-items').
  • Set Pagy::OPTIONS[:headers_map] = { limit: 'page-items', ... } to preserve your current API, if it relays on old default values.

==- jsonapi

{.compact}

• Notice that the nil links are now removed as the JSON:API specifications require.
• IMPORTANT: Enable the feature by explicitly setting the jsonapi: true option (in the initializer or pagy method).

==- keyset

{.compact}

• Replace any existing :jsonify_keyset_attributes with :pre_serialize.
  • The lambda receives the same keyset_attributes argument, but it must modify the specific values directly. The lambda's return value is ignored. For example: ->(attrs) { attrs[:created_at] = attrs[:created_at].strftime('%F %T.%6N') }.

==- limit

{.compact}

• Enable the feature by setting max_limit: allowed_max_limit option (in the initializer or pagy method).

==- metadata

{.compact}

==- overflow

• The Pagy::OverflowError has been replaced by the Pagy::RangeError; however, it is no longer raised by default.
• Pagy rescues the Pagy::RangeError and serves an empty page by default.
  • Now, Pagy behaves the same as it did before when requiring the overflow extra and using its default settings.
• The legacy pagy.overflow? is now the pagy.in_range? method, which checks/returns the opposite state/boolean.
• The overflow: :last_page behavior has been discontinued because it provides nearly no benefit:
  • Why there is little benefit in serving the last page?
    • The navigation bar for an out-of-range request is rendered identically to that of the last page.
    • The only difference is that there are no records/results to display.
    • The "previous page" button points to the last page, so if users truly want to see the last page results (which they have likely already seen), they can simply click the link.
• Summary for keeping the same behavior:
  • The :overflow variable is not used anymore.
  • If you did not use the extra (i.e., Pagy raised errors), set raise_range_error: true.
  • If you used overflow: :empty_page or just required the overflow extra, simply remove it (this is now the default behavior).
  • If you used overflow: :last_page and still want this behavior despite the reasons above, see this How To Example.

==- standalone

• Replace the :url variable with the :request hash option. For example:

  rubyCopy

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

==- i18n

• If absolutely necessary, uncomment or add this line to your initializer: Pagy.translate_with_the_slower_i18n_gem!.

==- gearbox (discontinued)

• Due to extensive overwriting for minimal benefit, you can safely remove this feature from your app without noticeable impact. Remove all /gearbox/ related code.

==- size (discontinued)

• Pagination bars similar to WillPaginate and Kaminari are not good for a lot of reasons. If still required, adapt the legacy file from a previous commit.

==- trim (discontinued)

• It was mostly useless and half-baked, causing many complications in both the Ruby and JavaScript code for no significant benefit.
• Use an appropriate approach to address your requirement, such as utilizing URL rewriting at the HTTP server level.

:::

Update the API...

==- Search and replace

{.compact}

==- Replace the :params variable...

Use the :querify option, which is a lambda that can modify the string-keyed params hash at will. It is a bit more verbose, but it's more powerful and low-level. It solves an incompatibility with the old high-level :params hash/lambda and improves performance. It is part of the URL Options group that gives you full and efficient control over the URL composition. For example:

# Old symbol-keyed, high-level hash variable
params: { a: 1, b: 2 }
# New string-keyed, low-level, direct modification of the params hash
querify: ->(p) { p.merge!('a' => 1, 'b' => 2) }
# It also allows to do things like:
querify = ->(p) { p.except!('not_useful').merge!('custom' => 'useful') }

==- Replace the *prev* abbreviated naming

Use *previous* in all the options, accessors, methods, etc.

===

Finalize the upgrade...

==- Javascript

If your pagy-old.rb contains any JavaScript setup, it should still work, so you can move it to the pagy.rb file, however, for apps with builders, consider using the new Pagy.sync and removing all the old entries from your JavaScript config files.

==- Stylesheets

The CSS for the default pagy helpers have new selectors and variables. See the new Stylesheets to interactively update your custom CSS.

!!!success CSS Frameworks Supported CSS frameworks (like Bootstrap and Bulma) don't require any change. !!!

==- Pagy::I18n and Locale Files

{{ include "snippets/mini-step" step: "•1" }} If your pagy-old.rb contains the Pagy::I18n setup, and the setup includes some custom dictionary file, then uncomment and set up the relevant Pagy::I18n lookup section in the pagy.rb file. (See the I18n docs for details)

{{ include "snippets/mini-step" step: "•2" }} Update your custom dictionary files (if any) to the new dictionary structure, or they won't work correctly.

{{ include "snippets/mini-step" step: "•3" }} Remove all the I18n code from the pagy-old.rb. All the locales are autoloaded when your app uses them.

==- Overriding

• Overriding methods in controllers/helpers is not possible or discouraged.
• The cleanest approach for local overriding is via Ruby refinements or the initializer for global override.
• Check the How To Override Pagy Methods.
• If your pagy-old.rb contains overridden methods, copy the methods over to the pagy.rb initializer, however, consider that:
  • Internal Pagy protected methods have been extensively refactored, likely renamed, and occasionally removed.
  • You should reconcile internal overrides by reviewing the updated Pagy codebase.

You may want also to check these internal renaming:

{.compact}

==- Delete the pagy-old.rb file

At this point, there should be no more code in the pagy-old.rb.

===

{{ include "snippets/ask-for-support" }}

!!!warning Please report any issue with this guide by opening a New Docs Issue. !!!