diff --git a/README.md b/README.md index 5b80a2df6..137efb830 100644 --- a/README.md +++ b/README.md @@ -79,11 +79,6 @@ _(see [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start) for more Use the official extras, or write your own in just a few lines. Extras add special options and manage different components, behaviors, Frontend or Backend environments... usually by just requiring them: -### Component Extras - -- [compact](http://ddnexus.github.io/pagy/extras/compact): An alternative UI that combines the pagination feature with the navigation info in one compact element: ![pagy-compact](docs/assets/images/pagy-compact-w.png) -- [responsive](http://ddnexus.github.io/pagy/extras/responsive): On resize, the number of page links adapts in real-time to the available window or container width: ![pagy-responsive](docs/assets/images/pagy-responsive-w.png) - ### Backend Extras - [array](http://ddnexus.github.io/pagy/extras/array): Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding @@ -103,6 +98,13 @@ Use the official extras, or write your own in just a few lines. Extras add speci - [out_of_range](http://ddnexus.github.io/pagy/extras/out_of_range): Allow for easy handling of out of range pages - [trim](http://ddnexus.github.io/pagy/extras/trim): Remove the `page=1` param from the first page link +### Alternative components + +Besides the classic pagination `nav`, Pagy offers a few ready to use alternatives like: + +- [compact nav](http://ddnexus.github.io/pagy/extras/navs#compact-navs): An alternative UI that combines the pagination feature with the navigation info in one compact element: ![pagy-compact](docs/assets/images/pagy-compact-w.png) +- [responsive nav](http://ddnexus.github.io/pagy/extras/navs#responsive-navs): On resize, the number of page links adapts in real-time to the available window or container width: ![pagy-responsive](docs/assets/images/pagy-responsive-w.png) + ## Chat Support and Feedback [Chat on Gitter](https://gitter.im/ruby-pagy/Lobby) diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 36b3ebd95..bf4ff2180 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -36,13 +36,12 @@

{{ site.title | default: site.github.repository_name }}

Array

Bootstrap

Bulma

 -

Compact

Foundation

I18n

Items

Out Of Range

Materialize

 -

Responsive

 +

Navs

Searchkick

Trim

Migration Tips

 diff --git a/docs/api.md b/docs/api.md index 5cb9b4f9a..1b2797ae4 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,7 +8,7 @@ title: API The whole core structure of Pagy is very simple: it is organized around 3 small modules of just ~100 lines of code in total: | Module | Description | Links | -| --------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| ---------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `Pagy` | The small class that keeps track of the variables involved in the pagination | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy.rb), [documentation](api/pagy.md) | | `Pagy::Backend` | The optional module that you can include in your controllers in order to automatically create the Pagy instance | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb), [documentation](api/backend.md) | | `Pagy::Frontend` | The module to include in your views in order to get a few helpers for the HTML output | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb), [documentation](api/frontend.md) | diff --git a/docs/api/frontend.md b/docs/api/frontend.md index a890777d3..0e7b5d1fd 100644 --- a/docs/api/frontend.md +++ b/docs/api/frontend.md @@ -118,7 +118,7 @@ If you need to add some HTML attribute to the page links, you can pass some extr 1. For all pagy objects: set the global variable `:link_extra`: ```ruby - # in the Pagy initializer file + # in the pagy.rb initializer file Pagy::VARS[:link_extra] = 'data-remote="true"' # in any view link = pagy_link_proc(pagy) diff --git a/docs/api/pagy.md b/docs/api/pagy.md index f18a1272a..69c22a743 100644 --- a/docs/api/pagy.md +++ b/docs/api/pagy.md @@ -8,7 +8,7 @@ The scope of the `Pagy` class is keeping track of the all integers and variables ## Synopsys ```ruby -# set global defaults and extra variables typically in the Pagy initializer +# set global defaults and extra variables typically in the pagy.rb initializer # they will get merged with every new Pagy instance Pagy::VARS[:items] = 25 Pagy::VARS[:some_var] = 'default value' @@ -38,7 +38,7 @@ pagy.series The `Pagy::VARS` is a globally available hash used to set defaults variables. It gets merged with (and overridden by) the variables passed with the `new` method every times a `Pagy` instance gets created. -You will typically use it in an initializer file to pass defaults values. For example: +You will typically use it in a `pagy.rb` initializer file to pass defaults values. For example: ```ruby Pagy::VARS[:items] = 25 diff --git a/docs/extras.md b/docs/extras.md index 384605f55..98475ba41 100644 --- a/docs/extras.md +++ b/docs/extras.md @@ -5,24 +5,23 @@ title: Extras Pagy comes with a few optional extensions/extras: -| Extra | Description | Links | -| :------------- | :----------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | -| `array` | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md) | -| `bootstrap` | Nav helper and templates for Bootstrap pagination | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md) | -| `bulma` | Nav helper and templates for [Bulma](https://bulma.io) pagination component | [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb), [documentation](extras/bulma.md) | -| `compact` | An alternative UI that combines the pagination with the nav info in a single compact element | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [documentation](extras/compact.md) | -| `foundation` | Nav helper and templates for Foundation pagination | [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb), [documentation](extras/foundation.md) | -| `i18n` | Use the `I18n` gem instead of the pagy implementation | [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i81n.rb), [documentation](extras/i18n.md) | -| `items` | Allow the client to request a custom number of items per page with a ready to use selector UI | [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb), [documentation](extras/items.md) | -| `materialize` | Nav helper for Materialize CSS [pagination component](https://materializecss.com/pagination.html) | [materialize.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/materialize.rb), [documentation](extras/materialize.md) | -| `out_of_range` | Allow for easy handling of out of range pages | [out_of_range.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/out_of_range.rb), [documentation](extras/out_of_range.md) | -| `responsive` | On resize, the number of page links will adapt in real-time to the available window or container width | [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb), [documentation](extras/responsive.md) | -| `searchkick` | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding | [searchkick.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/searchkick.rb), [documentation](extras/searchkick.md) | -| `trim` | Remove the `page=1` param from links | [trim.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/trim.rb), [documentation](extras/trim.md) | +| Extra | Description | Links | +| :------------- | :------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | +| `array` | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md) | +| `bootstrap` | Nav, responsive and compact helpers and templates for Bootstrap pagination | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md) | +| `bulma` | Nav, responsive and compact helpers and templates for [Bulma](https://bulma.io) pagination component | [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb), [documentation](extras/bulma.md) | +| `foundation` | Nav, responsive and compact helpers and templates for Foundation pagination | [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb), [documentation](extras/foundation.md) | +| `i18n` | Use the `I18n` gem instead of the pagy implementation | [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i81n.rb), [documentation](extras/i18n.md) | +| `items` | Allow the client to request a custom number of items per page with a ready to use selector UI | [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb), [documentation](extras/items.md) | +| `materialize` | Nav, responsive and compact helpers for Materialize CSS [pagination component](https://materializecss.com/pagination.html) | [materialize.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/materialize.rb), [documentation](extras/materialize.md) | +| `navs` | Add responsive and compact generic/unstyled nav helpers | [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb), [documentation](extras/navs.md) | +| `out_of_range` | Allow for easy handling of out of range pages | [out_of_range.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/out_of_range.rb), [documentation](extras/out_of_range.md) | +| `searchkick` | Paginate arrays efficiently avoiding expensive array-wrapping and without overriding | [searchkick.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/searchkick.rb), [documentation](extras/searchkick.md) | +| `trim` | Remove the `page=1` param from links | [trim.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/trim.rb), [documentation](extras/trim.md) | ## Synopsys -Extras are not loaded by default, so you should require them explicitly in your initializer _(see [Configuration](how-to.md#global-configuration))_: +Extras are not loaded by default, so you should require them explicitly in your `pagy.rb` initializer _(see [Configuration](how-to.md#global-configuration))_: ```ruby require 'pagy/extras/bootstrap' @@ -39,14 +38,14 @@ All the added methods are documented in the respective extras. ## Javascript -The `compact`, `items` and `responsive` extras use javascript, so if you use any of them you should load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file, and run `Pagy.init()` on window load. +The `compact`, `items` and `responsive` extras use javascript, so if you use any of them you should load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file, and run `Pagy.init()` on window load. ### In rails apps Add the assets-path in the `pagy.rb` initializer: ```ruby -Rails.application.config.assets.paths << Pagy.root.join('pagy', 'extras', 'javascripts') +Rails.application.config.assets.paths << Pagy.root.join('javascripts') ``` Add the pagy javascript to the `application.js`: diff --git a/docs/extras/bootstrap.md b/docs/extras/bootstrap.md index 267688cbe..42a02c724 100644 --- a/docs/extras/bootstrap.md +++ b/docs/extras/bootstrap.md @@ -3,17 +3,25 @@ title: Bootstrap --- # Bootstrap Extra -This extra adds nav helper and templates for Bootstrap pagination. +This extra adds nav helpers and templates for Bootstrap pagination. ## Synopsys See [extras](../extras.md) for general usage info. +In the `pagy.rb` initializer: + +```ruby +require 'pagy/extras/bootstrap' +``` + Render the navigation links in some view... with a fast helper: ```erb <%== pagy_nav_bootstrap(@pagy) %> +<%== pagy_nav_responsive_bootstrap(@pagy) %> +<%== pagy_nav_compact_bootstrap(@pagy) %> ``` or with a template: @@ -22,18 +30,20 @@ or with a template: <%== render 'pagy/nav_bootstrap', locals: {pagy: @pagy} %> ``` +Configure [javascript](../extras.md#javascript) if you use `pagy_nav_responsive_bootstrap` or `pagy_nav_compact_bootstrap`. + ## Files This extra is composed of 4 files: - [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb) -- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.erb) (optional template) -- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.haml) (optional template) -- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.slim) (optional template) +- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.erb) (optional template) +- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.haml) (optional template) +- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.slim) (optional template) ## Methods -This extra adds one nav helpers to the `Pagy::Frontend` module. You can customize it by overriding it directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding it directly in your own view helper. ### pagy_nav_bootstrap(pagy) @@ -41,6 +51,22 @@ This method is the same as the `pagy_nav`, but customized for Bootstrap. The `nav_bootstrap.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. +### pagy_nav_compact_bootstrap(pagy, ...) + +This method is the same as the `pagy_nav_compact`, but customized for the Bootstrap framework. + +Here is an example: + +![pagy-compact](../assets/images/pagy-compact-g.png) + +See more details in the [compact navs](navs.md#compact-navs) documentation. + +### pagy_nav_responsive_bootstrap(pagy, ...) + +This method is the same as the `pagy_nav_responsive`, but customized for the Bootstrap framework. + +See more details in the [responsive navs](navs.md#responsive-navs) documentation. + ### Optional Template Files See [Using Templates](../how-to.md#using-templates). diff --git a/docs/extras/bulma.md b/docs/extras/bulma.md index c3b15d045..fb35708d1 100644 --- a/docs/extras/bulma.md +++ b/docs/extras/bulma.md @@ -14,6 +14,8 @@ with a fast helper: ```erb <%== pagy_nav_bulma(@pagy) %> +<%== pagy_nav_responsive_bulma(@pagy) %> +<%== pagy_nav_compact_bulma(@pagy) %> ``` or with a template: @@ -22,18 +24,20 @@ or with a template: <%== render 'pagy/nav_bulma', locals: {pagy: @pagy} %> ``` +Configure [javascript](../extras.md#javascript) if you use `pagy_nav_responsive_bulma` or `pagy_nav_compact_bulma`. + ## Files This extra is composed of 4 files: - [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb) -- [nav_bulma.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.erb) (optional template) -- [nav_bulma.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.haml) (optional template) -- [nav_bulma.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.slim) (optional template) +- [nav_bulma.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.erb) (optional template) +- [nav_bulma.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.haml) (optional template) +- [nav_bulma.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.slim) (optional template) ## Methods -This extra adds one nav helpers to the `Pagy::Frontend` module. You can customize it by overriding it directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. ### pagy_nav_bulma(pagy) @@ -41,6 +45,22 @@ This method is the same as the `pagy_nav`, but customized for Bulma. The `nav_bulma.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. +### pagy_nav_compact_bulma(pagy, ...) + +This method is the same as the `pagy_nav_compact`, but customized for the Bulma CSS framework. + +Here is an example: + +![pagy-compact-bulma](../assets/images/pagy-compact-bulma-g.png) + +See more details in the [compact navs](navs.md#compact-navs) documentation. + +### pagy_nav_responsive_bulma(pagy, ...) + +This method is the same as the `pagy_nav_responsive`, but customized for the Bulma CSS framework. + +See more details in the [responsive navs](navs.md#responsive-navs) documentation. + ### Optional Template Files See [Using Templates](../how-to.md#using-templates). diff --git a/docs/extras/compact.md b/docs/extras/compact.md deleted file mode 100644 index d6edef657..000000000 --- a/docs/extras/compact.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Compact ---- -# Compact Extra - -The `compact` extra adds an alternative pagination UI that combines the pagination feature with the navigation info in a single compact element. - -It is especially useful for small size screens, but it is used also with wide layouts since it is __even faster__ than the classic nav of links, because it needs to render just a minimal HTML string. - -## Synopsys - -See [extras](../extras.md) for general usage info. - -Configure [javascript](../extras.md#javascript) - -Then use the responsive helper(s) in any view: - -```erb -<%== pagy_nav_compact(@pagy) %> -<%== pagy_nav_compact_bootstrap(@pagy) %> -<%== pagy_nav_compact_bulma(@pagy) %> -<%== pagy_nav_compact_foundation(@pagy) %> -<%== pagy_nav_compact_materialize(@pagy) %> -``` - -## Files - -This extra is composed of the [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb) and uses the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file. - -## Methods - -This extra adds a couple of nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. - -### pagy_nav_compact(pagy, ...) - -Renders a compact navigation with a style similar to the `pagy_nav` helper. - -It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you should pass an explicit id only if you are going to use more than one `pagy_nav_compact` or `pagy_nav_compact_bootstrap` call in the same line for the same page. - -### pagy_nav_compact_bootstrap(pagy, ...) - -This method is the same as the `pagy_nav_compact`, but customized for the Bootstrap framework. - -Here is an example: - -![pagy-compact](../assets/images/pagy-compact-g.png) - -### pagy_nav_compact_bulma(pagy, ...) - -This method is the same as the `pagy_nav_compact`, but customized for the Bulma CSS framework. - -Here is an example: - -![pagy-compact-bulma](../assets/images/pagy-compact-bulma-g.png) - -### pagy_nav_compact_foundation(pagy, ...) - -This method is the same as the `pagy_nav_compact`, but customized for the Foundation framework. - -### pagy_nav_compact_materialize(pagy, ...) - -This method is the same as the `pagy_nav_compact`, but customized for the Materialize CSS framework. - -Here is an example: - -![pagy-compact-materialize](../assets/images/pagy-compact-materialize-g.png) diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md index d1963b3b7..583fdb86f 100644 --- a/docs/extras/foundation.md +++ b/docs/extras/foundation.md @@ -22,14 +22,16 @@ or with a template: <%== render 'pagy/nav_foundation', locals: {pagy: @pagy} %> ``` +Configure [javascript](../extras.md#javascript) if you use `pagy_nav_responsive_foundation` or `pagy_nav_compact_foundation`. + ## Files This extra is composed of 4 files: - [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb) -- [nav_foundation.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.erb) (optional template) -- [nav_foundation.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.haml) (optional template) -- [nav_foundation.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.slim) (optional template) +- [nav_foundation.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.erb) (optional template) +- [nav_foundation.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.haml) (optional template) +- [nav_foundation.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.slim) (optional template) ## Methods @@ -41,6 +43,18 @@ This method is the same as the `pagy_nav`, but customized for Foundation. The `nav_foundation.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. +### pagy_nav_compact_foundation(pagy, ...) + +This method is the same as the `pagy_nav_compact`, but customized for the Foundation framework. + +See more details in the [compact navs](navs.md#compact-navs) documentation. + +### pagy_nav_responsive_foundation(pagy, ...) + +This method is the same as the `pagy_nav_responsive`, but customized for the Foundation framework. + +See more details in the [responsive navs](navs.md#responsive-navs) documentation. + ### Optional Template Files See [Using Templates](../how-to.md#using-templates). diff --git a/docs/extras/i18n.md b/docs/extras/i18n.md index 9623f2645..12279e133 100644 --- a/docs/extras/i18n.md +++ b/docs/extras/i18n.md @@ -11,8 +11,9 @@ See also [I18n](../api/frontend.md#i18n). See [extras](../extras.md) for general usage info. +In the `pagy.rb` initializer: + ```ruby -# in the Pagy initializer require 'pagy/extras/i18n' ``` diff --git a/docs/extras/items.md b/docs/extras/items.md index eb970479e..e9d6b1098 100644 --- a/docs/extras/items.md +++ b/docs/extras/items.md @@ -9,7 +9,7 @@ Allow the client to request a custom number of items per page with a ready to us See [extras](../extras.md) for general usage info. -In the Pagy initializer: +In the `pagy.rb` initializer: ```ruby require 'pagy/extras/items' @@ -22,7 +22,7 @@ Configure [javascript](../extras.md#javascript) (only if you use the `pagy_items ## Files -This extra is composed of the [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb) and may use the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file. +This extra is composed of the [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb) and may use the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file. ## Variables diff --git a/docs/extras/materialize.md b/docs/extras/materialize.md index 978841150..d5c805619 100644 --- a/docs/extras/materialize.md +++ b/docs/extras/materialize.md @@ -3,7 +3,7 @@ title: Materialize --- # Materialize Extra -This extra adds nav helper and templates for Materialize CSS framework [pagination component](https://materializecss.com/pagination.html). +This extra adds nav helpers for Materialize CSS framework [pagination component](https://materializecss.com/pagination.html). ## Synopsys @@ -14,8 +14,12 @@ with a fast helper: ```erb <%== pagy_nav_materialize(@pagy) %> +<%== pagy_nav_responsive_materialize(@pagy) %> +<%== pagy_nav_compact_materialize(@pagy) %> ``` +Configure [javascript](../extras.md#javascript) if you use `pagy_nav_responsive_materialize` or `pagy_nav_compact_materialize`. + ## Files This extra is composed of 1 file: @@ -24,12 +28,28 @@ This extra is composed of 1 file: ## Methods -This extra adds one nav helpers to the `Pagy::Frontend` module. You can customize it by overriding it directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. ### pagy_nav_materialize(pagy) This method is the same as the `pagy_nav`, but customized for Materialize. +### pagy_nav_compact_materialize(pagy, ...) + +This method is the same as the `pagy_nav_compact`, but customized for the Materialize CSS framework. + +Here is an example: + +![pagy-compact-materialize](../assets/images/pagy-compact-materialize-g.png) + +See more details in the [compact navs](navs.md#compact-navs) documentation. + +### pagy_nav_responsive_materialize(pagy, ...) + +This method is the same as the `pagy_nav_responsive`, but customized for the Materialize CSS framework. + +See more details in the [responsive navs](navs.md#responsive-navs) documentation. + ## Templates -There is currently no template for Materialize. Please, create a Pull Request or an Issue requesting that. +There is currently no template for Materialize. Please, create a Pull Request or an Issue requesting it. diff --git a/docs/extras/navs.md b/docs/extras/navs.md new file mode 100644 index 000000000..7929effb6 --- /dev/null +++ b/docs/extras/navs.md @@ -0,0 +1,110 @@ +--- +title: Navs +--- +# Navs Extra + +This extra adds a couple of nav helpers to the `Pagy::Frontend` module: `pagy_nav_compact` and `pagy_nav_responsive`. These are the generic/unstyled helpers for responsive and compact pagination. + +Other extras (e.g. [bootstrap](bootstrap.md), [bulma](bulma.md), [foundation](foundation.md), [materialize](materialize.md)) provide framework-styled versions of the same `responsive` and `compact` helpers, so you may not need this extra if you use one of those. + +## Synopsys + +See [extras](../extras.md) for general usage info. + +In the `pagy.rb` initializer: + +```ruby +require 'pagy/extras/navs' +``` + +Configure [javascript](../extras.md#javascript). + +## Files + +This extra is composed of the [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb) file and uses the shared [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file. + +# Compact navs + +The `compact` navs (implemented by this extra or by other frontend extras) add an alternative pagination UI that combines the pagination feature with the navigation info in a single compact element. + +It is especially useful for small size screens, but it is used also with wide layouts since it is __even faster__ than the classic nav of links, because it needs to render just a minimal HTML string. + +## Synopsys + +Use the responsive helper(s) in any view: + +```erb +<%== pagy_nav_compact(@pagy) %> +``` + +Other extras provide also the following framework-styled helpers: + +```erb +<%== pagy_nav_compact_bootstrap(@pagy) %> +<%== pagy_nav_compact_bulma(@pagy) %> +<%== pagy_nav_compact_foundation(@pagy) %> +<%== pagy_nav_compact_materialize(@pagy) %> +``` + +## Methods + +### pagy_nav_compact(pagy, ...) + +Renders a compact navigation with a style similar to the `pagy_nav` helper. + +It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you should pass an explicit id only if you are going to use more than one `pagy_nav_compact` or `pagy_nav_compact_bootstrap` call in the same line for the same page. + +# Responsive navs + +With the `responsive` navs (implemented by this extra or by other frontend extras) the number of page links will adapt in real-time to the available window or container width. + +Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav might look like by resizing the browser window at different widths: + +![pagy-responsive](../assets/images/pagy-responsive-g.png) + +## Synopsys + +```ruby +# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance) +Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} +``` + +Use the responsive helper(s) in any view: + +```erb +<%== pagy_nav_responsive(@pagy) %> +``` + +Other extras provide also the following framework-styled helpers: + +```erb +<%== pagy_nav_responsive_bootstrap(@pagy) %> +<%== pagy_nav_responsive_bulma(@pagy) %> +<%== pagy_nav_responsive_foundation(@pagy) %> +<%== pagy_nav_responsive_materialize(@pagy) %> +``` + +## Variables + +### :breakpoints + +The `:breakpoints` variable is a non-core variable used by the `responsive` navs: it allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the Pagy `:size` variables to be applied for that width. + For example: + +```ruby +Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} +``` + +The above statement means that from `0` to `450` pixels width, Pagy will use the `[1,2,2,1]` size, from `450` to `750` it will use the `[3,4,4,3]` size and over `750` it will use the `[4,5,5,4]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section) + +**IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing. + +**Notice**: Each breakpoint added slowers down Pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate. + +## Methods + +### pagy_nav_responsive(pagy, ...) + +Similar to the `pagy_nav` helper, with added responsiveness. + +It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you should pass an explicit id if you are going to use more than one `pagy_nav_responsive` or `pagy_nav_responsive_bootstrap` call in the same line for the same page. diff --git a/docs/extras/out_of_range.md b/docs/extras/out_of_range.md index 1a548cbef..29b82168e 100644 --- a/docs/extras/out_of_range.md +++ b/docs/extras/out_of_range.md @@ -9,7 +9,7 @@ This extra allows for easy handling of out of range pages. It internally rescues See [extras](../extras.md) for general usage info. -In the Pagy initializer: +In the `pagy.rb` initializer: ```ruby require 'pagy/extras/out_of_range' diff --git a/docs/extras/responsive.md b/docs/extras/responsive.md deleted file mode 100644 index e9174e6dd..000000000 --- a/docs/extras/responsive.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Responsive ---- -# Responsive Extra - -With the `responsive` extra the number of page links will adapt in real-time to the available window or container width. - -Here is an example of how the same pagination nav might look like by resizing the browser window at different widths: - -![pagy-responsive](../assets/images/pagy-responsive-g.png) - -## Synopsys - -See [extras](../extras.md) for general usage info. - -```ruby -# in the Pagy initializer -require 'pagy/extras/responsive' - -# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance) -Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} -``` - -Configure [javascript](../extras.md#javascript) - -Then use the responsive helper(s) in any view: - -```erb -<%== pagy_nav_responsive(@pagy) %> -<%== pagy_nav_responsive_bootstrap(@pagy) %> -<%== pagy_nav_responsive_bulma(@pagy) %> -<%== pagy_nav_responsive_foundation(@pagy) %> -<%== pagy_nav_responsive_materialize(@pagy) %> -``` - -## Files - -This extra is composed of the [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb) file and uses the shared [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file. - -## Variables - -### :breakpoints - -The `:breakpoints` variable is a non-core variable added by the `responsive` extra: it allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the Pagy `:size` variables to be applied for that width. - For example: - -```ruby -Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]} -``` - -The above statement means that from `0` to `450` pixels width, Pagy will use the `[1,2,2,1]` size, from `450` to `750` it will use the `[3,4,4,3]` size and over `750` it will use the `[4,5,5,4]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section) - -**IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing. - -**Notice**: Each breakpoint added slowers down Pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate. - -## Methods - -The `reponsive` extra adds an instance method to the `Pagy` class and couple of nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. - -### responsive - -**Notice**: Unless you are going to override a `pagy_nav_responsive*` helpers you can ignore this method. - -This is a `Pagy` instance method that returns the data structure used by the `pagy_nav_responsive*` helpers in order to build the html and the javascript codes needed to make Pagy responsive to different widths. - -### pagy_nav_responsive(pagy, ...) - -Similar to the `pagy_nav` helper, with added responsiveness. - -It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you should pass an explicit id if you are going to use more than one `pagy_nav_responsive` or `pagy_nav_responsive_bootstrap` call in the same line for the same page. - -### pagy_nav_responsive_bootstrap(pagy, ...) - -This method is the same as the `pagy_nav_responsive`, but customized for the Bootstrap framework. - -### pagy_nav_responsive_bulma(pagy, ...) - -This method is the same as the `pagy_nav_responsive`, but customized for the Bulma CSS framework. - -### pagy_nav_responsive_foundation(pagy, ...) - -This method is the same as the `pagy_nav_responsive`, but customized for the Foundation framework. - -### pagy_nav_responsive_materialize(pagy, ...) - -This method is the same as the `pagy_nav_responsive`, but customized for the Materialize CSS framework. diff --git a/docs/how-to.md b/docs/how-to.md index 5b29934a0..8073da28a 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -58,7 +58,7 @@ or with a template: Pagy should work out of the box for most Rack based apps (e.g. Rails) even without configuring anything, however you can configure all its features and all the extras loading a `pagy.rb` initializer file. -You can copy the comprehensive and annotated content of the [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) and uncomment and edit what you may need. The file contains also all the relevant documentation links. +You can copy the comprehensive and annotated [pagy.rb](https://github.com/ddnexus/pagy/blob/master/lib/config/pagy.rb) initializer and uncomment and edit what you may need. The file contains also all the relevant documentation links. ## Environment Assumptions @@ -277,14 +277,13 @@ These helpers take the Pagy object and returns the HTML string with the paginati **Notice**: the [extras](extras.md) add a few other helpers that you can use the same way, in order to get added features (e.g. bootstrap compatibility, responsiveness, compact layouts, etc.) -| Extra | Helpers | -| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| [bootstrap](extras/bootstrap.md) | `pagy_nav_bootstrap` | -| [bulma](extras/bulma.md) | `pagy_nav_bulma` | -| [compact](extras/compact.md) | `pagy_nav_compact`, `pagy_nav_compact_bootstrap`, `pagy_nav_compact_bulma` , `pagy_nav_compact_materialize` | -| [items](extras/items.md) | `pagy_items_selector` | -| [materialize](extras/materialize.md) | `pagy_nav_materialize` | -| [responsive](extras/responsive.md) | `pagy_nav_responsive`, `pagy_nav_responsive_bootstrap`, `pagy_nav_responsive_bulma`, `pagy_nav_responsive_materialize` | +| Extra | Helpers | +| ------------------------------------ | ----------------------------------------------------------------------------------------- | +| [bootstrap](extras/bootstrap.md) | `pagy_nav_bootstrap`, `pagy_nav_responsive_bootstrap`, `pagy_nav_compact_bootstrap` | +| [bulma](extras/bulma.md) | `pagy_nav_bulma`, `pagy_nav_responsive_bulma`, `pagy_nav_compact_bulma` | +| [foundation](extras/foundation.md) | `pagy_nav_foundation`, `pagy_nav_responsive_foundation`, `pagy_nav_compact_foundation` | +| [materialize](extras/materialize.md) | `pagy_nav_materialize`, `pagy_nav_responsive_materialize`, `pagy_nav_compact_materialize` | +| [navs](extras/navs.md) | `pagy_nav_responsive`, `pagy_nav_compact` | Helpers are the preferred choice (over templates) for their performance. If you need to override a `pagy_nav*` helper you can copy and paste it in your helper end edit it there. It is a simple concatenation of strings with a very simple logic. @@ -311,27 +310,27 @@ Pagy provides the replacement templates for the `pagy_nav`, `pagy_nav_bootstrap` They produce exactly the same output of the helpers, but they are slower, so use them only if you need to edit something. In that case customize a copy in your app, then use it as any other template: just remember to pass the `:pagy` local set to the `@pagy` object. Here are the links to the sources to copy: - `pagy` - - [nav.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav.html.erb) - - [nav.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav.html.haml) - - [nav.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav.html.slim) + - [nav.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav.html.erb) + - [nav.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav.html.haml) + - [nav.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav.html.slim) - `bootstrap` - - [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.erb) - - [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.haml) - - [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bootstrap.html.slim) + - [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.erb) + - [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.haml) + - [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.slim) - `bulma` - - [nav_bulma.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.erb) - - [nav_bulma.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.haml) - - [nav_bulma.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_bulma.html.slim) + - [nav_bulma.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.erb) + - [nav_bulma.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.haml) + - [nav_bulma.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bulma.html.slim) - `foundation` - - [nav_foundation.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.erb) - - [nav_foundation.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.haml) - - [nav_foundation.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/templates/nav_foundation.html.slim) + - [nav_foundation.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.erb) + - [nav_foundation.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.haml) + - [nav_foundation.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_foundation.html.slim) If you need to try/compare an unmodified built-in template, you can render it right from the Pagy gem with: ```erb -<%== render file: Pagy.root.join('pagy', 'extras', 'templates', 'nav.html.erb'), locals: {pagy: @pagy} %> -<%== render file: Pagy.root.join('pagy', 'extras', 'templates', 'nav_bootstrap.html.erb'), locals: {pagy: @pagy} %> +<%== render file: Pagy.root.join('templates', 'nav.html.erb'), locals: {pagy: @pagy} %> +<%== render file: Pagy.root.join('templates', 'nav_bootstrap.html.erb'), locals: {pagy: @pagy} %> ``` You may want to read also the [Pagy::Frontend API documentation](api/frontend.md) for complete control over your templates. @@ -373,6 +372,7 @@ That may work very well with static (or almost static) DBs, where there is not m The HTTP pagination headers may be useful for APIs, but they are out of scope for Pagy. However there are a couple of gems that support Pagy and do that for you in a quite automatic way. Please, take a look at: + - [api-pagination](https://github.com/davidcelis/api-pagination) - [pager-api](https://github.com/IcaliaLabs/pager-api) diff --git a/docs/migration-tips.md b/docs/migration-tips.md index a31a6e160..26836f75e 100644 --- a/docs/migration-tips.md +++ b/docs/migration-tips.md @@ -26,7 +26,7 @@ In this phase you will search statements from legacy pagination gems, remove the #### Preparation -- Copy the content of the [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) and rename it `pagy.rb`: you will edit it during the process. +- Copy the [pagy.rb](https://github.com/ddnexus/pagy/blob/master/lib/config/pagy.rb) initializer: you will edit it during the process. - Replace the legacy gem with `gem "pagy"` in the `Gemfile` and `bundle`, or install and require the gem if you don't use bundler. - Ensure that the legacy gem will not get loaded anymore (or it could mask some old statement still in place and not converted) - Add the `include Pagy::Backend` statement to the application controller. @@ -68,7 +68,7 @@ One of the most noticeable difference between the legacy gems and Pagy is that P The other gems are careless about adding methods, scopes, and even configuration settings to them, so you will find different kinds of statements scattered around in your models. You should remove them all and eventually add the equivalent code where it makes sense to Pagy, which of course _is absolutely not_ in the models. -For example, you may want to search for keywords like `per_page`, `per` and such, which are actually configuration settings. They should either go into the Pagy initializer (if they are global to the app) or into the specific `pagy` call in the controller if they are specific to an action. +For example, you may want to search for keywords like `per_page`, `per` and such, which are actually configuration settings. They should either go into the `pagy.rb` initializer (if they are global to the app) or into the specific `pagy` call in the controller if they are specific to an action. If the app used the `page` scope in some of its methods or scopes, that should be removed (including removing the argument used to pass the page number to the scope), leaving the rest of the scope in place. Search where the app uses the already paginated scope in the controllers, and use the scope in a regular `pagy` statement. For example: