updated documentation

CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## Version 4.4.0
+
+### Changes
+
+- All the public helpers accept optional keyword arguments, for example:
+  - `pagy*_nav(@pagy, pagy_id: 'my-id', link-extra: '...')`
+  - `pagy*_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...', steps: {...})`
+  - `pagy*_combo_nav_js(@pagy, pagy_id: 'my-id', link-extra: '...')`
+  - `pagy_items_selector_js(pagy, pagy_id: 'my-id', item_name: '...', i18n_key: '...')`
+  - `pagy_info(@pagy, item_name: '...', i18n_key: '...')`
+  - `pagy_prev_link(@pagy, text: '...', link_extra: '...')`
+  - `pagy_next_link(@pagy, text: '...', link_extra: '...')`
+  - passing positional arguments (besides `@pagy`) to the public helpers is deprecated and it will be supported only until pagy 5.0 (with the exception is the internal `pagy_url_for` and `pagy_link_proc` methods that will keep using positional arguments)
+- Changed the argument order of `pagy_url_for(page, pagy)` to `pagy_url_for(pagy, page)` for consistency with the rest of the helpers. The legacy usage, has been deprecated and supported only until pagy 5.0.
+
 ## Version 4.3.0
 
 ### Changes

README.md

@@ -19,6 +19,7 @@ Pagy is the ultimate pagination gem that outperforms the others in each and ever
 - Updating `pagy` from `3.0+` to `4.0+` requires a single renaming in your code, but only if it uses the `searchkick` or the `elasticsearch_rails` extras (see the [Changelog](CHANGELOG.md))
 - Added the docker development environment to ease contributions
 - Big code restyling following ruby 3.0 syntax and cops; the code is simpler, more readable and verbose with yet improved performance.
