From a2b915e923cd523e1851d47cd68ea40b78b9054b Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Tue, 11 Feb 2020 16:05:54 +0700 Subject: [PATCH] reorganization of Javascript documentation --- README.md | 4 +- docs/_layouts/default.html | 3 +- docs/api/frontend.md | 10 +- docs/api/javascript.md | 295 +++++++++++++++++++++++++++++++++++++ docs/extras.md | 122 +-------------- docs/extras/bootstrap.md | 14 +- docs/extras/bulma.md | 12 +- docs/extras/foundation.md | 10 +- docs/extras/items.md | 2 +- docs/extras/materialize.md | 12 +- docs/extras/navs.md | 132 +---------------- docs/extras/semantic.md | 8 +- docs/extras/uikit.md | 9 +- docs/how-to.md | 2 +- 14 files changed, 333 insertions(+), 302 deletions(-) create mode 100644 docs/api/javascript.md diff --git a/README.md b/README.md index 5df26ba5f..7ced1595c 100644 --- a/README.md +++ b/README.md @@ -138,9 +138,9 @@ Use the official extras, or write your own in just a few lines. Extras add speci Besides the classic pagination offered by the `pagy_nav` helpers, you can use a couple of more performant alternatives: -- [pagy_nav_js](http://ddnexus.github.io/pagy/extras/navs#javascript-navs): A faster and lighter classic looking UI, rendered on the client side with optional responsiveness:
![bootstrap_nav_js](docs/assets/images/bootstrap_nav_js-w.png) +- [pagy_nav_js](http://ddnexus.github.io/pagy/api/javascript#javascript-navs): A faster and lighter classic looking UI, rendered on the client side with optional responsiveness:
![bootstrap_nav_js](docs/assets/images/bootstrap_nav_js-w.png) -- [pagy_combo_nav_js](http://ddnexus.github.io/pagy/extras/navs#javascript-combo-navs): The fastest and lightest alternative UI _(48x faster, 48x lighter and 2,270x more efficient than Kaminari)_ that combines navigation and pagination info in a single compact element:
![bootstrap_combo_nav_js](docs/assets/images/bootstrap_combo_nav_js-w.png) +- [pagy_combo_nav_js](http://ddnexus.github.io/pagy/api/javascript#javascript-combo-navs): The fastest and lightest alternative UI _(48x faster, 48x lighter and 2,270x more efficient than Kaminari)_ that combines navigation and pagination info in a single compact element:
![bootstrap_combo_nav_js](docs/assets/images/bootstrap_combo_nav_js-w.png) ### Related Projects diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 71d8c9e21..c743c6e0a 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -89,7 +89,7 @@

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

© 2017-2019 Domizio Demichelis — MIT License

+

© 2017-2020 Domizio Demichelis — MIT License

@@ -101,6 +101,7 @@

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

Pagy::Backend

Pagy::Frontend

Pagy::Countless

 +

Javascript

Extras

Arel

Array

 diff --git a/docs/api/frontend.md b/docs/api/frontend.md index f7ecf4105..4b68608c3 100644 --- a/docs/api/frontend.md +++ b/docs/api/frontend.md @@ -94,13 +94,13 @@ This method returns a specialized proc that you call to produce the page links. Here is how you should use it: in your helper or template call the method to get the proc (just once): -```ruby +``` link = pagy_link_proc( pagy [, extra_attributes_string ] ) ``` Then call the `"link"` proc to get the links (multiple times): -```ruby +``` link.call( page_number [, text [, extra_attributes_string ] ] ) ``` @@ -178,7 +178,7 @@ If you need to load different built-in locales, and/or custom dictionary files o Here are a few examples that should cover all the possible confgurations: -```rb +```ruby # IMPORTANT: use only one load statement # load the "de" built-in locale: @@ -198,7 +198,7 @@ Pagy::I18n.load({locale: 'en'}, {locale: 'es', filepath: 'path/to/pagy-es.yml'}, {locale: 'xyz', # not built-in filepath: 'path/to/pagy-xyz.yml', - pluralize: lambda{|count| ... } ) + pluralize: lambda{|count| ... }}) ``` **Notice**: You should use a custom `:pluralize` proc only for pluralization types not included in the built-in [p11n.rb](https://github.com/ddnexus/pagy/blob/master/lib/locales/utils/p11n.rb) @@ -208,7 +208,7 @@ Pagy::I18n.load({locale: 'en'}, When you configure multiple locales, you must also set the locale for each 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: -```rb +```ruby before_action { @pagy_locale = params[:locale] || 'en' } ``` diff --git a/docs/api/javascript.md b/docs/api/javascript.md new file mode 100644 index 000000000..cd64c6ee9 --- /dev/null +++ b/docs/api/javascript.md @@ -0,0 +1,295 @@ +--- +title: Javascript +--- + +# Javascript + +## Overview + +A few helpers use javascript, and they are clearly recognizable by the `js` suffix: + +- `pagy*_nav_js` +- `pagy*_combo_nav_js` +- `pagy_items_selector_js` + +If you use any of them you should follow this documentation, if not, consider that Javascript is not used anywhere else, so you can skip this. + +## Usage + +Load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file, and run `Pagy.init()` on window-load and eventually on [AJAX-load](#using-ajax). + +**CAVEATS** +- If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it. +- See also [Preventing crawlers to follow look-alike links](../how-to.md#preventing-crawlers-to-follow-look-alike-links) + +### Add the oj gem + +Although it's not a requirement, if you are on ruby 2.0+ (not jruby), and if you use any `*_nav_js` helper, you should add the `gem 'oj'` to your Gemfile. When available, Pagy will automatically use it to boost the performance. (Notice: It does nothing for normal, non-js helpers.) + +### In rails apps + +#### With the asset pipeline + +If your app uses the sprocket asset-pipeline, add the assets-path in the `pagy.rb` initializer: + +```ruby +Rails.application.config.assets.paths << Pagy.root.join('javascripts') +``` + +Add the pagy javascript to the `application.js`: + +```js +//= require pagy +``` + +Add an event listener for turbolinks: + +```js +window.addEventListener("turbolinks:load", Pagy.init); +``` + +or a generic one if your app doesn't use turbolinks: +```js +window.addEventListener("load", Pagy.init); +``` + +#### With Webpacker + +If your app uses Webpacker, ensure that the webpacker `erb` loader is installed: + +```sh +bundle exec rails webpacker:install:erb +``` + +Then create a `pagy.js.erb` in order to render the content of `pagy.js` and add the event listener into it: + +```erb +<%= Pagy.root.join('javascripts', 'pagy.js').read %> +window.addEventListener("load", Pagy.init) +``` + +and import it in `app/javascript/application.js`: + +```js +import '../src/javascripts/pagy.js.erb' +``` + +**Notice**: + +- You may want to use `turbolinks:load` if your app uses turbolinks despite webpacker +- or you may want just `export { Pagy }` from the `pagy.js.erb` file and import and use it somewhere else. +- You may want to expose the `Pagy` namespace, if you need it available elsewhere (e.g. in js.erb templates): + ```js + global.Pagy = Pagy + ``` + +### In non-rails apps + +Ensure the `pagy/extras/javascripts/pagy.js` script gets served with the page. + +Add an event listener like: + +```js +window.addEventListener('load', Pagy.init); +``` + +or execute the `Pagy.init()` using jQuery: + +```js +$( window ).load(function() { + Pagy.init() +}); +``` + +# Javascript Navs + +The following `pagy*_nav_js` helpers: + +- `pagy_nav_js` +- `pagy_bootstrap_nav_js` +- `pagy_bulma_nav_js` +- `pagy_foundation_nav_js` +- `pagy_materialize_nav_js` +- `pagy_semantic_nav_js` + +look like a normal `pagy*_nav` but have a few added features: + +1. Client-side rendering +2. Optional responsiveness +3. Better performance and resource usage _(see [Maximizing Performance](../how-to.md#maximizing-performance))_ + +Here is a screenshot (from the `bootstrap`extra) showing responsiveness at different widths: + +![bootstrap_nav_js](../assets/images/bootstrap_nav_js-g.png) + +## Synopsis + +See [extras](../extras.md) for general usage info. + +In the `pagy.rb` initializer, require the specific extra for the style you want to use: + +```ruby +# 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/semantic' +require 'pagy/extras/uikit' +``` + +Use the `pagy*_nav_js` helpers in any view: + +```erb +<%== pagy_nav_js(@pagy) %> +<%== pagy_bootstrap_nav_js(@pagy) %> +<%== pagy_bulma_nav_js(@pagy) %> +<%== pagy_foundation_nav_js(@pagy) %> +<%== pagy_materialize_nav_js(@pagy) %> +<%== pagy_semantic_nav_js(@pagy) %> +``` + +## Variables + +| Variable | Description | Default | +|:---------|:------------------------------------------------------------------|:--------| +| `:steps` | Hash variable to control multipe pagy `:size` at different widths | `false` | + +### :steps + +The `:steps` is an optional non-core variable used by the `pagy*_nav_js` navs. If it's `false`, the `pagy*_nav_js` will behave exactly as a static `pagy*_nav` respecting the single `:size` variable, just faster and lighter. If it's defined as a hash, it allows you to control multiple pagy `:size` at different widths. + +You can set the `:steps` as a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width. + +As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance. + +For example: + +```ruby +# globally +Pagy::VARS[:steps] = { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] } + +# or for a single instance +pagy, records = pagy(collection, steps: { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] } ) + +# or use the :size as any static pagy*_nav +pagy, records = pagy(collection, steps: false ) + +``` + +The above statement means that from `0` to `540` pixels width, Pagy will use the `[2,3,3,2]` size, from `540` to `720` it will use the `[3,5,5,3]` size and over `720` it will use the `[5,7,7,5]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section). + +**IMPORTANT**: You can set any number of steps with any arbitrary width/size. The only requirement is that the `:steps` hash must contain always the `0` width or a `Pagy::VariableError` exception will be raised. + +#### Setting the right sizes + +Setting the widths and sizes can create a nice transition between widths or some apparently erratic behavior. + +Here is what you should consider/ensure: + +1. The pagy size changes in discrete `:steps`, defined by the width/size pairs. + +2. The automatic transition from one size to another depends on the width available to the pagy nav. That width is the _internal available width_ of its container (excluding eventual horizontal padding). + +3. You should ensure that - for each step - each pagy `:size` produces a nav that can be contained in its width. + +4. You should ensure that the minimum internal width for the container div be equal (or a bit bigger) to the smaller positive width. (`540` pixels in our previous example). + +5. If the container width snaps to specific widths in discrete steps, you should sync the quantity and widths of the pagy `:steps` to the quantity and internal widths for each discrete step of the container. + +#### Javascript Caveats + +In case of a window resize, the `pagy_*nav_js` elements on the page are re-rendered (when the container width changes), however if the container width changes in any other way that does not involve a window resize, then you should re-render the pagy element explicitly. For example: + +```js +document.getElementById('my-pagy-nav-js').render(); +``` + +# Javascript Combo Navs + +The following `pagy*_combo_nav_js` offer an alternative pagination UI that combines navigation and pagination info in a single compact element: + +- `pagy_combo_nav_js` +- `pagy_bootstrap_combo_nav_js` +- `pagy_bulma_combo_nav_js` +- `pagy_foundation_combo_nav_js` +- `pagy_materialize_combo_nav_js` +- `pagy_semantic_combo_nav_js` + +They are the fastest and lighter `nav` on modern environments, recommended when you care about efficiency and server load _(see [Maximizing Performance](../how-to.md#maximizing-performance))_. + +Here is a screenshot (from the `bootstrap` extra): + +![bootstrap_combo_nav_js](../assets/images/bootstrap_combo_nav_js-g.png) + +## Synopsis + +See [extras](../extras.md) for general usage info. + +In the `pagy.rb` initializer, require the specific extra for the style you want to use: + +```ruby +# 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/semantic' +require 'pagy/extras/uikit' +``` + +Use the `pagy*_combo_nav_js` helpers in any view: + +```erb +<%== pagy_combo_nav_js(@pagy) %> +<%== pagy_bootstrap_combo_nav_js(@pagy) %> +<%== pagy_bulma_combo_nav_js(@pagy) %> +<%== pagy_foundation_combo_nav_js(@pagy) %> +<%== pagy_materialize_combo_nav_js(@pagy) %> +<%== pagy_semantic_combo_nav_js(@pagy) %> +``` + +## Methods + +### *_nav_js(pagy, ...) + +All `*_nav_js` methods can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id generation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `*_js` call in the same line for the same file. + +**Notice**: passing an explicit id is also a bit faster than having pagy to generate one. + +# Using AJAX + +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 a `pagy_bootstrap_nav_js` AJAX-render: + +`pagy_remote_nav_js` controller action (notice the `link_extra` to enable AJAX): + +```ruby +def pagy_remote_nav_js + @pagy, @records = pagy(Product.all, link_extra: 'data-remote="true"') +end +``` + +`pagy_remote_nav_js.html.erb` template for non-AJAX render (first page-load): + +```erb +
+ <%= render partial: 'nav_js' %> +
+``` + +`_nav_js.html.erb` partial shared for AJAX and non-AJAX rendering: + +```erb +<%== pagy_bootstrap_nav_js(@pagy) %> +``` + +`pagy_remote_nav_js.js.erb` javascript template used for AJAX: + +```erb +$('#container').html("<%= j(render 'nav_js')%>"); +Pagy.init(document.getElementById('container')); +``` + +**IMPORTANT**: The `document.getElementById('container')` argument will re-init the pagy elements just AJAX-rendered in the container div. If you miss it it will not work with AJAX. diff --git a/docs/extras.md b/docs/extras.md index fb05fc619..053a5850f 100644 --- a/docs/extras.md +++ b/docs/extras.md @@ -46,7 +46,7 @@ A few extras require the [pagy/extras/shared](https://github.com/ddnexus/pagy/bl **Notice**: All the other added methods are documented in the respective extras doc. -## Javascript +## Javascript Helpers A few helpers use javascript, and they are clearly recognizable by the `js` suffix: @@ -54,122 +54,4 @@ A few helpers use javascript, and they are clearly recognizable by the `js` suff - `pagy*_combo_nav_js` - `pagy_items_selector_js` -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 and eventually on [AJAX-load](#using-ajax-with-javascript-enabled-helpers). - -**CAVEATS** -- If you override any `*_js` helper, ensure to override/enforce the relative javascript function, even with a simple copy and paste. If the relation between the helper and the function changes in a next release (e.g. arguments, naming, etc.), your app will still work with your own overriding even without the need to update it. -- See also [Preventing crawlers to follow look-alike links](how-to.md#preventing-crawlers-to-follow-look-alike-links) - -### Add the oj gem - -Although it's not a requirement, if you are on ruby 2.0+ (not jruby), and if you use any `*_nav_js` helper, you should add the `gem 'oj'` to your Gemfile. When available, Pagy will automatically use it to boost the performance. (Notice: It does nothing for normal, non-js helpers.) - -### In rails apps - -#### With the asset pipeline - -If your app uses the sprocket asset-pipeline, add the assets-path in the `pagy.rb` initializer: - -```ruby -Rails.application.config.assets.paths << Pagy.root.join('javascripts') -``` - -Add the pagy javascript to the `application.js`: - -```js -//= require pagy -``` - -Add an event listener for turbolinks: - -```js -window.addEventListener("turbolinks:load", Pagy.init); -``` - -or a generic one if your app doesn't use turbolinks: -```js -window.addEventListener("load", Pagy.init); -``` - -#### With Webpacker - -If your app uses Webpacker, ensure that the webpacker `erb` loader is installed: - -```sh -bundle exec rails webpacker:install:erb -``` - -Then create a `pagy.js.erb` in order to render the content of `pagy.js` and add the event listener into it: - -```erb -<%= Pagy.root.join('javascripts', 'pagy.js').read %> -window.addEventListener("load", Pagy.init) -``` - -and import it in `app/javascript/application.js`: - -```js -import '../src/javascripts/pagy.js.erb' -``` - -**Notice**: - -- You may want to use `turbolinks:load` if your app uses turbolinks despite webpacker -- or you may want just `export { Pagy }` from the `pagy.js.erb` file and import and use it somewhere else. -- You may want to expose the `Pagy` namespace, if you need it available elsewhere (e.g. in js.erb templates): - ```js - global.Pagy = Pagy - ``` - -### In non-rails apps - -Ensure the `pagy/extras/javascripts/pagy.js` script gets served with the page. - -Add an event listener like: - -```js -window.addEventListener('load', Pagy.init); -``` - -or execute the `Pagy.init()` using jQuery: - -```js -$( window ).load(function() { - Pagy.init() -}); -``` - -### Using AJAX with javascript-enabled helpers - -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 a `pagy_bootstrap_nav_js` AJAX-render: - -`pagy_remote_nav_js` controller action (notice the `link_extra` to enable AJAX): - -```ruby -def pagy_remote_nav_js - @pagy, @records = pagy(Product.all, link_extra: 'data-remote="true"') -end -``` - -`pagy_remote_nav_js.html.erb` template for non-AJAX render (first page-load): - -```erb -
- <%= render partial: 'nav_js' %> -
-``` - -`_nav_js.html.erb` partial shared for AJAX and non-AJAX rendering: - -```erb -<%== pagy_bootstrap_nav_js(@pagy) %> -``` - -`pagy_remote_nav_js.js.erb` javascript template used for AJAX: - -```erb -$('#container').html("<%= j(render 'nav_js')%>"); -Pagy.init(document.getElementById('container')); -``` - -Notice the `document.getElementById('container')` argument: that will re-init the pagy elements just AJAX-rendered in the container div. +See [Javascript](api/javascript.md) diff --git a/docs/extras/bootstrap.md b/docs/extras/bootstrap.md index 4d573ef9c..b59405da5 100644 --- a/docs/extras/bootstrap.md +++ b/docs/extras/bootstrap.md @@ -30,7 +30,7 @@ or with a template: <%== render partial: 'pagy/bootstrap_nav', locals: {pagy: @pagy} %> ``` -Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_nav_js` or `pagy_bootstrap_combo_nav_js`. +See [Javascript](../api/javascript.md) if you use `pagy_bootstrap_nav_js` or `pagy_bootstrap_combo_nav_js`. ## Files @@ -52,17 +52,11 @@ The `bootstrap_nav.*` templates produce the same output, and can be used as an e ### pagy_bootstrap_nav_js(pagy, ...) -This method is the same as the `pagy_nav_js`, but customized for the Bootstrap framework. - -See more details in the [javascript navs](navs.md#javascript-navs) documentation. - +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_bootstrap_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the Bootstrap framework. - -Here is an example: - ![bootstrap_combo_nav_js](../assets/images/bootstrap_combo_nav_js-g.png) -See more details in the [javascript compact navs](navs.md#javascript-combo-navs) documentation. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. + diff --git a/docs/extras/bulma.md b/docs/extras/bulma.md index d90a97611..8638a47d1 100644 --- a/docs/extras/bulma.md +++ b/docs/extras/bulma.md @@ -30,7 +30,7 @@ or with a template: <%== render partial: 'pagy/bulma_nav', locals: {pagy: @pagy} %> ``` -Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_nav_js` or `pagy_bulma_combo_nav_js`. +See [Javascript](../api/javascript.md) if you use `pagy_bulma_nav_js` or `pagy_bulma_combo_nav_js`. ## Files @@ -51,16 +51,10 @@ The `bulma_nav.*` templates produce the same output, and can be used as an easie ### 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. +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_bulma_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the Bulma CSS framework. - -Here is an example: - ![bulma_combo_nav_js](../assets/images/bulma_combo_nav_js-g.png) -See more details in the [compact_navs_js](navs.md#javascript-combo-navs) documentation. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md index 537919ebd..228e42608 100644 --- a/docs/extras/foundation.md +++ b/docs/extras/foundation.md @@ -30,7 +30,7 @@ or with a template: <%== render partial: 'pagy/foundation_nav', locals: {pagy: @pagy} %> ``` -Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_nav_js` or `pagy_foundation_combo_nav_js`. +See [Javascript](../api/javascript.md) if you use `pagy_foundation_nav_js` or `pagy_foundation_combo_nav_js`. ## Files @@ -51,12 +51,8 @@ The `foundation_nav.*` templates produce the same output, and can be used as an ### pagy_foundation_nav_js(pagy, ...) -This method is the same as the `pagy_nav_js`, but customized for the Foundation framework. - -See more details in the [javascript navs](navs.md#javascript-navs) documentation. +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_foundation_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the Foundation framework. - -See more details in the [compact_navs_js](navs.md#javascript-combo-navs) documentation. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. diff --git a/docs/extras/items.md b/docs/extras/items.md index 716f4a081..ff3904c66 100644 --- a/docs/extras/items.md +++ b/docs/extras/items.md @@ -20,7 +20,7 @@ Pagy::VARS[:items_param] = :custom_param # default :items Pagy::VARS[:max_items] = 100 # default ``` -Configure [javascript](../extras.md#javascript) (only if you use the `pagy_items_selector_js` UI) +See [Javascript](../api/javascript.md) (only if you use the `pagy_items_selector_js` UI) ## Files diff --git a/docs/extras/materialize.md b/docs/extras/materialize.md index 61ee51144..4d795172d 100644 --- a/docs/extras/materialize.md +++ b/docs/extras/materialize.md @@ -24,7 +24,7 @@ with a fast helper: <%== pagy_materialize_combo_nav_js(@pagy) %> ``` -Configure [javascript](../extras.md#javascript) if you use `pagy_materialize_nav_js` or `pagy_materialize_combo_nav_js`. +See [Javascript](../api/javascript.md) if you use `pagy_materialize_nav_js` or `pagy_materialize_combo_nav_js`. ## Files @@ -40,16 +40,10 @@ 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. +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_materialize_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the Materialize CSS framework. - -Here is an example: - ![materialize_combo_nav_js](../assets/images/materialize_combo_nav_js-g.png) -See more details in the [compact_navs_js](navs.md#javascript-combo-navs) documentation. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. diff --git a/docs/extras/navs.md b/docs/extras/navs.md index f4287669c..a192f3007 100644 --- a/docs/extras/navs.md +++ b/docs/extras/navs.md @@ -17,142 +17,26 @@ In the `pagy.rb` initializer: require 'pagy/extras/navs' ``` -Configure [javascript](../extras.md#javascript). - -## Files - -- [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb) - -# Javascript Navs - -The `pagy*_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 offers optional responsiveness -3. It is faster and lighter than a simple `pagy*_nav` helper _(see [Maximizing Performance](../how-to.md#maximizing-performance))_ - -Here is a screenshot (from the `bootstrap`extra) showing responsiveness at different widths: - -![bootstrap_nav_js](../assets/images/bootstrap_nav_js-g.png) - -## Synopsis - -Use the `pagy*_nav_js` helpers in any view: +Render the navigation links in some view... +with a fast helper: ```erb <%== pagy_nav_js(@pagy) %> +<%== pagy_combo_nav_js(@pagy) %> ``` -Other extras provide also the following framework-styled helpers: - -```erb -<%== pagy_bootstrap_nav_js(@pagy) %> -<%== pagy_bulma_nav_js(@pagy) %> -<%== pagy_foundation_nav_js(@pagy) %> -<%== pagy_materialize_nav_js(@pagy) %> -<%== pagy_semantic_nav_js(@pagy) %> -``` - -## Variables - -| Variable | Description | Default | -|:---------|:------------------------------------------------------------------|:--------| -| `:steps` | Hash variable to control multipe pagy `:size` at different widths | `false` | - -### :steps - -The `:steps` is an optional non-core variable used by the `pagy*_nav_js` navs. If it's `false`, the `pagy*_nav_js` will behave exactly as a static `pagy*_nav` respecting the single `:size` variable, just faster and lighter. If it's defined as a hash, it allows you to control multiple pagy `:size` at different widths. - -You can set the `:steps` as a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width. - -As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance. - -For example: - -```ruby -# globally -Pagy::VARS[:steps] = { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] } - -# or for a single instance -pagy, records = pagy(collection, steps: { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] } ) - -# or use the :size as any static pagy*_nav -pagy, records = pagy(collection, steps: false ) - -``` - -The above statement means that from `0` to `540` pixels width, Pagy will use the `[2,3,3,2]` size, from `540` to `720` it will use the `[3,5,5,3]` size and over `720` it will use the `[5,7,7,5]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section). - -**IMPORTANT**: You can set any number of steps with any arbitrary width/size. The only requirement is that the `:steps` hash must contain always the `0` width or a `Pagy::VariableError` exception will be raised. - -#### Setting the right sizes - -Setting the widths and sizes can create a nice transition between widths or some apparently erratic behavior. +See [Javascript](../api/javascript.md). -Here is what you should consider/ensure: - -1. The pagy size changes in discrete `:steps`, defined by the width/size pairs. - -2. The automatic transition from one size to another depends on the width available to the pagy nav. That width is the _internal available width_ of its container (excluding eventual horizontal padding). - -3. You should ensure that - for each step - each pagy `:size` produces a nav that can be contained in its width. - -4. You should ensure that the minimum internal width for the container div be equal (or a bit bigger) to the smaller positive width. (`540` pixels in our previous example). - -5. If the container width snaps to specific widths in discrete steps, you should sync the quantity and widths of the pagy `:steps` to the quantity and internal widths for each discrete step of the container. - -#### Javascript Caveats - -In case of a window resize, the `pagy_*nav_js` elements on the page are re-rendered (when the container width changes), however if the container width changes in any other way that does not involve a window resize, then you should re-render the pagy element explicitly. For example: +## Files -```js -document.getElementById('my-pagy-nav-js').render(); -``` +- [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb) ## Methods ### pagy_nav_js(pagy, ...) -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 generation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `*_js` call in the same line for the same file. - -**Notice**: passing an explicit id is also a bit faster than having pagy to generate one. - -# Javascript Combo Navs - -The `pagy*_combo_nav_js` (implemented by this extra or by other frontend extras) offers an alternative pagination UI that combines navigation and pagination info in a single compact element. - -It is the fastest and lighter `nav` on modern environments, recommended when you care about efficiency and server load _(see [Maximizing Performance](../how-to.md#maximizing-performance))_. - -Here is a screenshot (from the `bootstrap` extra): - -![bootstrap_combo_nav_js](../assets/images/bootstrap_combo_nav_js-g.png) - -## Synopsis - -Use the `pagy*_combo_nav_js helpers in any view: - -```erb -<%== pagy_combo_nav_js(@pagy) %> -``` - -Other extras provide also the following framework-styled helpers: - -```erb -<%== pagy_bootstrap_combo_nav_js(@pagy) %> -<%== pagy_bulma_combo_nav_js(@pagy) %> -<%== pagy_foundation_combo_nav_js(@pagy) %> -<%== pagy_materialize_combo_nav_js(@pagy) %> -<%== pagy_semantic_combo_nav_js(@pagy) %> -``` - -## Methods +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_combo_nav_js(pagy, ...) -Renders a javascript-powered compact navigation 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 generation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `*_js` call in the same line for the same page. - -**Notice**: passing an explicit id is also a bit faster than having pagy to generate one. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. diff --git a/docs/extras/semantic.md b/docs/extras/semantic.md index ddfb27203..5ee5d8895 100644 --- a/docs/extras/semantic.md +++ b/docs/extras/semantic.md @@ -38,12 +38,8 @@ This method is the same as the `pagy_nav`, but customized for Semantic UI. ### 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. +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation. ### pagy_semantic_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the Semantic UI framework. - -See more details in the [compact_navs_js](navs.md#javascript-combo-navs) documentation. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. diff --git a/docs/extras/uikit.md b/docs/extras/uikit.md index 36d0b862f..99a51c674 100644 --- a/docs/extras/uikit.md +++ b/docs/extras/uikit.md @@ -48,17 +48,12 @@ The `uikit_nav.*` templates produce the same output, and can be used as an easie ### pagy_uikit_nav_js(pagy, ...) -This method is the same as the `pagy_nav_js`, but customized for the UIkit framework. - -See more details in the [javascript navs](navs.md#javascript-navs) documentation. - +See the [Javascript Navs](../api/javascript.md#javascript-navs) documentation ### pagy_uikit_combo_nav_js(pagy, ...) -This method is the same as the `pagy_combo_nav_js`, but customized for the UIkit framework. +See the [Javascript Combo Navs](../api/javascript.md#javascript-combo-navs) documentation. Here is an example: ![uikit_combo_nav_js](../assets/images/uikit_combo_nav_js-g.png) - -See more details in the [javascript compact navs](navs.md#javascript-combo-navs) documentation. diff --git a/docs/how-to.md b/docs/how-to.md index 5f1df3063..29cb326ad 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -531,7 +531,7 @@ Here are some tips that will help chosing the best way to use Pagy, depending on If you need the classic pagination bar with links and info, then you have a couple of choices, depending on your environment: -- If you are on ruby 2.0+, add the `oj` gem to your gemfile and use any `pagy*_nav_js` helper _(see [Javascript Navs](extras/navs.md#javascript-navs))_. That uses client side rendering and it is faster and lighter than using any `pagy*_nav` helper _(40x faster, 36x lighter and 1,410x more efficient than Kaminari)_. _Notice: the `oj` gem is not a requirement but helps the performance when it is available._ +- If you are on ruby 2.0+, add the `oj` gem to your gemfile and use any `pagy*_nav_js` helper _(see [Javascript](api/javascript.md))_. That uses client side rendering and it is faster and lighter than using any `pagy*_nav` helper _(40x faster, 36x lighter and 1,410x more efficient than Kaminari)_. _Notice: the `oj` gem is not a requirement but helps the performance when it is available._ - If you are on jruby (any version) or ruby 1.9.x, or you cannot install `oj` then use the `pagy*_nav` helper, which will give you the same performance of pagy v2.0 (33x faster; 26x lighter; 850x more efficient than Kaminari) ### Consider the combo navs