From f7425a5484760c605dae88effcd1cbff29100e6c Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Sat, 6 Apr 2019 17:34:02 +0700 Subject: [PATCH] renamed assets according to helper names; reordered and improved nav docs --- README.md | 8 +- docs/api/frontend.md | 14 +-- ...t-g.png => bootstrap_compact_nav_js-g.png} | Bin ...t-w.png => bootstrap_compact_nav_js-w.png} | Bin ...gy-nav_js-g.png => bootstrap_nav_js-g.png} | Bin ...gy-nav_js-w.png => bootstrap_nav_js-w.png} | Bin ...bulma-g.png => bulma_compact_nav_js-g.png} | Bin ...g.png => materialize_compact_nav_js-g.png} | Bin docs/extras/bootstrap.md | 22 ++--- docs/extras/bulma.md | 22 ++--- docs/extras/foundation.md | 16 ++-- docs/extras/materialize.md | 22 ++--- docs/extras/navs.md | 90 +++++++++--------- docs/extras/semantic.md | 16 ++-- 14 files changed, 98 insertions(+), 112 deletions(-) rename docs/assets/images/{pagy-compact-g.png => bootstrap_compact_nav_js-g.png} (100%) rename docs/assets/images/{pagy-compact-w.png => bootstrap_compact_nav_js-w.png} (100%) rename docs/assets/images/{pagy-nav_js-g.png => bootstrap_nav_js-g.png} (100%) rename docs/assets/images/{pagy-nav_js-w.png => bootstrap_nav_js-w.png} (100%) rename docs/assets/images/{pagy-compact-bulma-g.png => bulma_compact_nav_js-g.png} (100%) rename docs/assets/images/{pagy-compact-materialize-g.png => materialize_compact_nav_js-g.png} (100%) diff --git a/README.md b/README.md index adf614764..3db21344c 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ Use the official extras, or write your own in just a few lines. Extras add speci - [bulma](http://ddnexus.github.io/pagy/extras/bulma): Add nav, nav_js and compact_nav_js helpers for the Bulma CSS [pagination component](https://bulma.io/documentation/components/pagination) - [foundation](http://ddnexus.github.io/pagy/extras/foundation): Add nav, nav_js and compact_nav_js helpers for the Foundation [pagination component](https://foundation.zurb.com/sites/docs/pagination.html) - [materialize](http://ddnexus.github.io/pagy/extras/materialize): Add nav, nav_js and compact_nav_js helpers for the Materialize CSS [pagination component](https://materializecss.com/pagination.html) -- [navs](http://ddnexus.github.io/pagy/extras/navs): Add nav_js and compact_nav_js plain/unstyled helpers +- [navs](http://ddnexus.github.io/pagy/extras/navs): Add nav_js and compact_nav_js unstyled helpers - [semantic](http://ddnexus.github.io/pagy/extras/semantic): Add nav, nav_js and compact_nav_js helpers for the Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html) ### Feature Extras @@ -128,9 +128,9 @@ Use the official extras, or write your own in just a few lines. Extras add speci 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) +- [nav_js](http://ddnexus.github.io/pagy/extras/navs#javascript-navs): A classic looking UI that fits the number of page links to the available width on the client-side:
![bootstrap_nav_js](docs/assets/images/bootstrap_nav_js-w.png) -- [nav_js](http://ddnexus.github.io/pagy/extras/navs#responsive-navs): A classic looking UI that fits the number of page links to the available width on the client-side:
![pagy-nav_js](docs/assets/images/pagy-nav_js-w.png) +- [compact_nav_js](http://ddnexus.github.io/pagy/extras/navs#javascript-compact-navs): An alternative UI that combines the pagination feature with the navigation info in one compact element:
![bootstrap_compact_nav_js](docs/assets/images/bootstrap_compact_nav_js-w.png) ## Resources @@ -138,7 +138,7 @@ Besides the classic pagination `nav`, Pagy offers a few ready to use alternative [![Objects Chart](docs/assets/images/gorails-thumbnail-w360.png)](https://gorails.com/episodes/pagination-with-pagy-gem?autoplay=1) -**Notice**: the `pagy_nav_bootstrap` helper used in the screencast has been renamed as `pagy_bootstrap_nav` in version 2.0 +**Notice**: the `pagy_nav_bootstrap` helper used in the screencast has been renamed as `pagy_bootstrap_nav` since version 2.0 ### Posts and Tutorials diff --git a/docs/api/frontend.md b/docs/api/frontend.md index 018c04025..7130a5673 100644 --- a/docs/api/frontend.md +++ b/docs/api/frontend.md @@ -5,7 +5,7 @@ title: Pagy::Frontend This module provides a few methods to deal with the navigation aspect of the pagination. You will usually include it in some helper module, making its methods available (and overridable) in your views. _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb))_ -You can extend this module with a few more `nav_*` helpers _(see the [extras](../extras.md) doc for more details)_ +You can extend this module with a few more nav helpers _(see the [extras](../extras.md) doc for more details)_ ## Synopsis @@ -186,19 +186,19 @@ Here are a few examples that should cover all the possible confgurations: # IMPORTANT: use only one load statement # load the "de" built-in locale: -Pagy::I18n.load(locale: 'de') +Pagy::I18n.load(locale: 'de') # load the "de" locale defined in the custom file at :filepath: -Pagy::I18n.load(locale: 'de', filepath: 'path/to/pagy-de.yml') +Pagy::I18n.load(locale: 'de', filepath: 'path/to/pagy-de.yml') # load the "de", "en" and "es" built-in locales: # the first :locale will be used also as the default_locale -Pagy::I18n.load({locale: 'de'}, - {locale: 'en'}, +Pagy::I18n.load({locale: 'de'}, + {locale: 'en'}, {locale: 'es'}) - + # load the "en" built-in locale, a custom "es" locale, and a totally custom locale complete with the :pluralize proc: -Pagy::I18n.load({locale: 'en'}, +Pagy::I18n.load({locale: 'en'}, {locale: 'es', filepath: 'path/to/pagy-es.yml'}, {locale: 'xyz', # not built-in filepath: 'path/to/pagy-xyz.yml', diff --git a/docs/assets/images/pagy-compact-g.png b/docs/assets/images/bootstrap_compact_nav_js-g.png similarity index 100% rename from docs/assets/images/pagy-compact-g.png rename to docs/assets/images/bootstrap_compact_nav_js-g.png diff --git a/docs/assets/images/pagy-compact-w.png b/docs/assets/images/bootstrap_compact_nav_js-w.png similarity index 100% rename from docs/assets/images/pagy-compact-w.png rename to docs/assets/images/bootstrap_compact_nav_js-w.png diff --git a/docs/assets/images/pagy-nav_js-g.png b/docs/assets/images/bootstrap_nav_js-g.png similarity index 100% rename from docs/assets/images/pagy-nav_js-g.png rename to docs/assets/images/bootstrap_nav_js-g.png diff --git a/docs/assets/images/pagy-nav_js-w.png b/docs/assets/images/bootstrap_nav_js-w.png similarity index 100% rename from docs/assets/images/pagy-nav_js-w.png rename to docs/assets/images/bootstrap_nav_js-w.png diff --git a/docs/assets/images/pagy-compact-bulma-g.png b/docs/assets/images/bulma_compact_nav_js-g.png similarity index 100% rename from docs/assets/images/pagy-compact-bulma-g.png rename to docs/assets/images/bulma_compact_nav_js-g.png diff --git a/docs/assets/images/pagy-compact-materialize-g.png b/docs/assets/images/materialize_compact_nav_js-g.png similarity index 100% rename from docs/assets/images/pagy-compact-materialize-g.png rename to docs/assets/images/materialize_compact_nav_js-g.png diff --git a/docs/extras/bootstrap.md b/docs/extras/bootstrap.md index 05bb7c472..b725b7018 100644 --- a/docs/extras/bootstrap.md +++ b/docs/extras/bootstrap.md @@ -41,30 +41,28 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_nav_j ## Methods -This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper. ### pagy_bootstrap_nav(pagy) This method is the same as the `pagy_nav`, but customized for Bootstrap. -The `bootstrap_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. +The `bootstrap_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates). -### pagy_bootstrap_compact_nav_js(pagy, ...) -This method is the same as the `pagy_compact_nav_js`, but customized for the Bootstrap framework. +### pagy_bootstrap_nav_js(pagy, ...) -Here is an example: +This method is the same as the `pagy_nav_js`, but customized for the Bootstrap framework. -![pagy-compact](../assets/images/pagy-compact-g.png) +See more details in the [javascript navs](navs.md#javascript-navs) documentation. -See more details in the [javascript compact navs](navs.md#javascript-compact-navs) documentation. -### pagy_bootstrap_nav_js(pagy, ...) +### pagy_bootstrap_compact_nav_js(pagy, ...) -This method is the same as the `pagy_nav_js`, but customized for the Bootstrap framework. +This method is the same as the `pagy_compact_nav_js`, but customized for the Bootstrap framework. -See more details in the [javascript navs](navs.md#javascript-navs) documentation. +Here is an example: -### Optional Template Files +![bootstrap_compact_nav_js](../assets/images/bootstrap_compact_nav_js-g.png) -See [Using Templates](../how-to.md#using-templates). +See more details in the [javascript compact navs](navs.md#javascript-compact-navs) documentation. diff --git a/docs/extras/bulma.md b/docs/extras/bulma.md index cd5bfadaa..6cfce201a 100644 --- a/docs/extras/bulma.md +++ b/docs/extras/bulma.md @@ -41,13 +41,19 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_nav_js` o ## Methods -This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper. ### pagy_bulma_nav(pagy) This method is the same as the `pagy_nav`, but customized for Bulma. -The `bulma_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. +The `bulma_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates). + +### pagy_bulma_nav_js(pagy, ...) + +This method is the same as the `pagy_nav_js`, but customized for the Bulma CSS framework. + +See more details in the [javascript navs](navs.md#javascript-navs) documentation. ### pagy_bulma_compact_nav_js(pagy, ...) @@ -55,16 +61,6 @@ This method is the same as the `pagy_compact_nav_js`, but customized for the Bul Here is an example: -![pagy-compact-bulma](../assets/images/pagy-compact-bulma-g.png) +![bulma_compact_nav_js](../assets/images/bulma_compact_nav_js-g.png) See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation. - -### pagy_bulma_nav_js(pagy, ...) - -This method is the same as the `pagy_nav_js`, but customized for the Bulma CSS framework. - -See more details in the [javascript navs](navs.md#javascript-navs) documentation. - -### Optional Template Files - -See [Using Templates](../how-to.md#using-templates). diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md index 897974f8e..83a7518f6 100644 --- a/docs/extras/foundation.md +++ b/docs/extras/foundation.md @@ -39,19 +39,13 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_nav_ ## Methods -This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper. ### pagy_foundation_nav(pagy) This method is the same as the `pagy_nav`, but customized for Foundation. -The `foundation_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. - -### pagy_foundation_compact_nav_js(pagy, ...) - -This method is the same as the `pagy_compact_nav_js`, but customized for the Foundation framework. - -See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation. +The `foundation_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it. See [Using Templates](../how-to.md#using-templates). ### pagy_foundation_nav_js(pagy, ...) @@ -59,6 +53,8 @@ This method is the same as the `pagy_nav_js`, but customized for the Foundation See more details in the [javascript navs](navs.md#javascript-navs) documentation. -### Optional Template Files +### pagy_foundation_compact_nav_js(pagy, ...) -See [Using Templates](../how-to.md#using-templates). +This method is the same as the `pagy_compact_nav_js`, but customized for the Foundation framework. + +See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation. diff --git a/docs/extras/materialize.md b/docs/extras/materialize.md index bad2a9400..ee0285f98 100644 --- a/docs/extras/materialize.md +++ b/docs/extras/materialize.md @@ -3,7 +3,7 @@ title: Materialize --- # Materialize Extra -This extra adds nav helpers for the Materialize CSS [pagination component](https://materializecss.com/pagination.html). +This extra adds 3 nav helpers for the Materialize CSS [pagination component](https://materializecss.com/pagination.html). ## Synopsis @@ -32,28 +32,24 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_materialize_nav ## Methods -This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper. ### pagy_materialize_nav(pagy) This method is the same as the `pagy_nav`, but customized for Materialize. +### pagy_materialize_nav_js(pagy, ...) + +This method is the same as the `pagy_nav_js`, but customized for the Materialize CSS framework. + +See more details in the [javascript navs](navs.md#javascript-navs) documentation. + ### pagy_materialize_compact_nav_js(pagy, ...) This method is the same as the `pagy_compact_nav_js`, but customized for the Materialize CSS framework. Here is an example: -![pagy-compact-materialize](../assets/images/pagy-compact-materialize-g.png) +![materialize_compact_nav_js](../assets/images/materialize_compact_nav_js-g.png) See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation. - -### pagy_materialize_nav_js(pagy, ...) - -This method is the same as the `pagy_nav_js`, but customized for the Materialize CSS framework. - -See more details in the [javascript navs](navs.md#javascript-navs) documentation. - -## Templates - -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 index 89f718444..267f25189 100644 --- a/docs/extras/navs.md +++ b/docs/extras/navs.md @@ -23,55 +23,20 @@ Configure [javascript](../extras.md#javascript). - [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb) -# Javascript Compact Navs - -The `*_compact_nav_js` 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. - -## Synopsis - -Use the `*_compact_nav_js helpers in any view: - -```erb -<%== pagy_compact_nav_js(@pagy) %> -``` - -Other extras provide also the following framework-styled helpers: - -```erb -<%== pagy_bootstrap_compact_nav_js(@pagy) %> -<%== pagy_bulma_compact_nav_js(@pagy) %> -<%== pagy_foundation_compact_nav_js(@pagy) %> -<%== pagy_materialize_compact_nav_js(@pagy) %> -<%== pagy_semantic_compact_nav_js(@pagy) %> -``` - -## Methods - -### pagy_compact_nav_js(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 _must_ pass an explicit id if you are going to use more than one `pagy_*_nav_js` or `pagy_*_compact_nav_js` call in the same line for the same page. - -**Notice**: passing an explicit id is also a bit faster than having pagy to generate one. - # Javascript Navs -With the `*_nav_js` 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. +The `*_nav_js` (implemented by this extra or by other frontend extras) looks like a normal `*_nav` but has a a few added features: + +1. It is rendered on the client side +2. It has optional added responsiveness +3. It is a lot faster on modern environments _(see [Maximizing Performance](../how-to.md#maximizing-performance))_ Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav might look like by resizing the browser window/container at different widths: -![pagy-nav_js](../assets/images/pagy-nav_js-g.png) +![bootstrap_nav_js](../assets/images/bootstrap_nav_js-g.png) ## Synopsis -```ruby -# set your default custom sizes (width/size pairs) globally (it can be overridden per Pagy instance) -Pagy::VARS[:sizes] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] } -``` - Use the `*_nav_js` helpers in any view: ```erb @@ -96,7 +61,7 @@ Other extras provide also the following framework-styled helpers: ### :sizes -The `:sizes` variable is an optional non-core variable used by the `*_nav_js` navs. If defined, it allows you to control multipe pagy `:size` at different widths; if `nil` the `*_nav_js` will behave exactly as a static `*_nav` respecting the single `:size` variable _(see also the [pagy variables](../api/pagy.md#other-variables) doc for details)_. +The `:sizes` variable is an optional non-core variable used by the `*_nav_js` navs. If it's defined, it allows you to control multiple pagy `:size` at different widths. If it's `nil`, the `*_nav_js` will behave exactly as a static `*_nav` respecting the single `:size` variable _(see also the [pagy variables](../api/pagy.md#other-variables) doc for details)_. The `:sizes` variable is a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width. @@ -136,8 +101,47 @@ Here is what you should consider/ensure: ### pagy_nav_js(pagy, ...) -Similar to the `pagy_nav` helper, with added responsiveness. +Similar to the `pagy_nav` helper, but faster and rendered on the client side, 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 _must_ pass an explicit id if you are going to use more than one `pagy_*_nav_js` or `pagy_*_compact_nav_js` call in the same line for the same file. **Notice**: passing an explicit id is also a bit faster than having pagy to generate one. + + +# Javascript Compact Navs + +The `*_compact_nav_js` navs (implemented by this extra or by other frontend extras) adds an alternative pagination UI that combines the pagination feature with the navigation info in a single compact element. + +It is even faster and lighter than the `*_nav_js` on modern environments _(see [Maximizing Performance](../how-to.md#maximizing-performance))_, so it is recommended when youo care about efficiency and server load. + +Here is a screenshot (from the `bootstrap`extra): + +![bootstrap_compact_nav_js](../assets/images/bootstrap_compact_nav_js-g.png) + +## Synopsis + +Use the `*_compact_nav_js helpers in any view: + +```erb +<%== pagy_compact_nav_js(@pagy) %> +``` + +Other extras provide also the following framework-styled helpers: + +```erb +<%== pagy_bootstrap_compact_nav_js(@pagy) %> +<%== pagy_bulma_compact_nav_js(@pagy) %> +<%== pagy_foundation_compact_nav_js(@pagy) %> +<%== pagy_materialize_compact_nav_js(@pagy) %> +<%== pagy_semantic_compact_nav_js(@pagy) %> +``` + +## Methods + +### pagy_compact_nav_js(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 _must_ pass an explicit id if you are going to use more than one `pagy_*_nav_js` or `pagy_*_compact_nav_js` call in the same line for the same page. + +**Notice**: passing an explicit id is also a bit faster than having pagy to generate one. diff --git a/docs/extras/semantic.md b/docs/extras/semantic.md index 5d9ed3b03..b60b34ecb 100644 --- a/docs/extras/semantic.md +++ b/docs/extras/semantic.md @@ -3,7 +3,7 @@ title: Semantic UI --- # Semantic UI Extra -This extra adds nav helper and templates for Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html#pagination). +This extra adds 3 nav helpers for Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html#pagination). ## Synopsis @@ -30,24 +30,20 @@ with a fast helper: ## Methods -This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by overriding them directly in your own view helper. +This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize them by direct overriding in your own view helper. ### pagy_semantic_nav(pagy) This method is the same as the `pagy_nav`, but customized for Semantic UI. -### pagy_semantic_compact_nav_js(pagy, ...) - -This method is the same as the `pagy_compact_nav_js`, but customized for the Semantic UI framework. - -See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation. - ### pagy_semantic_nav_js(pagy, ...) This method is the same as the `pagy_nav_js`, but customized for the Semantic UI framework. See more details in the [javascript navs](navs.md#javascript-navs) documentation. -## Templates +### pagy_semantic_compact_nav_js(pagy, ...) -There is currently no template for Semantic UI. Please, create a Pull Request or an Issue requesting that. +This method is the same as the `pagy_compact_nav_js`, but customized for the Semantic UI framework. + +See more details in the [compact_navs_js](navs.md#javascript-compact-navs) documentation.