](https://github.com/ddnexus)[
](https://github.com/benkoshy)[
](https://github.com/dependabot[bot])[
](https://github.com/grosser)[
](https://github.com/workgena)[
](https://github.com/bquorning)[
](https://github.com/molfar)[
](https://github.com/sunny)[
](https://github.com/enzinia)[
](https://github.com/espen)[
](https://github.com/Earlopain)[
](https://github.com/berniechiu)[
](https://github.com/renshuki)[
](https://github.com/wimdavies)[
](https://github.com/tiagotex)[
](https://github.com/gamafranco)[
](https://github.com/thomasklemm)[
](https://github.com/tersor)[
](https://github.com/simonneutert)[
](https://github.com/rainerborene)[
](https://github.com/petergoldstein)[
](https://github.com/sabljak)[
](https://github.com/cseelus)[
](https://github.com/ashmaroli)[
](https://github.com/747)[
](https://github.com/WilliamHorel)[
](https://github.com/okuramasafumi)[
](https://github.com/olleolleolle)[
](https://github.com/pedrocarmona)[
](https://github.com/rafaeelaudibert)[
](https://github.com/rafaelmontas)[
](https://github.com/yenshirak)[
](https://github.com/Tolchi)[
](https://github.com/serghost)[
](https://github.com/sliminas)[
](https://github.com/artplan1)[
](https://github.com/woller)[
](https://github.com/sk8higher)[
](https://github.com/muhammadnawzad)[
](https://github.com/ronald)[
](https://github.com/achmiral)[
](https://github.com/mauro-ni)[
](https://github.com/borama)[
](https://github.com/creativetags)[
](https://github.com/mcary)[
](https://github.com/marckohlbrugge)[
](https://github.com/tr4b4nt)[
](https://github.com/tiejianluo)[
](https://github.com/szTheory)[
](https://github.com/smoothdvd)[
](https://github.com/rhodes-david)[
](https://github.com/radinreth)[
](https://github.com/okliv)[
](https://github.com/nedimdz)[
](https://github.com/msdundar)[
](https://github.com/m-abdurrehman)[
](https://github.com/dwieringa)[
](https://github.com/jyuvaraj03)[
](https://github.com/YutoYasunaga)[
](https://github.com/iamyujinwon)[
](https://github.com/yhk1038)[
](https://github.com/ya-s-u)[
](https://github.com/yshmarov)[
](https://github.com/thattimc)[
](https://github.com/thomaschauffour)[
](https://github.com/snkashis)[
](https://github.com/fluser)[
](https://github.com/tulak)[
](https://github.com/Federico-G)[
](https://github.com/egimenos)[
](https://github.com/elliotlarson)[
](https://github.com/hungdiep97)[
](https://github.com/djpremier)[
](https://github.com/davidwessman)[
](https://github.com/david-a-wheeler)[
](https://github.com/MrMoins)[
](https://github.com/excid3)[
](https://github.com/cellvinchung)[
](https://github.com/brunoocasali)[
](https://github.com/BrandonKlotz)[
](https://github.com/Atul9)[
](https://github.com/amenon)[
](https://github.com/artinboghosian)[
](https://github.com/antonzaharia)[
](https://github.com/andrew)[
](https://github.com/AliOsm)[
](https://github.com/AbelToy)[
](https://github.com/maful)[
](https://github.com/loed-idzinga)[
](https://github.com/epeirce)[
](https://github.com/kobusjoubert)[
](https://github.com/KevinColemanInc)[
](https://github.com/neontuna)[
](https://github.com/xuanxu)[
](https://github.com/jpgarritano)[
](https://github.com/archonic)[
](https://github.com/jonasMirendo)[
](https://github.com/lostapathy)[
](https://github.com/jivko-chobanov)[
](https://github.com/whithajess)
+[
-
-
-
-
-@@ pagy_head
-
-
-
-@@ bootstrap_head
-
-
-@@ bulma_head
-
-
-@@ foundation_head
-
-
-@@ materialize_head
-
-
-
-@@ semantic_head
-
-
-
-@@ tailwind_head
-
-
-
-
-@@ uikit_head
-
-
-
-
-@@ helpers
-"
}
```
-|||
-
+++ Webpack
Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
-||| package.json
-
-```json
+```json package.json
{
"build": "NODE_PATH=\"$(bundle show 'pagy')/lib/javascripts\" "
}
```
-|||
-
-||| webpack.confg.js
-
-```js
+```js webpack.confg.js
module.exports = {
..., // your original config
resolve: { // add resolve.modules
@@ -232,8 +190,6 @@ module.exports = {
}
```
-|||
-
#### Legacy way
Ensure that the `erb` loader is installed:
@@ -243,41 +199,28 @@ bundle exec rails webpacker:install:erb
```
Generate a local pagy javascript file using `erb` with webpacker:
-||| app/javascript/packs/pagy.js.erb
-
-```erb
+```erb app/javascript/packs/pagy.js.erb
<%= Pagy.root.join('javascripts', 'pagy.js').read %>
window.addEventListener(YOUR_EVENT_LISTENER, Pagy.init)
```
-
-|||
_where `YOUR_EVENT_LISTENER` is the load event that works with your app (
e.g. `"turbo:load"`, `"turbolinks:load"`, `"load"`, ...)._
-||| app/javascript/application.js
-
-```js
+```js app/javascript/application.js
import './pagy.js.erb'
```
-|||
-
+++ Rollup
Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
-||| package.json
-
-```json
+```json package.json
{
"build": "NODE_PATH=\"$(bundle show 'pagy')/lib/javascripts\" "
}
```
-|||
-
-||| rollup.confg.js
Configure the `plugins[resolve]`:
-```js
+```js rollup.confg.js
export default {
..., // your original config
plugins: [
@@ -290,8 +233,6 @@ export default {
]
}
```
-
-|||
+++
#### Non-Rails apps
@@ -303,9 +244,7 @@ export default {
After the helper is loaded you have to initialize `Pagy` to make it work:
+++ Stimulus JS
-||| pagy_initializer_controller.js
-
-```js
+```js pagy_initializer_controller.js
import {Controller} from "@hotwired/stimulus"
import Pagy from "pagy-module" // if using sprockets, you can remove above line, but make sure you have the appropriate directive if your manifest.js file.
@@ -316,30 +255,20 @@ export default class extends Controller {
}
```
-|||
-
-||| View
-
-```erb
+```erb View
+## Overview
+
For all its own interactive helpers shown above, the pagy gem includes a few stylesheets files that you can download, link or
copy.
!!!warning
-You don't need any stylesheet if you use a frontend extra
-like: [bootstrap](/docs/extras/bootstrap), [bulma](/docs/extras/bulma), [foundation](/docs/extras/foundation), [materialize](/docs/extras/materialize), [semantic](/docs/extras/semantic), [uikit](/docs/extras/uikit)
+You don't need any stylesheet if you use a frontend extra like:
+[bootstrap](/docs/extras/bootstrap), [bulma](/docs/extras/bulma), [foundation](/docs/extras/foundation),
+[materialize](/docs/extras/materialize), [semantic](/docs/extras/semantic), [uikit](/docs/extras/uikit)
!!!
-!!!success
-You can adapt the stylesheets below to anything you need by just editing the content inside the curly brackets, usually leaving
-the rest
-untouched.
+### HTML Structure
+
+In order to ensure a minimalistic valid output, still complete with all the ARIA attributes, we use a single line with the minimum
+number of tags and class attributes that can identify all the parts of the nav bars:
+
+- The output of `pagy_nav` and `pagy_nav_js` are a series of `a` tags inside a wrapper `nav` tag
+- The disabled links are so because they are missing the `href` attributes
+- The `pagy nav` and `pagy nav-js` classes are assigned to the `nav` tag
+- The `current`, `gap` classes are assigned to the specific `a` tags
+
+!!! Notice
+
+- The stylesheets target the disabled `a` tags by using the `pagy a:not([href])` selector
+- You can make the `gap` look like the other pages by removing the `:not(.gap)`
+- You can target the previous and next links by using `pagy a:first-child` and `pagy a:last-child` pseudo classes
+
+!!!
+
+!!!success
+You can totally transform the stylesheets below by just editing the content inside the curly brackets, usually leaving
+the rest untouched.
+
+!!!warning The order of the selectors is important!
!!!
+++ pagy.scss
@@ -41,19 +63,16 @@ stylesheet_path = Pagy.root.join('stylesheets', 'pagy.css')
:::code source="/lib/stylesheets/pagy.css" :::
-+++ pagy.tailwind.scss
++++ pagy.tailwind.css
-[!file](/lib/stylesheets/pagy.tailwind.scss)
+[!file](/lib/stylesheets/pagy.tailwind.css)
```ruby
-stylesheet_path = Pagy.root.join('stylesheets', 'pagy.tailwind.scss')
+stylesheet_path = Pagy.root.join('stylesheets', 'pagy.tailwind.css')
```
-:::code source="/lib/stylesheets/pagy.tailwind.scss" :::
+:::code source="/lib/stylesheets/pagy.tailwind.css" :::
+++
-!!!
-You can also quickly check and interact with all the pagy and extra styles (including the `pagy` and `tailwind` stylesheets above)
-by running the single-file self-contaied app [!file](/apps/pagy_styles.ru)
-!!!
+[!button corners="pill" variant="success" text=":icon-play: Try it now!"](/playground.md#3-demo-app)
diff --git a/docs/assets/nav.html b/docs/assets/nav.html
new file mode 100644
index 000000000..0b149287d
--- /dev/null
+++ b/docs/assets/nav.html
@@ -0,0 +1,11 @@
+
diff --git a/docs/assets/nav.html.erb b/docs/assets/nav.html.erb
index ed497b627..34fddd30c 100644
--- a/docs/assets/nav.html.erb
+++ b/docs/assets/nav.html.erb
@@ -1,41 +1,29 @@
-<%#
- The link variable is set to a proc that returns the link tag (complete with rel and aria-current)
- Usage: link.call( page_number [, text [, extra_attributes_string ]])
--%>
-<% link = pagy_link_proc(pagy) -%>
-
<%= style %>
- -Collection
-@records: <%= @records.join(',') %>
- -
-
diff --git a/docs/api/ARIA.md b/docs/api/ARIA.md
index d48bafdb5..06e34ac05 100644
--- a/docs/api/ARIA.md
+++ b/docs/api/ARIA.md
@@ -10,34 +10,29 @@ Since version `7.0.0` pagy has introduced a consistent set of ARIA compliant att
+++ Nav helpers
-Pagy provides the instance-customizable `aria-label` for the root element of its helpers. It is usually a `nav` element, but for
+Pagy provides the customizable `aria-label` for the root element of its helpers. It is usually a `nav` element, but for
the few helper styles that use a different root element, pagy adds a `role="navigation"` attribute to it.
-The default string for the `aria-label` of the root element is "Page" / "Pages" (translated and pluralized according to the
-total page number). It's arguably a better description of the nav content than just "Pagination" (also difficult to
-translate in certain languages).
+The default string for the `aria-label` of the root element is "Page" / "Pages" (translated and pluralized according to the total
+page number). It's arguably a better description of the nav content than just "Pagination" (also difficult to translate in certain
+languages).
-!!!warning Help us with your languages!
+!!!success Help us with your languages!
Please, check the `pagy.aria_label.nav` in the [locale files](https://github.com/ddnexus/pagy/tree/master/lib/locales)
used by your app to be already correctly translated and pluralized. If it's not, please, post your translation in the issue linked
in the file itself. Thank you!
!!!
!!!danger Validation
-Since the `nav` or `role="navigation"` elements of a HTML document are considered `landmark roles`, they should be uniquely
-aria-identified in the page.
+Since the `nav` or `role="navigation"` elements of a HTML document are considered `landmark roles`, they
+should be uniquely aria-identified in the page.
-If you use more than one pagy helper in the same page, you should not rely on the default (that would
-otherwise generate a non-valid document), instead, you should pass either your own (possibly translated and
-pluralized) `aria-label` string or an i18n-key that locates the translated and pluralized string in your dictionary file. For
-example:
+If you use more than one pagy helper in the same page, you should not rely on the default (that would otherwise generate a
+non-valid document), instead, you should pass your own (possibly translated and pluralized) `aria-label` string. For example:
```erb
-<%# Explicitly set the nav_aria_label string %>
-<%== pagy_nav(@pagy, nav_aria_label: 'Search result pages') %>
-
-<%# Pass an i18n key in a dictionary file (pluralized entry) %>
-<%== pagy_nav(@pagy, nav_i18n_key: 'my.aria_label.nav') %>
+<%# Explicitly set the aria_label string %>
+<%== pagy_nav(@pagy, aria_label: 'Search result pages') %>
```
!!!
diff --git a/docs/api/backend.md b/docs/api/backend.md
index 56159a97f..62fb703cc 100644
--- a/docs/api/backend.md
+++ b/docs/api/backend.md
@@ -28,9 +28,7 @@ and [meilisearch](/docs/extras/meilisearch.md) extras for specific backend custo
## Synopsis
-||| Controller
-
-```ruby
+```ruby Controller
include Pagy::Backend
# optional overriding of some sub-method
@@ -44,8 +42,6 @@ def index
end
```
-|||
-
## Methods
All the methods in this module are prefixed with the `"pagy_"` string, to avoid any possible conflict with your own methods when
@@ -75,7 +71,7 @@ self contained custom `pagy` method. (see [Writing your own Pagy methods](#writi
Sub-method called only by the `pagy` method, it returns the hash of variables used to initialize the Pagy object.
-Override it if you need to add or change some variable. For example you may want to add the `:item_i18n_key` in order to customize
+Override it if you need to add or change some variable. For example you may want to add the `:item_name` in order to customize
the output _(see [How to customize the item name](/docs/how-to.md#customize-the-item-name))_, or even cache the `count`.
!!!warning Don't remove `:count` and `:page`
@@ -122,9 +118,7 @@ In that case you can define a number of `pagy_*` custom methods specific for eac
For example: here is a `pagy` method that doesn't call any sub-method, that may be enough for your needs:
-||| Controller
-
-```ruby
+```ruby Controller
def pagy_custom(collection, vars = {})
pagy = Pagy.new(count: collection.count(*vars[:count_args]), page: params[:page], **vars)
@@ -132,8 +126,6 @@ def pagy_custom(collection, vars = {})
end
```
-|||
-
You can easily write a `pagy` method for _any possible_ environment: please read how
to [Paginate Any Collection](/docs/how-to.md#paginate-any-collection) for details.
diff --git a/docs/api/frontend.md b/docs/api/frontend.md
index 8ff45bfcd..4e5da783e 100644
--- a/docs/api/frontend.md
+++ b/docs/api/frontend.md
@@ -15,8 +15,7 @@ You can extend this module with a few more nav helpers _(see the [extras](/categ
## Synopsis
-||| View Helper
-```ruby
+```ruby View Helper
include Pagy::Frontend
# optional overriding of some sub-method
@@ -24,15 +23,11 @@ def pagy_nav(...)
...
end
```
-|||
-
-||| View
-```erb
+```erb View
<%== pagy_nav(@pagy, **vars) %>
<%== pagy_info(@pagy, **vars) %>
```
-|||
## Methods
@@ -44,22 +39,17 @@ Please, keep in mind that overriding any method is very easy with Pagy. Indeed y
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:
-||| View
-```erb
+```erb View
<%== pagy_nav(@pagy, **vars) %>
```
-|||
The method accepts also a few optional keyword arguments variables:
-- `:pagy_id`: the `id` HTML attribute to the `nav` tag (omitted by default)
-- `:link_extra`: the verbatim string added to the `a` tag (e.g. `'data-remote="true"'`)
-- `:nav_aria_label`: an already pluralized string for the `aria-label` attribute of the `nav`, that will be used in place of
+- `:id`: the `id` HTML attribute to the `nav` tag (omitted by default)
+- `:aria_label`: an already pluralized string for the `aria-label` attribute of the `nav`, that will be used in place of
the default `pagy.aria_label.nav`
-- `:nav_i18n_key`: the i18n dictionary key to lookup the default `pagy.aria_label.nav` pluralized value (ignored if
- `nav_aria_label` is
defined)
-- `:size` which use the passed size Array instead of the `:size` variable of the instance
+- `:size` which use the passed value instead of the `:size` variable of the instance
See also [ARIA Attributes](ARIA.md).
@@ -77,18 +67,12 @@ Will produce something like:
The method accepts also a few optional keyword arguments variables:
-- `:pagy_id`: the `id` HTML attribute to the `span` tag wrapping the info
+- `:id`: the `id` HTML attribute to the `span` tag wrapping the info
- `:item_name` an already pluralized string that will be used in place of the default `item/items`
-- `:item_i18n_key` the key to lookup in a dictionary
-
-Notice the `:item_i18n_key` can be passed also to the constructor or be a global variable (i.e. `Pagy::DEFAULT[:item_i18n_key]`
-||| View
-```erb
+```erb View
<%== pagy_info(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %>
-<%== pagy_info(@pagy, item_i18n_key: 'activerecord.model.product' %>
```
-|||
Displaying Products 476-500 of 1000 in total
@@ -100,105 +84,59 @@ This method is called internally in order to produce the url of a page by passin
See also [How to customize the URL](/docs/how-to.md#customize-the-url) and [How to customize the params](/docs/how-to.md#customize-the-params).
-==- `pagy_link_proc(pagy, link_extra='')`
+==- `pagy_anchor(pagy)`
-This method is called internally to get a very specialized and fast proc that produce the HTML links for the pages.
+This method is called internally to get a very specialized and fast proc that produce the HTML anchor elements (i.e. `a` tags) for the pages.
For standard usage you may just need to read [How to customize the link attributes](/docs/how-to.md#customize-the-link-attributes), for advanced usage see below.
-===
-## Advanced Usage
+### Advanced Usage
-You need this section only if you are going to override a `pagy_nav*` helper AND you need to customize the HTML attributes of the link tags.
+You need this section only if you are going to override a `pagy_nav*` helper AND you need to customize the HTML attributes of the
+link tags.
!!! primary
-This method is not intended to be overridden, however you could just replace it in your overridden `pagy_nav*` helpers with some generic helper like the rails `link_to`. If you intend to do so, be sure to have a very good reason, since using `pagy_link_proc` is a lot faster than the rails `link_to` (benchmarked at ~22x faster using ~18x less memory on a 20 links nav).
+This method is not intended to be overridden, however you could just replace it in your overridden `pagy_nav*` helpers with some
+generic helper like the rails `link_to`. If you intend to do so, be sure to have a very good reason, since using `pagy_anchor` is
+a lot faster than the rails `link_to` (benchmarked at ~22x faster using ~18x less memory on a 20 links nav).
!!!
-This method returns a specialized proc that you call to produce the page links. The reason it is a two steps process instead of a single method call is performance. Indeed the method calls the potentially expensive `pagy_url_for` only once and generates the proc, then calling the proc will just interpolates the strings passed to it.
+This method returns a specialized proc that you call to produce the page `a` tags. The reason it is a two steps process instead of
+a single method call is performance. Indeed the method calls the potentially expensive `pagy_url_for` only once and generates the
+proc, then calling the proc will just interpolates the strings passed to it.
Here is how you should use it: in your helper call the method to get the proc (just once):
```ruby
-link = pagy_link_proc( pagy [, extra_attributes_string ] )
+a = pagy_anchor(pagy)
```
-Then call the `"link"` proc to get the links (multiple times):
+Then call the `a` proc to get the links (multiple times):
```ruby
-link.call( page_number [, text [, extra_attributes_string ] ] )
+my_link = a.(page_number, text, classes:, aria_label:)
```
-### Extra attribute strings
+#### The anchor_string variable
-If you need to add some HTML attribute to the page links, you can pass some extra attribute string at many levels, depending on the scope you want your attributes to be added.
+If you need to add some HTML attribute to ALL the page links, you can set the `:anchor_string` variable.
-!!!primary Attributes Must be Valid HTML
-For performance reasons, the extra attributes strings must be formatted as valid HTML attribute/value pairs. _All_ the strings passed at any level will get inserted *verbatim* in the HTML of the link.
+!!!warning Attributes Must be Valid HTML
+For performance reasons, the `:anchor_string` string must be formatted as valid HTML attribute/value pairs because it will get
+inserted *verbatim* in the HTML of the `a` tag.
!!!
-1. For all pagy objects: set the global variable `:link_extra`:
-
- ||| pagy.rb (initializer)
- ```ruby
- Pagy::DEFAULT[:link_extra] = 'data-remote="true"'
- |||
-
- ||| View
- ```ruby
- link = pagy_link_proc(pagy)
- link.call(2)
- #=> 2
- ```
- |||
-
-2. For one Pagy object: pass the `:link_extra` variable to a Pagy constructor (`Pagy.new` or `pagy` controller method):
-
- ||| Controller
- ```ruby
- @pagy, @records = pagy(my_scope, link_extra: 'data-remote="true"')
- ```
- |||
-
- ||| View
- ```ruby
- link = pagy_link_proc(pagy)
- link.call(2)
- #=> 2
- ```
-
-3. For all the `link.call`: pass an extra attributes string to the `pagy_link_proc`:
-
- ||| View
- ```ruby
- link = pagy_link_proc(pagy, 'class="page-link"')
- link.call(2)
- #=> 2
- link.call(3)
- #=> 3
- ```
- |||
-
-4. For a single `link.call`: pass an extra attributes string when you call the proc:
-
- ||| View
- ```ruby
- link.call(page_number, 'aria-label="my-label"')
- #=> 2
- ```
- |||
-
-#### CAVEATS
-
-We use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
-
-!!! warning Do Not Pass Atributes Multiple Times
-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).
-!!!
+!!! warning Do Not Pass Attributes Already Present
+Be careful not to pass some attribute that is already added by the helper. That would generate a duplicate HTML attribute which
+is invalid html (although handled by all mayor browsers by ignoring all the duplicates but the first).
-!!!warning Do not add `class` attribute for `*js` helpers
-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.
+!!!success Easily check the native component attributes:
+```sh
+pagy demo
+# or: bundle exec pagy demo
+# ...and point your browser at http://0.0.0.0:8000
+```
!!!
==- `pagy_t(key, vars={})`
diff --git a/docs/api/i18n.md b/docs/api/i18n.md
index 1fec097a3..dba7a291b 100644
--- a/docs/api/i18n.md
+++ b/docs/api/i18n.md
@@ -39,9 +39,7 @@ you can do it all by passing a few arguments to the `Pagy::I18n.load` method.
### Synopsis
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
# load the "de" built-in locale:
Pagy::I18n.load(locale: 'de')
@@ -63,8 +61,6 @@ Pagy::I18n.load({ locale: 'en' },
pluralize: lambda { |count| ... } })
```
-|||
-
!!!warning Use one load statement
Use only one load statement or you will get a FrozenError exception
!!!
@@ -83,14 +79,10 @@ When you configure multiple locales (i.e. this does not apply to single locale a
request. You usually do that in the application controller, by checking the `:locale` param. For example, in a rails app you
should do something like:
-||| Controller
-
-```ruby
+```ruby Controller
before_action { @pagy_locale = params[:locale] }
```
-|||
-
If the `@pagy_locale` is `nil` or missing pagy will serve the first locale you set in the configuration.
## Adding the model translations
diff --git a/docs/api/javascript/ajax.md b/docs/api/javascript/ajax.md
index ac8ff3458..f72db8ecb 100644
--- a/docs/api/javascript/ajax.md
+++ b/docs/api/javascript/ajax.md
@@ -9,44 +9,27 @@ order: 1
If you AJAX-render any of the javascript helpers mentioned above, you should also execute `Pagy.init(container_element);` in the
javascript template. Here is an example for an AJAX-rendered `pagy_bootstrap_nav_js`:
-||| Controller
-
-```ruby
-
+```ruby Controller
def pagy_remote_nav_js
- # notice the link_extra to enable Ajax
- @pagy, @products = pagy(collection, link_extra: 'data-remote="true"')
+ # notice the anchor_string to enable Ajax
+ @pagy, @products = pagy(collection, anchor_string: 'data-remote="true"')
end
```
-|||
-
-||| `pagy_remote_nav_js.html.erb` - non-AJAX render (first page-load):
-
-```erb
+```erb "pagy_remote_nav_js.html.erb" - non-AJAX render (first page-load)
pagy_<%= prefix %>nav
- <%= html = send(:"pagy_#{prefix}nav", @pagy, pagy_id: 'nav', nav_aria_label: 'Pages nav') %> - <%= highlight(html) %> - -pagy_<%= prefix %>nav_js
- <%= html = send(:"pagy_#{prefix}nav_js", @pagy, pagy_id: 'nav-js', nav_aria_label: 'Pages nav_js') %> - <%= highlight(html) %> - -pagy_<%= prefix %>nav_js (responsive)
- <%= html = send(:"pagy_#{prefix}nav_js", @pagy, pagy_id: 'nav-js-responsive', - nav_aria_label: 'Pages nav_js_responsive', - steps: { 0 => [1,3,3,1], 600 => [2,4,4,2], 900 => [3,4,4,3] }) %> - <%= highlight(html) %> - -pagy_<%= prefix %>combo_nav_js
- <%= html = send(:"pagy_#{prefix}combo_nav_js", @pagy, pagy_id: 'combo-nav-js', nav_aria_label: 'Pages combo_nav_js') %> - <%= highlight(html) %> - -pagy_items_selector_js
- <%= html = pagy_items_selector_js(@pagy, pagy_id: 'items-selector-js') %> - <%= highlight(html) %> - -pagy_info
- <%= html = pagy_info(@pagy, pagy_id: 'pagy-info') %> - <%= highlight(html) %> -
<%= render partial: 'nav_js' %>
```
-|||
-
-||| `_nav_js.html.erb` partial - AJAX and non-AJAX rendering:
-
-```erb
+```erb "_nav_js.html.erb" partial - AJAX and non-AJAX rendering
<%== pagy_bootstrap_nav_js(@pagy) %>
```
-|||
-
-||| `pagy_remote_nav_js.js.erb`template - AJAX rendering:
-
-```js
+```js "pagy_remote_nav_js.js.erb" template - AJAX rendering
document.getElementById('container').innerHTML = "<%= j(render 'nav_js')%>";
Pagy.init(document.getElementById('container'));
-````
-
-|||
+```
!!!warning Don't forget to re-initialize!
diff --git a/docs/api/javascript/combo-navs.md b/docs/api/javascript/combo-navs.md
index cf431ad94..3da994ab1 100644
--- a/docs/api/javascript/combo-navs.md
+++ b/docs/api/javascript/combo-navs.md
@@ -23,28 +23,24 @@ Here is a screenshot (from the `bootstrap` extra):
+[!button corners="pill" variant="success" text=":icon-play: Try it now!"](/playground.md#3-demo-app)
+
## Synopsis
See [Setup Javascript](setup.md).
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
# you only need one of the following extras
require 'pagy/extras/bootstrap'
require 'pagy/extras/bulma'
require 'pagy/extras/foundation'
require 'pagy/extras/materialize'
-require 'pagy/extras/navs'
+require 'pagy/extras/pagy'
require 'pagy/extras/semantic'
require 'pagy/extras/uikit'
```
-|||
-
-||| Any View
-
-```erb
+```erb Any View
<%== pagy_combo_nav_js(@pagy, **vars) %>
<%== pagy_bootstrap_combo_nav_js(@pagy, **vars) %>
@@ -54,8 +50,6 @@ require 'pagy/extras/uikit'
<%== pagy_semantic_combo_nav_js(@pagy, **vars) %>
```
-|||
-
## Methods
==- `pagy*_combo_nav_js(pagy, **vars)`
@@ -63,8 +57,4 @@ require 'pagy/extras/uikit'
The method accepts also the same optional keyword arguments variables of
the [pagy_nav(pagy, **vars)](/docs/api/frontend.md#pagy-nav-pagy-vars)
-!!!warning
-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.
-!!!
===
diff --git a/docs/api/javascript/navs.md b/docs/api/javascript/navs.md
index 90109e163..f61a3a607 100644
--- a/docs/api/javascript/navs.md
+++ b/docs/api/javascript/navs.md
@@ -25,28 +25,24 @@ Here is a screenshot (from the `bootstrap`extra) showing responsiveness at diffe
+[!button corners="pill" variant="success" text=":icon-play: Try it now!"](/playground.md#3-demo-app)
+
## Synopsis
See [Setup Javascript](setup).
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
# Use just one:
require 'pagy/extras/bootstrap'
require 'pagy/extras/bulma'
require 'pagy/extras/foundation'
require 'pagy/extras/materialize'
-require 'pagy/extras/navs'
+require 'pagy/extras/pagy'
require 'pagy/extras/semantic'
require 'pagy/extras/uikit'
```
-|||
-
-||| Any View
-
-```erb
+```erb Any View
<%== pagy_nav_js(@pagy) %>
<%== pagy_bootstrap_nav_js(@pagy) %>
@@ -56,8 +52,6 @@ require 'pagy/extras/uikit'
<%== pagy_semantic_nav_js(@pagy) %>
```
-|||
-
## Variables
| Variable | Description | Default |
@@ -78,18 +72,12 @@ pass it to the `pagy*_nav_js` helper as an optional keyword argument.
For example:
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
# globally
Pagy::DEFAULT[:steps] = { 0 => 5, 540 => [3, 5, 5, 3], 720 => [5, 7, 7, 5] }
```
-|||
-
-||| Controller
-
-```ruby
+```ruby Controller
# or for a single instance
pagy, records = pagy(collection, steps: { 0 => 5, 540 => [3, 5, 5, 3], 720 => [5, 7, 7, 5] })
@@ -97,8 +85,6 @@ pagy, records = pagy(collection, steps: { 0 => 5, 540 => [3, 5, 5, 3], 720 => [5
pagy, records = pagy(collection, steps: false)
```
-|||
-
```erb
or pass it to the helper
<%== pagy_nav_js(@pagy, steps: {...}) %>
@@ -151,9 +137,4 @@ document.getElementById('my-pagy-nav-js').render();
The method accepts also the same optional keyword arguments variables of
the [pagy_nav(pagy, **vars)](/docs/api/frontend#pagy-nav-pagy-vars)
-!!!warning
-The `pagy_bootstrap_nav_js` and `pagy_semantic_nav_js` assign a class attribute to their links, so do not add another class
-attribute with the `:link_extra`. That would be illegal HTML and ignored by most browsers.
-!!!
-
===
diff --git a/docs/api/javascript/setup.md b/docs/api/javascript/setup.md
index d39bebcc4..c562bec77 100644
--- a/docs/api/javascript/setup.md
+++ b/docs/api/javascript/setup.md
@@ -7,7 +7,7 @@ order: 4
# Javascript Setup
!!!info Notice
-A javascript setup is required only for the `pagy*_js` helpers. Just using `'data-remote="true"'` in any other helper works out of
+A javascript setup is required only for the `pagy*_js` helpers. Just using something like `anchor_string: 'data-remote="true"'` in any other helper works out of
the box.
!!!
@@ -114,63 +114,35 @@ Depending on your environment you have a few ways of configuring your app:
In older versions of Rails, you can configure the app to look into the installed pagy gem javascript files:
+++ Sprockets
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts') # uncomment.
```
-|||
-
-||| manifest.js (or `application.js` for old sprocket sprockets):
-
-```js
+```js manifest.js (or "application.js" for old sprocket sprockets):
//= require pagy
```
-|||
-
+++ Importmaps
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts') #uncomment
```
-|||
-
-||| app/assets/config/manifest.js
-
-```js
+```js app/assets/config/manifest.js
//= link pagy-module.js
```
-|||
-
-||| config/importmap.rb
-
-```ruby
+```ruby config/importmap.rb
pin 'pagy-module'
```
-|||
-
+++ Propshaft
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts')
```
-|||
-
-||| application.html.erb
-
-```erb
+```erb application.html.erb
<%= javascript_include_tag "pagy" %>
```
-
-|||
+++
#### Builders
@@ -182,9 +154,7 @@ javascript path:
You can create a symlink or a copy of the `pagy-module.js` file (available in the pagy gem) into an app compiled dir and use it as
a regular app file. That way any builder will pick it up. For example:
-||| config/initializers/pagy.rb
-
-```ruby
+```ruby config/initializers/pagy.rb
# Create/refresh the `app/javascript/pagy-module.js` symlink/copy every time
# the app restarts (unless in production), ensuring syncing when pagy is updated.
# Replace the FileUtils.ln_sf with FileUtils.cp if your OS doesn't support file linking.
@@ -192,35 +162,23 @@ FileUtils.ln_sf(Pagy.root.join('javascripts', 'pagy-module.js'), Rails.root.join
unless Rails.env.production?
```
-|||
-
+++ esbuild
Prepend the `NODE_PATH` environment variable to the `scripts.build` command:
-||| package.json
-
-```json
+```json package.json
{
"build": "NODE_PATH=\"$(bundle show 'pagy')/lib/javascripts\"
<%== pagy_nav_js(@pagy) %>
```
-|||
-
+++ jsbundling-rails
Import and use the pagy module:
-||| app/javascript/application.js
-
-```js
+```js app/javascript/application.js
import Pagy from "pagy-module";
window.addEventListener("turbo:load", Pagy.init);
```
-|||
-
+++ Others
```js
diff --git a/docs/api/pagy.md b/docs/api/pagy.md
index 9c77211d7..7df9ef9cb 100644
--- a/docs/api/pagy.md
+++ b/docs/api/pagy.md
@@ -14,9 +14,7 @@ memory ([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy.rb)).
## Synopsis
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
# set global defaults and extra variables
# they will get merged with every new Pagy instance
Pagy::DEFAULT[:items] = 25
@@ -43,8 +41,6 @@ pagy.series
#=> [1, 2, "3", 4, 5, 6, 7, :gap, 40]
```
-|||
-
## Global Default
The `Pagy::DEFAULT` is a globally available hash used to set defaults variables. It is a constant for easy access, but it is
@@ -54,17 +50,13 @@ variables passed with the `new` method every times a `Pagy` instance gets create
You will typically use it in a `pagy.rb` initializer file to pass defaults values. For example:
-||| pagy.rb (initializer)
-
-```ruby
+```ruby pagy.rb (initializer)
Pagy::DEFAULT[:items] = 25
Pagy::DEFAULT[:my_option] = 'my option'
...
Pagy::DEFAULT.freeze
```
-|||
-
## Methods
==- `Pagy.root`
@@ -150,19 +142,17 @@ They are all integers:
### Other Variables
-| Variable | Description | Default |
-|:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------|
-| `:size` | The size of the page links to show: can be an array of initial pages, before current page, after current page, final pages or the total page size. _(see also [How to control the page links](/docs/how-to.md#control-the-page-links))_ | `7` |
-| `:page_param` | The name of the page param name used in the url. _(see [How to customize the page param](/docs/how-to.md#customize-the-page-param))_ | `:page` |
-| `:params` | It can be a `Hash` of params to add to the URL, or a `Proc` that can edit/add/delete the request params _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `{}` |
-| `:fragment` | The arbitrary fragment string (including the "#") to add to the url. _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `''` |
-| `:link_extra` | The extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [How to customize the link attributes](/docs/how-to.md#customize-the-link-attributes))_ | `''` |
-| `:item_i18n_key` | The i18n key to lookup the `item_name` that gets interpolated in a few helper outputs (see [How to customize the item name](/docs/how-to.md#customize-the-item-name)) | `'pagy.item_name'` |
-| `:nav_i18n_key` | The i18n key to lookup the `aria-label` for the `pagy*_nav` helpers | `'pagy.aria_label.nav'` |
-| `:cycle` | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` |
-| `:request_path` | Allows overriding the request path for pagination links. Pass the path only (not the absolute url). _(see [Customize the request path](/docs/how-to.md#customize-the-request-path))_ | `request.path` |
-| `jsonapi` | Enable `jsonapi` compliance of the pagy query params | `false` |
-| `count_args` | The arguments passed to the `collection.count`. You may want to set it to `[]` in ORMs different than ActiveRecord | [:all] |
+| Variable | Description | Default |
+|:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
+| `:size` | The size of the page links to show: can be an array of initial pages, before current page, after current page, final pages or the total page size. _(see also [How to control the page links](/docs/how-to.md#control-the-page-links))_ | `7` |
+| `:page_param` | The name of the page param name used in the url. _(see [How to customize the page param](/docs/how-to.md#customize-the-page-param))_ | `:page` |
+| `:params` | It can be a `Hash` of params to add to the URL, or a `Proc` that can edit/add/delete the request params _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `{}` |
+| `:fragment` | The arbitrary fragment string (including the "#") to add to the url. _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `''` |
+| `:anchor_string` | The extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [How to customize the link attributes](/docs/how-to.md#customize-the-link-attributes))_ | `nil` |
+| `:cycle` | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` |
+| `:request_path` | Allows overriding the request path for pagination links. Pass the path only (not the absolute url). _(see [Customize the request path](/docs/how-to.md#customize-the-request-path))_ | `nil` |
+| `jsonapi` | Enable `jsonapi` compliance of the pagy query params | `false` |
+| `count_args` | The arguments passed to the `collection.count`. You may want to set it to `[]` in ORMs different than ActiveRecord | [:all] |
There is no specific validation for non-instance variables.
@@ -186,7 +176,7 @@ or `nil`), except the `vars` hash:
| `next` | The next page number or `nil` if there is no next page |
| `vars` | The variables hash |
| `params` | The `:params` variable (`Hash` or `Proc`) |
-| `request_path` | The request path used for pagination helpers. If blank, helpers will use `request.path` |
+| `request_path` | The request path used for pagination helpers. If nil, helpers will use `request.path` |
### Lowest limit analysis
@@ -214,6 +204,8 @@ Which means:
With `size: []` the `series` method returns `[]`
- `in`, `from` and `to` of an empty page are all `0`
- `prev` and `next` of a single page (not necessary an empty one) are both `nil` (i.e. there is no other page)
+
+===
## Exceptions
diff --git a/docs/api/stylesheets.md b/docs/api/stylesheets.md
index f16408111..b318ab56a 100644
--- a/docs/api/stylesheets.md
+++ b/docs/api/stylesheets.md
@@ -7,18 +7,40 @@ image: none
+## Overview
+
For all its own interactive helpers shown above, the pagy gem includes a few stylesheets files that you can download, link or
copy.
!!!warning
-You don't need any stylesheet if you use a frontend extra
-like: [bootstrap](/docs/extras/bootstrap), [bulma](/docs/extras/bulma), [foundation](/docs/extras/foundation), [materialize](/docs/extras/materialize), [semantic](/docs/extras/semantic), [uikit](/docs/extras/uikit)
+You don't need any stylesheet if you use a frontend extra like:
+[bootstrap](/docs/extras/bootstrap), [bulma](/docs/extras/bulma), [foundation](/docs/extras/foundation),
+[materialize](/docs/extras/materialize), [semantic](/docs/extras/semantic), [uikit](/docs/extras/uikit)
!!!
-!!!success
-You can adapt the stylesheets below to anything you need by just editing the content inside the curly brackets, usually leaving
-the rest
-untouched.
+### HTML Structure
+
+In order to ensure a minimalistic valid output, still complete with all the ARIA attributes, we use a single line with the minimum
+number of tags and class attributes that can identify all the parts of the nav bars:
+
+- The output of `pagy_nav` and `pagy_nav_js` are a series of `a` tags inside a wrapper `nav` tag
+- The disabled links are so because they are missing the `href` attributes
+- The `pagy nav` and `pagy nav-js` classes are assigned to the `nav` tag
+- The `current`, `gap` classes are assigned to the specific `a` tags
+
+!!! Notice
+
+- The stylesheets target the disabled `a` tags by using the `pagy a:not([href])` selector
+- You can make the `gap` look like the other pages by removing the `:not(.gap)`
+- You can target the previous and next links by using `pagy a:first-child` and `pagy a:last-child` pseudo classes
+
+!!!
+
+!!!success
+You can totally transform the stylesheets below by just editing the content inside the curly brackets, usually leaving
+the rest untouched.
+
+!!!warning The order of the selectors is important!
!!!
+++ pagy.scss
@@ -41,19 +63,16 @@ stylesheet_path = Pagy.root.join('stylesheets', 'pagy.css')
:::code source="/lib/stylesheets/pagy.css" :::
-+++ pagy.tailwind.scss
++++ pagy.tailwind.css
-[!file](/lib/stylesheets/pagy.tailwind.scss)
+[!file](/lib/stylesheets/pagy.tailwind.css)
```ruby
-stylesheet_path = Pagy.root.join('stylesheets', 'pagy.tailwind.scss')
+stylesheet_path = Pagy.root.join('stylesheets', 'pagy.tailwind.css')
```
-:::code source="/lib/stylesheets/pagy.tailwind.scss" :::
+:::code source="/lib/stylesheets/pagy.tailwind.css" :::
+++
-!!!
-You can also quickly check and interact with all the pagy and extra styles (including the `pagy` and `tailwind` stylesheets above)
-by running the single-file self-contaied app [!file](/apps/pagy_styles.ru)
-!!!
+[!button corners="pill" variant="success" text=":icon-play: Try it now!"](/playground.md#3-demo-app)
diff --git a/docs/assets/nav.html b/docs/assets/nav.html
new file mode 100644
index 000000000..0b149287d
--- /dev/null
+++ b/docs/assets/nav.html
@@ -0,0 +1,11 @@
+
diff --git a/docs/assets/nav.html.erb b/docs/assets/nav.html.erb
index ed497b627..34fddd30c 100644
--- a/docs/assets/nav.html.erb
+++ b/docs/assets/nav.html.erb
@@ -1,41 +1,29 @@
-<%#
- The link variable is set to a proc that returns the link tag (complete with rel and aria-current)
- Usage: link.call( page_number [, text [, extra_attributes_string ]])
--%>
-<% link = pagy_link_proc(pagy) -%>
-