docs/CHANGELOG_LEGACY.md
foundation, materialize, semantic and uikit CSS extras have been removed:
(See the reasons)pagy.js: use pagy.min.jspagy-module.js: use pagy.mjspagy-dev.js: use the pagy.min.jswith the pagy.min.js.mappagy-module.d.ts: use pagy.d.ts:size (e.g. size: [1, 4, 4, 1]) that generates the classic bar is not supported anymore: use the
:size set to an integer with the ends: true variable (which are the default since 8.4.6). If a legacy bar remains REALLY a
requirement, add require 'pagy/extras/size to your pagy.rb initalizer. (See the
size extra)We used items for too many things that confused even maintainers. The "items" are now referencing only the records/elements
fetched from a collection (plural entity), so they are kept as before (e.g. pagy_*get_items methods). The "number of items" (
singular entity), are now unmistakably referenced as the limit everywhere (code, API, files, extras, docs, etc.). The logic
didn't change so you have just to globally search 'items' and replace with limit and you should be done... or use the detailed
table below:
| Type | Search | Replace |
|---|---|---|
| Pagy Variable | :items | :limit |
| Extra Path | pagy/extras/items | pagy/extras/limit |
| Extra Variable | :items_param | :limit_param |
| Default URL param | items | limit |
| Extra Variable | :items_extra | :limit_extra |
| Extra Variable | :max_items | :limit_max (now inverted) |
| Extra Method | pagy_items_selector_js | pagy_limit_selector_js |
| Extra Variable | :headers[:items] | :headers[limit] |
DEFAULT[:anchor_string] was useless and has been dropped.:anchor_stringand the :fragment are not instance variables anymore, but keyword arguments for all the helpers, because
it is frontend code (see the discussion). Instead of passing them to the
pagy* method in the controller, pass it to any pagy_*nav method in the view.wrong number of arguments (given 1, expected 0) (ArgumentError), just use a double splat **.next_a "aria-label" (#700)pagy_id:, replace with id:nav_aria_label:, replace witharia_label:nav_i18n_key has been removed: pass the interpolated/pluralized value as the aria_label: argumentitem_i18n_key has been removed: pass the interpolated/pluralized value as the item_name: argumentlink_extra: has been removed: its cumulative mechanism was confusing and error prone. The :anchor_string pagy
variable substitutes it, however it's not an helper argument anymore, so you can assign it as the DEFAULT[:anchor_string]
and/or pass it as any other pagy variable at object construction. (
See customize the link attributes)navs and support extras has been merged into the new pagy extra.
Search for "extras/navs" and
"extras/support" and replace with "extras/pagy" (remove the duplicate if you used both)"extras/frontend_helpers" has been renamed to "extras/js_tools"lib to
the gem root. Notice that the correct setup in package json was still wrongly wrapped in the gem dir for 8.0.0-8.0.1, and it
has finally been fixed in 8.0.2 (sorry for that):
build: "NODE_PATH=\"$(bundle show 'pagy')/gem/javascripts\" <your original command>"build: "NODE_PATH=\"$(bundle show 'pagy')/javascripts\" <your original command>"pagy_nav and pagy_nav_js helpers output a series of a tags inside a wrapper nav tag (nothing else)href attributes. (They also have the role="link"
and aria-disabled="true" attributes)current and gap classes are assigned to the specific a tags"pagy-nav" > "pagy nav""pagy-bootstrap-nav-js" > "pagy-bootstrap series-nav-js"active class of the *nav/*nav_js links as been renamed as currentdisabled, prev, next and pagy-combo-input link classes have been removed (see
the stylesheets for details)rel="prev" and rel="next" attributes have been dropped (they are obsolete)<label>/</label> and <b>/</b> wrappers in the dictionary files have been removedpagy_link_proc method (only used internally or in your custom overriding) has been renamed to pagy_anchor and it works
slightly differently:
link_extra: key argument has been removed
extra positional argument of the returned lambda has been removedclasses: and aria_label: keyword arguments have been added to the returned lambdanav_aria_label_attr method has been renamed as nav_aria_labelprev_aria_label_attr and next_aria_label_attr methods have been removedgap in the nav bars is a disabled anchor element (a tag without a href attribute)pagy_prev_html and pagy_next_html have been renamed as pagy_prev_a and pagy_next_apagy_prev_link_tag and pagy_next_link_tag have been renamed as pagy_prev_link and pagy_next_link*combo_nav_js and pagy_items_selector_js helpers use a more efficient codesrc/pagy.ts and relative built javascript files have been adapted to the above changes*combo-nav_js of the framework extras use simpler structure and improve the look and feel consistently with their
respective frameworksclasses:
argument to a few components, when the framework allows it.pagy executable.FrontendHelpers > JSToolspagy.prev and pagy.next (#649)pagy_nav, pagy_nav_js and .pagy-combo-inputpagy_tailwind_app.ru (#646):i18n_key > :item_i18n_keysupport extra
pagy_prev_link to pagy_prev_html to avoid confusion with pagy_prev_link_tagpagy_next_link to pagy_next_html to avoid confusion with pagy_next_link_tagheaders extra produces all lowercase headers, regardless how you set
them see rack issue:escaped_html option from pagy_url_for (only breaking if you override the method or use the option directly)nav entry has been flattened: pagy.nav.* entries are now pagy.*:
'.nav.' and replace them with '.''nav:' line and unindent its blockaria-label have been added: you may want to add/use them to your custom helper/templates/dictionaries
for ARIA compliance.
pagy.aria_label.nav Pluralized entry: used in the nav elementpagy.aria_label.prev, pagy.aria_label.next Single entry: used in the prev/next a link elementsPagy::DEFAULT[:size] variable defaults from [1, 4, 4, 1] to 7. You can explicitly set/restore it in the
initializer, if your app was relying on it.:size defaults in Calendar Unit subclasses. You can explicitly set it in the initializer, if your app was
relying on it.
Pagy::Calendar::Day::DEFAULT[:size] 31Pagy::Calendar::Month::DEFAULT[:size] 12Pagy::Calendar::Quarter::DEFAULT[:size] 4Pagy::Calendar::Year::DEFAULT[:size] 10format defaults in Calendar Unit subclasses. You can explicitly set it in the initializer, if your app was
relying on it.
Pagy::Calendar::Day::DEFAULT[:format] from '%Y-%m-%d' to '%d'Pagy::Calendar::Month::DEFAULT[:format] from '%Y-%m' to '%b'Pagy::Calendar::Quartr::DEFAULT[:format] from '%Y-Q%q' to 'Q%q'"Prev" and "Next" is now used for the aria-label (actually as "Previous" and "Next") and has been
replaced in the UI as < and >. You can edit the dictionary entries pagy.prev and pagy.next if you want to revert it to
the previous default (‹ Prev and Next ›)pagy_nav and pagy_nav_js has been changed from simple text (e.g. 5) to a
disabled link (e.g. <a role="link" aria-disabled="true" aria-current="page">5</a>). That affects your CSS rules and
the old tailwind examples targeting the page links, now overreaching the current page.
a rules with narrower a[href] selectors however if you use
Tailwind we recommend to use the improved tailwind style, that you can
adapt in no time to anything you need.pagy_nav and pagy_nav_js have been removedpagy-combo-nav-js .pagy-combo-input internal element x-margins have been removedYou should not have used any of the private methods, but if you did so, you will get a NoMethodError
(undefined method...) very easy to fix by simply renaming, because there are no changes in the logic.
:count_args variable passed to the collection.count(...) statement (avoids overriding of pagy-gets-vars and
expands count capabilities):size)Removed support for the deprecation of 5.0:
pagy_massage_params method: use the :params variable set to a lambda Proc that does the same (but per instance). See How to customize the params.activesupport core dependency is now an optional requirement if you use the calendar: you must add gem 'activesuport' to your Gemfile if your app doesn't use rails.Time objects in the :period variable: use only ActiveSupport::TimeWithZone objects.:offset variable used by the Pagy::Calendar::Week: set the Date.beginning_of_week variable to the symbol of the first day of the week (e.g. Date.beginning_of_week = :sunday). Notice the default is :monday consistently with the ISO-8601 standard (and Rails).Pagy::DEFAULT[:elasticsearch_rails_search_method]: use Pagy::DEFAULT[:elasticsearch_rails_pagy_search] instead.Pagy::DEFAULT[:searchkick_search_method]: use Pagy::DEFAULT[:searchkick_pagy_search] instead.Pagy::DEFAULT[:meilisearch_search_method]: use Pagy::DEFAULT[:meilisearch_pagy_search] instead.pagy_url_for method ensure you add the extra parameters required..includes (closes #378)pagy_headers method in the headers extraPagy::Calendar::* classes require ActiveSupport (temporarily added activesupport dependency that will e replaced in 6.0):period items can be Time or TimeWithZone objects (which work across DST ranges):offset to set the first weekday, in favour of Date.beginning_of_week (default to :monday)version and init()Pagy::DEFAULT to class-specific Pagy::Calendar::*::DEFAULT:minmax -> :period:time_order -> :order:week_offset -> :offset:*_format -> :format#utc_from -> #from (use from.utc if you need it)#utc_to -> #to (use to.utc if you need it):skip key in the #pagy_calendar conf, now renamed:
:skip -> :active#pagy_calendar_minmax -> #pagy_calendar_period#pagy_calendar_filtered -> #pagy_calendar_filterpagy_calendar_app.ru:desc orderPagy::Calendar and calendar extra:
*nav_js to Calendarpagy_massage_params: use the :params variable set to a Proc that does the same, but per instancePagy 4 dropped the compatibility for old ruby versions >2.5 and started to refactor the code using more modern syntax and paradigms and better performance. It deprecated the legacy ones, printing deprecation warnings and upgrading instruction in the log, but still supporting its legacy API. Pagy 5.0.0 cleans up and removes all that transitional support code.
The changes for upgrading your app cannot be fixed with simple search and replace, but fear not! Fixing them should just take a few minutes with the following steps:
FYI: Here is the list of the deprecations that are not supported anymore:
Pagy::VARS[:anchor] is now Pagy::DEFAULT[:fragment]pagy_url_for(page, pagy) is now inverted: pagy_url_for(pagy, page)The following optional positional arguments are passed with keywords arguments in all the pagy helpers:
id html attribute string with the id keywordurl|absolute flag with the absolute keyworditem_name string with the item_name keywordextra|link_extra string with the link_extra keywordtext string with the text keywordThere are a few renaming that have not been deprecated in previous versions because they are extremely easy to fix with simple search and replace (while implementing deprecations would have been detrimental to performance and complex for no reason)
A few elements have been renamed: you code may or may not contain them. Just search and replace the following strings:
Pagy::VARS to Pagy::DEFAULTenable_items_extra to items_extraenable_trim_extra to trim_extraPagy::Helpers to Pagy::UrlHelperspagy_get_params to pagy_massage_paramsThe items accessor does not adjust for the actual items in the last page anymore. This should not affect normal usage, so you can ignore this change unless you build something on that assumption.
If your code is relying on the actual number of items in the page, then just replace @pagy.items with @pagy.in wherever you meant that.
FYI: The @pagy.items is now always equal to @pagy.vars[:items] (i.e. the requested items), while the @pagy.in returns the actual items in the page (which could be less than the items when the page is the last page)
rematch gem@pagy) to all the helpers is deprecated and it will be supported only until pagy 5.0pagy*_nav(@pagy, id: 'my-id', link-extra: '...')pagy*_nav_js(@pagy, id: 'my-id', link-extra: '...', steps: {...})pagy*_combo_nav_js(@pagy, id: 'my-id', link-extra: '...')pagy_items_selector_js(pagy, id: 'my-id', item_name: '...', i18n_key: '...', link_extra: '...')pagy_info(@pagy, id: 'my-id', item_name: '...', i18n_key: '...')pagy_prev_link(@pagy, text: '...', link_extra: '...')pagy_next_link(@pagy, text: '...', link_extra: '...')pagy_link_proc(@pagy, link_extra: '...')pagy_url_for(pagy, page, absolute: nil) (notice the inverted page/pagy order with the legacypagy_url_for(page, pagy, url=nil)):anchor variable in favor of :fragmentPagy::Frontend::I18n conflicting with rthe I18n gem namespace after inclusion and safer renaming of other modulesPagy::Search as Pagy::Searchkick or Pagy::ElasticsearchRailsPagy::Frontend::MARK > Pagy::PAGE_PLACEHOLDERNamespacing of all exceptions, still backward compatible with legacy rescues
zh-cn and zh-hk were named incorrectly. They have been properly renamed as zh-CN and zh-HK. If you used them, you should update the Pagy::I18n.load statement.:item_path variable has been renamed as :i18n_key: you should search and replace it.The javascript-powered helpers (pagy*_responsive_nav, pagy*_compact_nav and items_selector) have been renamed in order to be simpler and more descriptive of their arguments, features and requirements. They have been improved internally, but you need only to search and replace because their usage has not been changed.
| v2.0+ | v3.0+ |
|---|---|
pagy_bootstrap_responsive_nav :breakpoints | pagy_bootstrap_nav_js :steps |
pagy_bootstrap_compact_nav | pagy_bootstrap_combo_nav_js |
| v2.0+ | v3.0+ |
|---|---|
pagy_bulma_responsive_nav :breakpoints | pagy_bulma_nav_js :steps |
pagy_bulma_compact_nav | pagy_bulma_combo_nav_js |
| v2.0+ | v3.0+ |
|---|---|
pagy_foundation_responsive_nav :breakpoints | pagy_foundation_nav_js :steps |
pagy_foundation_compact_nav | pagy_foundation_combo_nav_js |
| v2.0+ | v3.0+ |
|---|---|
pagy_materialize_responsive_nav :breakpoints | pagy_materialize_nav_js :steps |
pagy_materialize_compact_nav | pagy_materialize_combo_nav_js |
| v2.0+ | v3.0+ |
|---|---|
pagy_plain_nav (pagy_nav alias) | - removed - |
pagy_plain_responsive_nav :breakpoints | pagy_nav_js :steps |
pagy_plain_compact_nav | pagy_combo_nav_js |
require "pagy/extras/plain" | require "pagy/extras/navs" |
| v2.0+ | v3.0+ |
|---|---|
pagy_semantic_responsive_nav :breakpoints | pagy_semantic_nav_js :steps |
pagy_semantic_compact_nav | pagy_semantic_combo_nav_js |
Pagy::Vars[:breakpoints] has been renamed as Pagy::VARS[:steps]
items_selector has been renamed as items_selector_js. It is also possible to use the i18n_key variable to customize the item name.
Notice: You can skip the following sections if you did not override any nav helper.
The nav CSS classes follow the same renaming rules of the helper methods:
| v2.0+ | v3.0+ |
|---|---|
pagy-bootstrap-responsive-nav | pagy-bootstrap-nav-js |
pagy-bootstrap-compact-nav | pagy-bootstrap-combo-nav-js |
pagy-bulma-responsive-nav | pagy-bulma-nav-js |
pagy-bulma-compact-nav | pagy-bulma-combo-nav-js |
pagy-foundation-responsive-nav | pagy-foundation-nav-js |
pagy-foundation-compact-nav | pagy-foundation-combo-nav-js |
pagy-materialize-responsive-nav | pagy-materialize-nav-js |
pagy-materialize-compact-nav | pagy-materialize-combo-nav-js |
pagy-plain-responsive-nav | pagy-nav-js |
pagy-plain-compact-nav | pagy-combo-nav-js |
pagy-semantic-responsive-nav | pagy-semantic-nav-js |
pagy-semantic-compact-nav | pagy-semantic-combo-nav-js |
Renamed first param passed to the pagy_json_tag:
| v2.0+ | v3.0+ |
|---|---|
:responsive | :nav |
:compact | :combo_nav |
:items | :items_selector |
| v2.0+ | v3.0+ |
|---|---|
Pagy.responsive | Pagy.nav |
Pagy.compact | Pagy.combo_nav |
Pagy.items | Pagy.items_selector |
Dropped pagy_serialized, pagy_apply_init_tag and PagyInit javascript namespace. They were too basic to be useful as support for javascript powered custom component.
pagy_url_for returning duplicated paramsThe following methods have been renamed. You only need to search and replace, because the functionality has not been changed.
| Legacy Name | New Name |
|---|---|
pagy_nav_bootstrap | pagy_bootstrap_nav |
pagy_nav_compact_bootstrap | pagy_bootstrap_compact_nav |
pagy_nav_responsive_bootstrap | pagy_bootstrap_responsive_nav |
| Legacy Name | New Name |
|---|---|
pagy_nav_bulma | pagy_bulma_nav |
pagy_nav_compact_bulma | pagy_bulma_compact_nav |
pagy_nav_responsive_bulma | pagy_bulma_responsive_nav |
| Legacy Name | New Name |
|---|---|
pagy_nav_foundation | pagy_foundation_nav |
pagy_nav_compact_foundation | pagy_foundation_compact_nav |
pagy_nav_responsive_foundation | pagy_foundation_responsive_nav |
| Legacy Name | New Name |
|---|---|
pagy_nav_materialize | pagy_materialize_nav |
pagy_nav_compact_materialize | pagy_materialize_compact_nav |
pagy_nav_responsive_materialize | pagy_materialize_responsive_nav |
| Legacy Name | New Name |
|---|---|
pagy_plain_nav (pagy_nav alias) | |
pagy_nav_compact | pagy_plain_compact_nav |
pagy_nav_responsive | pagy_plain_responsive_nav |
require "pagy/extras/navs" | require "pagy/extras/plain" |
| Legacy Name | New Name |
|---|---|
pagy_nav_semantic | pagy_semantic_nav |
pagy_nav_compact_semantic | pagy_semantic_compact_nav |
pagy_nav_responsive_semantic | pagy_semantic_responsive_nav |
Notice: You can skip this section if you did not override any nav helper.
The nav CSS classes follow the same renaming rules of the helper methods. For example:
pagy-nav-responsive-bootstrap is now pagy-bootstrap-responsive-nav
All the JSON tag classes are now pagy-json, and the qualifier of the json (e.g. compact, responsive, ...) is now passed as the first argument in the array content. For example:
<script type="application/json" class="pagy-responsive-json">["#{id}", ...
is now
<script type="application/json" class="pagy-json">["responsive", "#{id}", ...
However the tags have been refactored to use the shared pagy_json_tag helper. For example:
script = pagy_json_tag(:responsive, id, tags, responsive[:widths], responsive[:series])
Pagy::Frontend::I18N is now Pagy::I18nPagy::I18n.load method accepts params in different format: see the docsearchkick extra has been refactored and its methods work in a different way: see the docelasticsearch_rails extra has been refactored and its methods work in a different way: see the docThe pagy initializer has changed: please replace/update it: pagy.rb
extras/sharedpagy.jssupport extra for features like: incremental, infinite, auto-scroll paginationPagy::Countless support subclasscountless extra integrated with the other extrasPagy::Countless (#108)"/out_of_range" > "/overflow""OutOfRangeError" > "OverflowError"":out_of_range_mode" > ":overflow""out_of_range? > "overflow?"compact and responsive extras have been integrated into the respective frontend extras (bootstrap, bulma, foundation, materialize and navs), so the compact and responsive extras are gone. You should remove them from the pagy.rb initializer, eventually adding the navs extra if you use its plain helpers.templates and javascripts dirs have been moved to lib. If you use rails and the pagy.js you should update the assets.paths in the pagy.rb initializer.pagy_nav_bootstrap_compact and pagy_nav_bootstrap_responsive helpers have been renamed as pagy_nav_compact_bootstrap and pagy_nav_responsive_bootstrap to keep the consistency with the extras structure (and support the consistency of future framework additions). Please, rename them accordingly.Pagy::Frontend::I18N.load_file has been renamed as Pagy::Frontend::I18N.load and expects a hash as the argument. See the I18n doc.Pagy::Frontend::I18N[plurals] has been renamed as Pagy::Frontend::I18N[plural]. See the I18n doc.compact, items and responsive extras has been refactored in order to avoid any usafe-inline vulnerability. The javascript files have been replaced by one shared file, and require to set an event listener or run a function on window load. See the commit below and the javascript doc for details.I18N to fix #39Pagy::I18N has been moved to Pagy::Frontend::I18N: you should update the initializer in case you set any of the Pagy::I18N variable.collection.count(:all):params and :anchor variables to control the generation of arbitrary URLs per pagy instancepagy-extras gem into Pagy, now optionally required in the initializerI18n extra:page_param variable used to get the page number from and create the URL for the page linkspagy-extras gem has been discontinued: you should remove it and update your code as indicated herePagy::I18N[:gem] variable has been removed, so if you want to use the I18n gem in place of the internal Pagy implementation you need just to require 'pagy/extras/i18n' in your initializer. (see the I18n doc)pagy_url_for now requires the pagy argument and it's called with 2 params: if you have overridden it, you should add the extra param.pagy_get_vars now requires the vars argument and it's called with 2 params: if you have overridden it, you should add the extra param.pagy_array_get_vars now requires the vars argument and it's called with 2 params: if you have overridden it, you should add the extra param.