-
Notifications
You must be signed in to change notification settings - Fork 395
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
8 changed files
with
376 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| --- | ||
| title: Support | ||
| --- | ||
| # Support Extra | ||
|
|
||
| This extra adds support for features like countless or navless pagination, where you don't need the full link bar but only a simple `next` or `prev` link or no link at all (like for auto-scroll). | ||
|
|
||
| It also provides a couple of helpers to setup you own custom javascript components. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| See [extras](../extras.md) for general usage info. | ||
|
|
||
| In the `pagy.rb` initializer: | ||
|
|
||
| ```ruby | ||
| require 'pagy/extras/support' | ||
| ``` | ||
|
|
||
| ## Support for alternative pagination types and features | ||
|
|
||
| Besides the classic navbar pagination, the `compact` and the `responsive` UI components, Pagy offers a few helpers to support a few alternative types of pagination and related features. | ||
|
|
||
| ### Countless | ||
|
|
||
| You can totally avoid one query per render by using the [countless](countless.md) extra. It has a few limitation, but still supports navbar links (see also [Pagy::Countless](../api/countless.md) for more details). | ||
|
|
||
| ### Navless/incremental | ||
|
|
||
| If you don't need the navbar you can just set the `:size` variable to an empty value and the page links will be skipped from the rendering. That works with `Pagy` and `Pagy:Countless` instances. All the `*nav` helpers will render only the `prev` and `next` links/buttons, allowing for a manual incremental pagination. | ||
|
|
||
| You can also use the `pagy_prev_link` and `pagy_next_link` helpers provided by this extra, mostly useful if you also use the `countless` extra. | ||
|
|
||
| ### Circular/Infinite | ||
|
|
||
| This type of pagination sets the `next` page to `1` when the current page is the last page, allowing an infinite loop through the pages. | ||
|
|
||
| For example, it is often used to show a few suggestions of "similar products" in a horizontal stripe of just a few page of a few items each. Clicking on next will continue to loop through. | ||
|
|
||
| For example: | ||
|
|
||
| ```ruby | ||
| @pagy, @suggestions = Pagy.new(count: 25, items: 5, cycle: true) | ||
| ``` | ||
|
|
||
| Passing a forced `:count` of 25 will generate 5 pages of 5 items each that will always have a next page. Regardless the actual collection count, you will show the first 25 items of the collection, looping in stripes of 5 items each. | ||
|
|
||
| You may want to combine it with something like: | ||
|
|
||
| ```erb | ||
| <%== pagy_next_link(@pagy, 'More...') | ||
| ``` | ||
|
|
||
| ### Auto-scroll | ||
|
|
||
| Pagy supports auto-scroll pagination by providing the `pagy_apply_init_tag` helper, which initializes your custom pagination elements by calling your custom defined javascript function at page load. | ||
|
|
||
| ### Custom UIs | ||
|
|
||
| You can use the `pagy_prev_url` and `pagy_next_url` to build your own links or buttons. Besides, with the `pagy_apply_init_tag` and `pagy_serialized` helpers you can also setup you own custom javascript components. | ||
|
|
||
| ## Methods | ||
|
|
||
| ### pagy_prev_url(pagy) | ||
|
|
||
| Returns the url for the previous page. Useful to build minimalistic UIs that don't use nav bar links (e.g. `countless` extra). | ||
|
|
||
| ### pagy_next_url(pagy) | ||
|
|
||
| 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='') | ||
|
|
||
| Returns the link for the next 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='') | ||
|
|
||
| Returns the link for the next page. It is the same next 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_serialized(pagy) | ||
|
|
||
| Returns a hash with all the instance variables, series, prev_url and next_url of the `pagy` argument. Useful to use in some client-side javascript. It's the default payload of `pagy_apply_init_tag`. | ||
|
|
||
| ### pagy_apply_init_tag(pagy, function, payload=...) | ||
|
|
||
| This is a multi-purpose helper that generates a JSON tag that will be loaded and exececuted by the `Pagy.init` javascript function at document load (see [Javascript](../extras.md#javascript)). | ||
|
|
||
| The method requires a pagy object, a javascript function name and accepts an optional payload (default to the hash returned by `pagy_serialized` method) that will get passed to the function. For example: | ||
|
|
||
| ```ryby | ||
| # this uses the serialized pagy object as the default payload | ||
| pagy_apply_init_tag(@pagy, :myInitFunction) | ||
| # this uses a custom payload | ||
| pagy_apply_init_tag(@pagy, :myOtherFunction, {a: 1, b: 2}) | ||
| ``` | ||
|
|
||
| You should define your functions in the `PagyInit` namespace, as follow, using the payload as needed: | ||
|
|
||
| ```javascript | ||
| PagyInit.myInitFunction = function(payload){ | ||
| console.log(payload); | ||
| doSomethingWith(payload); | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| You can use it to initialize your custom pagination elements. For auto-scroll, you may want to update some client side variable with the `pagy_next_url` at each page load. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # See the Pagy documentation: https://ddnexus.github.io/pagy/extras/support | ||
| # frozen_string_literal: true | ||
|
|
||
| require 'pagy/extras/shared' | ||
|
|
||
| class Pagy | ||
|
|
||
| def to_h | ||
| { count: @count, | ||
| page: @page, | ||
| items: @items, | ||
| pages: @pages, | ||
| last: @last, | ||
| offset: @offset, | ||
| from: @from, | ||
| to: @to, | ||
| prev: @prev, | ||
| next: @next, | ||
| vars: @vars, | ||
| series: series } | ||
| end | ||
|
|
||
| module Frontend | ||
|
|
||
| def pagy_prev_url(pagy) | ||
| pagy_url_for(pagy.prev, pagy) if pagy.prev | ||
| end | ||
|
|
||
| def pagy_next_url(pagy) | ||
| pagy_url_for(pagy.next, pagy) if pagy.next | ||
| end | ||
|
|
||
| def pagy_prev_link(pagy, text = pagy_t('pagy.nav.prev'), link_extra = '') | ||
| pagy.prev ? %(<span class="page prev"><a href="#{pagy_prev_url(pagy)}" rel="next" aria-label="next" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>) | ||
| : %(<span class="page prev disabled">#{text}</span>) | ||
| end | ||
|
|
||
| def pagy_next_link(pagy, text = pagy_t('pagy.nav.next'), link_extra = '') | ||
| pagy.next ? %(<span class="page next"><a href="#{pagy_next_url(pagy)}" rel="next" aria-label="next" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>) | ||
| : %(<span class="page next disabled">#{text}</span>) | ||
| end | ||
|
|
||
| def pagy_serialized(pagy) | ||
| pagy.to_h.merge(prev_url: pagy_prev_url(pagy), next_url: pagy_next_url(pagy)) | ||
| end | ||
|
|
||
| # Multi purpose JSON tag for custom javascript initialization | ||
| def pagy_apply_init_tag(pagy, function, payload=pagy_serialized(pagy)) | ||
| pagy_json_tag(:applyInit, function, payload) | ||
| end | ||
|
|
||
| end | ||
|
|
||
| end |
Oops, something went wrong.