+- All the public helpers accept optional keyword arguments (see the [Changelog](CHANGELOG.md#version-440))
 
 ## Comparison with other gems
 

docs/api/frontend.md

@@ -22,8 +22,8 @@ end
 use some of its method in some view:
 
 ```erb
-<%== pagy_nav(@pagy) %>
-<%== pagy_info(@pagy) %>
+<%== pagy_nav(@pagy, ...) %>
+<%== pagy_info(@pagy, ...) %>
 ```
 
 ## Methods
@@ -32,43 +32,50 @@ All the methods in this module are prefixed with the `"pagy_"` string in order t
 
 Please, keep in mind that overriding any method is very easy with Pagy. Indeed you can do it right where you are using it: no need of monkey-patching or tricky gymmickry.
 
-### pagy_nav(pagy)
+### pagy_nav(pagy, ...)
 
 This method takes the Pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example:
 
 ```erb
-<%== pagy_nav(@pagy) %>
+<%== pagy_nav(@pagy, ...) %>
 ```
 
-The `nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.
+The method accepts also a couple of optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim `link_extra` string to the `a` tag (e.g. `'data-remote="true"'`)
+
+The `nav.*` templates produce the same output, and can be used as an easier (but slower) way to customize it.
 
 See also [Using templates](../how-to.md#using-templates).
 
-### pagy_info(pagy, item_name=nil)
+### pagy_info(pagy, item_name: ..., i18n_key: ...)
 
 This method provides the info about the content of the current pagination. For example:
 
 ```erb
-<%== pagy_info(@pagy) %>
+<%== pagy_info(@pagy, ...) %>
 ```
 
 Will produce something like:
 
 Displaying items <b>476-500</b> of <b>1000</b> in total
 
-or, if you use the `:i18n_key` variable a custom/collection-specific output:
-
-Displaying Products <b>476-500</b> of <b>1000</b> in total
+The method accepts also a couple of optional keyword arguments:
+- `:item_name` an already pluralized string that will be used in place of the dedfault `item/items`
+- `:i18n_key` the key to lookup in a dictionary
 
-You can also overwrite the `item_name` entirely by passing an already pluralized string directly to the helper:
+Notice the `:i18n_key` can be passed also to the constructor or be a less useful global variable (i.e. `VARS[:i18n_key]`
 
 ```erb
-<%== pagy_info(@pagy, 'Widget'.pluralized(@pagy.count) %>
+<%== pagy_info(@pagy, item_name: 'Product'.pluralize(@pagy.count) %>
+<%== pagy_info(@pagy, i18n_key: 'activerecord.model.product' %>
 ```
 
+Displaying Products <b>476-500</b> of <b>1000</b> in total
+
 _(see [Customizing the item name](../how-to.md#customizing-the-item-name))_
 
-### pagy_url_for(page, pagy)
+### pagy_url_for(pagy, page)
 
 This method is called internally in order to produce the url of a page by passing it its number. For standard usage it works out of the box and you can just ignore it.
 
@@ -149,8 +156,14 @@ If you need to add some HTML attribute to the page links, you can pass some extr
     link.call(page_number, 'aria-label="my-label"')
     #=> <a href="...?page=2" data-remote="true" class="page-link" aria-label="my-label">2</a>
     ```
-**WARNING**: we use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
-Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated HTML attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first)
+
+#### CAVEATS
+
+We use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
+
+Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated HTML attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first).
+
+Specifically do not add a `class` attribute that will end up in the `pagy_bootstrap_nav_js`, `pagy_semantic_nav_js` and `pagy_semantic_combo_nav_js`, which define already their own.
 
 ### pagy_t(key, vars={})
 

docs/api/javascript.md

@@ -22,9 +22,11 @@ All the `pagy*_js` helpers produce/render their component on the client side. Th
 
 Load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file, and run `Pagy.init()` on window-load and eventually on [AJAX-load](#using-ajax).
 
-**CAVEATS**
-- If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it.
-- See also [Preventing crawlers to follow look-alike links](../how-to.md#preventing-crawlers-to-follow-look-alike-links)
+### CAVEATS
+
+If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it.
+
+See also [Preventing crawlers to follow look-alike links](../how-to.md#preventing-crawlers-to-follow-look-alike-links)
 
 ### Add the oj gem
 
@@ -166,7 +168,7 @@ The `:steps` is an optional non-core variable used by the `pagy*_nav_js` navs. I
 
 You can set the `:steps` as a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width.
 
-As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance.
+As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance, or even pass it to the `pagy*_nav_js` helper as an optional keyword argument.
 
 For example:
 
@@ -179,7 +181,10 @@ pagy, records = pagy(collection, steps: { 0 => [2,3,3,2], 540 => [3,5,5,3], 720
 
 # or use the :size as any static pagy*_nav
 pagy, records = pagy(collection, steps: false )
-
+```
+```erb
+or pass it to the helper
+<%== pagy_nav_js(@pagy, steps: {...}) %> 
 ```
 
 The above statement means that from `0` to `540` pixels width, Pagy will use the `[2,3,3,2]` size, from `540` to `720` it will use the `[3,5,5,3]` size and over `720` it will use the `[5,7,7,5]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section).
@@ -247,21 +252,32 @@ require 'pagy/extras/uikit'
 Use the `pagy*_combo_nav_js` helpers in any view:
 
 ```erb
-<%== pagy_combo_nav_js(@pagy) %>
-<%== pagy_bootstrap_combo_nav_js(@pagy) %>
-<%== pagy_bulma_combo_nav_js(@pagy) %>
-<%== pagy_foundation_combo_nav_js(@pagy) %>
-<%== pagy_materialize_combo_nav_js(@pagy) %>
-<%== pagy_semantic_combo_nav_js(@pagy) %>
+<%== pagy_combo_nav_js(@pagy, ...) %>
+<%== pagy_bootstrap_combo_nav_js(@pagy, ...) %>
+<%== pagy_bulma_combo_nav_js(@pagy, ...) %>
+<%== pagy_foundation_combo_nav_js(@pagy, ...) %>
+<%== pagy_materialize_combo_nav_js(@pagy, ...) %>
+<%== pagy_semantic_combo_nav_js(@pagy, ...) %>
 ```
 
 ## Methods
 
-### *_nav_js(pagy, ...)
+### pqgy*_nav_js(pagy, ...)
+
+The method accepts also a few optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim `link_extra` string to the `a` tag (e.g. `'data-remote="true"'`)
+- `:steps` the [:steps](#steps) variable
+
+**CAVEATS**: the `pagy_bootstrap_nav_js` and `pagy_semantic_nav_js` assign a class attribute to their links, so do not add anoter class attribute with the `:link_extra`. That would be illegal HTML and ignored by most browsers.
+
+### pagy*_combo_nav_js(pagy, ...)
 
-All `*_nav_js` methods can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id generation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `*_js` call in the same line for the same file.
+The method accepts also a couple of optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:link_extra` which add a verbatim `link_extra` string to the `a` tag (e.g. `'data-remote="true"'`)
 
-**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.
+**CAVEATS**: the `pagy_semantic_combo_nav_js` assigns a class attribute to its links, so do not add another class attribute with the `:link_extra`. That would be illegal HTML and ignored by most browsers.
 
 # Using AJAX
 

docs/extras/bootstrap.md

@@ -19,9 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_bootstrap_nav(@pagy) %>
-<%== pagy_bootstrap_nav_js(@pagy) %>
-<%== pagy_bootstrap_combo_nav_js(@pagy) %>
+<%== pagy_bootstrap_nav(@pagy, ...) %>
+<%== pagy_bootstrap_nav_js(@pagy, ...) %>
+<%== pagy_bootstrap_combo_nav_js(@pagy, ...) %>
 ```
 
 or with a template:
@@ -43,12 +43,13 @@ See [Javascript](../api/javascript.md) if you use `pagy_bootstrap_nav_js` or `pa
 
 This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper.
 
-### pagy_bootstrap_nav(pagy)
+### pagy_bootstrap_nav(pagy, ...)
 
 This method is the same as the `pagy_nav`, but customized for Bootstrap.
 
-The `bootstrap_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
 
+The `bootstrap_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
 
 ### pagy_bootstrap_nav_js(pagy, ...)
 

docs/extras/bulma.md

@@ -19,9 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_bulma_nav(@pagy) %>
-<%== pagy_bulma_nav_js(@pagy) %>
-<%== pagy_bulma_combo_nav_js(@pagy) %>
+<%== pagy_bulma_nav(@pagy, ...) %>
+<%== pagy_bulma_nav_js(@pagy, ...) %>
+<%== pagy_bulma_combo_nav_js(@pagy, ...) %>
 ```
 
 or with a template:
@@ -47,6 +47,8 @@ This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize
 
 This method is the same as the `pagy_nav`, but customized for Bulma.
 
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
+
 The `bulma_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
 
 ### pagy_bulma_nav_js(pagy, ...)

docs/extras/foundation.md

@@ -19,9 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_foundation_nav(@pagy) %>
-<%== pagy_foundation_nav_js(@pagy) %>
-<%== pagy_foundation_combo_nav_js(@pagy) %>
+<%== pagy_foundation_nav(@pagy, ...) %>
+<%== pagy_foundation_nav_js(@pagy, ...) %>
+<%== pagy_foundation_combo_nav_js(@pagy, ...) %>
 ```
 
 or with a template:
@@ -47,6 +47,8 @@ This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize
 
 This method is the same as the `pagy_nav`, but customized for Foundation.
 
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
+
 The `foundation_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
 
 ### pagy_foundation_nav_js(pagy, ...)

docs/extras/items.md

@@ -73,7 +73,7 @@ This extra overrides the `pagy_get_vars` method of the `Pagy::Backend` module in
 
 This extra overrides the `pagy_countless_get_vars` method of the `Pagy::Backend` module (added by the `countless` extra) in order to set the `:items` variable, pulled from the request-params.
 
-### pagy_url_for(page, pagy)
+### pagy_url_for(pagy, page)
 
 This extra overrides also the `pagy_url_for` method of the `Pagy::Frontend` module in order to add the `:items_param` param to the url of the links.
 
@@ -83,7 +83,17 @@ This helper provides an items selector UI, which allows the user to select any a
 
 <span>Show <input type="number" min="1" max="100" value="20" style="padding: 0; text-align: center; width: 3rem;"> items per page</span>
 
-or, if you use the `:i18n_key` variable you can get a custom/collection-specific output:
+The method accepts also a few optional keyword arguments:
+- `:pagy_id` which adds the `id` HTML attributedto the `nav` tag
+- `:item_name` an already pluralized string that will be used in place of the dedfault `item/items`
+- `:i18n_key` the key to lookup in a dictionary
+
+Notice the `:i18n_key` can be passed also to the constructor or be a less useful global variable (i.e. `VARS[:i18n_key]`
+
+```erb
+<%== pagy_items_selector_js(@pagy, item_name: 'Product'.pluralize(@pagy.count) %>
+<%== pagy_items_selector_js(@pagy, i18n_key: 'activerecord.model.product' %>
+```
 
 <span>Show <input type="number" min="1" max="100" value="20" style="padding: 0; text-align: center; width: 3rem;"> Products per page</span>
 

docs/extras/materialize.md

@@ -19,9 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_materialize_nav(@pagy) %>
-<%== pagy_materialize_nav_js(@pagy) %>
-<%== pagy_materialize_combo_nav_js(@pagy) %>
+<%== pagy_materialize_nav(@pagy, ...) %>
+<%== pagy_materialize_nav_js(@pagy, ...) %>
+<%== pagy_materialize_combo_nav_js(@pagy, ...) %>
 ```
 
 See [Javascript](../api/javascript.md) if you use `pagy_materialize_nav_js` or `pagy_materialize_combo_nav_js`.
@@ -38,6 +38,8 @@ This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize
 
 This method is the same as the `pagy_nav`, but customized for Materialize.
 
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
+
 ### pagy_materialize_nav_js(pagy, ...)
 
 See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation.

docs/extras/navs.md

@@ -21,8 +21,8 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_nav_js(@pagy) %>
-<%== pagy_combo_nav_js(@pagy) %>
+<%== pagy_nav_js(@pagy, ...) %>
+<%== pagy_combo_nav_js(@pagy, ...) %>
 ```
 
 See [Javascript](../api/javascript.md).

docs/extras/semantic.md

@@ -19,9 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_semantic_nav(@pagy) %>
-<%== pagy_semantic_nav_js(@pagy) %>
-<%== pagy_semantic_combo_nav_js(@pagy) %>
+<%== pagy_semantic_nav(@pagy, ...) %>
+<%== pagy_semantic_nav_js(@pagy, ...) %>
+<%== pagy_semantic_combo_nav_js(@pagy, ...) %>
 ```
 
 ## Files
@@ -36,6 +36,8 @@ This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize
 
 This method is the same as the `pagy_nav`, but customized for Semantic UI.
 
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
+
 ### pagy_semantic_nav_js(pagy, ...)
 
 See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation.

docs/extras/support.md

@@ -133,7 +133,7 @@ Passing a forced `:count` of 25 will generate 5 pages of 5 items each that will
 You may want to combine it with something like:
 
 ```erb
-<%== pagy_next_link(@pagy, 'More...') %>
+<%== pagy_next_link(@pagy, text: 'More...') %>
 ```
 
 ## Methods
@@ -146,13 +146,13 @@ Returns the url for the previous page. Useful to build minimalistic UIs that don
 
 Returns the url for the next page. Useful to build minimalistic UIs that don't use nav bar links (e.g. `countless` extra).
 
-### pagy_prev_link(pagy, text=pagy_t('pagy.nav.prev'), link_extra="")
+### pagy_prev_link(pagy, text: pagy_t('pagy.nav.prev'), link_extra: "")
 
 Returns the `a` tag for the previous page. It is the same prev link string which is part of the `pagy_nav` helper.
 
 Useful to build minimalistic helpers UIs that don't use nav bar links (e.g. `countless` extra).
 
-### pagy_next_link(pagy, text=pagy_t('pagy.nav.next'), link_extra="")
+### pagy_next_link(pagy, text: pagy_t('pagy.nav.next'), link_extra: "")
 
 Returns the `a` tag for the next page. It is the same next link string which is part of the `pagy_nav` helper.
 

docs/extras/uikit.md

@@ -19,7 +19,9 @@ Render the navigation links in some view...
 with a fast helper:
 
 ```erb
-<%== pagy_uikit_nav(@pagy) %>
+<%== pagy_uikit_nav(@pagy, ...) %>
+<%== pagy_uikit_nav_js(@pagy, ...) %>
+<%== pagy_uikit_combo_nav_js(@pagy, ...) %>
 ```
 
 or with a template:
@@ -43,8 +45,9 @@ This extra adds nav helper to the `Pagy::Frontend` module. You can customize it
 
 This method is the same as the `pagy_nav`, but customized for UIkit.
 
-The `uikit_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
+See the [pagy_nav(pagy, ...)](../api/frontend.md#pagy_navpagy-) documentation.
 
+The `uikit_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates).
 
 ### pagy_uikit_nav_js(pagy, ...)