compact > combo and other changes

ddnexus · Apr 28, 2019 · 901f779 · 901f779
1 parent f7425a5
commit 901f779
Show file tree

Hide file tree

Showing 30 changed files with 258 additions and 240 deletions.
diff --git a/LEGACY_CHANGELOG.md b/LEGACY_CHANGELOG.md
@@ -190,7 +190,7 @@
 ### Breaking Changes
 
 - I18n refactoring
-  - Compact helpers and item selectors have been refactored: you should update your overridden helpers accordingly
+  - Combo helpers and item selectors have been refactored: you should update your overridden helpers accordingly
   - The i18n structure has changed, update your custom i18n locale file
 
 ### Commits

diff --git a/README.md b/README.md
@@ -11,13 +11,15 @@
 
 Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.
 
-## Improvements in 2.0+
+## New in 3.0+
 
-- Lower ruby requirements (ruby 1.9+ || jruby 1.7+) make Pagy very convenient also on older systems
-- Added RFC-8288 compliant http response `headers` extra
-- The i18n internal implementation now includes full dynamic support for multi-language apps, it's ~18x faster and uses ~10x less memory than the i18n gem
-- The `searchkick` and `elasticsearch_rails` extras have been refactored with more and better options
-- Pagy 2.0+ is even faster and lighter than 1.0+ (see charts below)
+- Internal refactoring of nav helpers for improved performance and more intuitive API
+- Added [Maximizing Performance](https://ddnexus.github.io/pagy/how-to#maximizing-performance) docs as a practical guide to choose the best options for your requirements and environment
+- Pagy 3.0+ is even faster and lighter than 2.0+ on modern environments (see the charts below)
+
+**Notice**: Updating from 2.0+ to 3.0+ requires only a few renaming. Check the [CHANGELOG](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md) for details.
+
+**Suggestion**: If you are using any `pagy*_nav` helper, [consider to switch](https://ddnexus.github.io/pagy/how-to#consider-the-nav_js) to `pagy*_nav_js`, which gives you the same output with a substancial performance boost.
 
 ## Comparison with other gems
 
@@ -64,7 +66,7 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
 
 ### Unlike the other gems
 
-- Pagy is very modular and does not load nor execute unnecessary code in your app _(see [why...](https://ddnexus.github.io/pagy/how-to#global-configuration))_
+- Pagy is very modular and does not load any unnecessary code in your app _(see [why...](https://ddnexus.github.io/pagy/how-to#global-configuration))_
 - It works even with collections/scopes that already used `limit` and `offset` _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-a-pre-offsetted-and-pre-limited-collection))_
 - It works with fast helpers OR easy to edit templates _(see [more...](https://ddnexus.github.io/pagy/how-to#using-templates))_
 - It raises real `Pagy::OverflowError` exceptions that you can rescue from _(see [how...](https://ddnexus.github.io/pagy/how-to#handling-pagyoutofrangeerror-exception))_ or use the [overflow extra](http://ddnexus.github.io/pagy/extras/overflow) for a few ready to use common behaviors
@@ -73,7 +75,7 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
 
 ### Easy to use
 
-You can use Pagy in a quite familiar way:
+After installing and including Pagy _(see [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start))_, you can use it in a quite familiar way:
 
 Paginate your collection in some controller:
 
@@ -93,8 +95,6 @@ Or - if you prefer - render the navigation links with a template:
 <%== render 'pagy/nav', locals: {pagy: @pagy} %>
 ```
 
-_(see [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start) for more details)_
-
 ## Easy to customize
 
 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:
@@ -108,12 +108,12 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 
 ### Frontend Extras
 
-- [bootstrap](http://ddnexus.github.io/pagy/extras/bootstrap): Add nav, nav_js and compact_nav_js helpers for the Bootstrap [pagination component](https://getbootstrap.com/docs/4.1/components/pagination)
-- [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 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)
+- [bootstrap](http://ddnexus.github.io/pagy/extras/bootstrap): Add nav, nav_js and combo_nav_js helpers for the Bootstrap [pagination component](https://getbootstrap.com/docs/4.1/components/pagination)
+- [bulma](http://ddnexus.github.io/pagy/extras/bulma): Add nav, nav_js and combo_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 combo_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 combo_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 combo_nav_js unstyled helpers
+- [semantic](http://ddnexus.github.io/pagy/extras/semantic): Add nav, nav_js and combo_nav_js helpers for the Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html)
 
 ### Feature Extras
 
@@ -126,11 +126,11 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 
 ### Alternative Components
 
-Besides the classic pagination `nav`, Pagy offers a few ready to use alternatives like:
+Besides the classic pagination offered by the `pagy_nav` helpers, you can use a couple of more performant alternatives:
 
-- [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:<br>![bootstrap_nav_js](docs/assets/images/bootstrap_nav_js-w.png)
+- [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:<br>![bootstrap_nav_js](docs/assets/images/bootstrap_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:<br>![bootstrap_compact_nav_js](docs/assets/images/bootstrap_compact_nav_js-w.png)
+- [pagy_combo_nav_js](http://ddnexus.github.io/pagy/extras/navs#javascript-combo-navs): The fastest and lighest alternative UI that combines navigation and pagination info in a single compact element:<br>![bootstrap_combo_nav_js](docs/assets/images/bootstrap_combo_nav_js-w.png)
 
 ## Resources
 

diff --git a/docs/api/countless.md b/docs/api/countless.md
@@ -41,7 +41,7 @@ The available values for the `:overflow` variable are `:empty_page` and `:except
 
 ### Features without support
 
-The `pagy_info` and all the `*_compact_nav_js` helpers that use the total `count` are not supported.
+The `pagy_info` and all the `*_combo_nav_js` helpers that use the total `count` are not supported.
 
 ## How countless pagination works
 

diff --git a/...ets/images/bootstrap_compact_nav_js-g.png → ...ssets/images/bootstrap_combo_nav_js-g.png b/...ets/images/bootstrap_compact_nav_js-g.png → ...ssets/images/bootstrap_combo_nav_js-g.png
diff --git a/...ets/images/bootstrap_compact_nav_js-w.png → ...ssets/images/bootstrap_combo_nav_js-w.png b/...ets/images/bootstrap_compact_nav_js-w.png → ...ssets/images/bootstrap_combo_nav_js-w.png
diff --git a/.../assets/images/bulma_compact_nav_js-g.png → docs/assets/images/bulma_combo_nav_js-g.png b/.../assets/images/bulma_compact_nav_js-g.png → docs/assets/images/bulma_combo_nav_js-g.png
diff --git a/...s/images/materialize_compact_nav_js-g.png → ...ets/images/materialize_combo_nav_js-g.png b/...s/images/materialize_compact_nav_js-g.png → ...ets/images/materialize_combo_nav_js-g.png
diff --git a/docs/extras.md b/docs/extras.md
@@ -8,19 +8,19 @@ 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`           | Add nav, nav_js and compact_nav_js helpers for the Bootstrap [pagination component](https://getbootstrap.com/docs/4.1/components/pagination) | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md)                               |
-| `bulma`               | Add nav, nav_js and compact_nav_js helpers for the Bulma [pagination component](https://bulma.io/documentation/components/pagination)        | [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb), [documentation](extras/bulma.md)                                           |
+| `bootstrap`           | Add nav, nav_js and combo_nav_js helpers for the Bootstrap [pagination component](https://getbootstrap.com/docs/4.1/components/pagination) | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md)                               |
+| `bulma`               | Add nav, nav_js and combo_nav_js helpers for the Bulma [pagination component](https://bulma.io/documentation/components/pagination)        | [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb), [documentation](extras/bulma.md)                                           |
 | `countless`           | Paginate without any count, saving one query per rendering                                                                                   | [countless.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/countless.rb), [documentation](extras/countless.md)                               |
 | `elasticsearch_rails` | Paginate `elasticsearch_rails` gem results efficiently                                                                                       | [elasticsearch_rails.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/elasticsearch_rails.rb), [documentation](extras/elasticsearch_rails.md) |
-| `foundation`          | Add nav, nav_js and compact_nav_js helpers for the Foundation [pagination component](https://foundation.zurb.com/sites/docs/pagination.html) | [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb), [documentation](extras/foundation.md)                            |
+| `foundation`          | Add nav, nav_js and combo_nav_js helpers for the Foundation [pagination component](https://foundation.zurb.com/sites/docs/pagination.html) | [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb), [documentation](extras/foundation.md)                            |
 | `headers`             | Add [RFC-8288](https://tools.ietf.org/html/rfc8288) compliant http response headers (and other helpers) useful for API pagination            | [headers.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/headers.rb), [documentation](extras/headers.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`         | Add nav, nav_js and compact_nav_js helpers for the 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 nav_js and compact_nav_js javascript unstyled helpers                                                                                    | [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb), [documentation](extras/navs.md)                                              |
+| `materialize`         | Add nav, nav_js and combo_nav_js helpers for the 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 nav_js and combo_nav_js javascript unstyled helpers                                                                                    | [navs.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/navs.rb), [documentation](extras/navs.md)                                              |
 | `overflow`            | Allow for easy handling of overflowing pages                                                                                                 | [overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb), [documentation](extras/overflow.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)                            |
-| `semantic`            | Add nav, nav_js and compact_nav_js helpers for the Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html)     | [semantic.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/semantic.rb), [documentation](extras/semantic.md)                                  |
+| `semantic`            | Add nav, nav_js and combo_nav_js helpers for the Semantic UI CSS [pagination component](https://semantic-ui.com/collections/menu.html)     | [semantic.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/semantic.rb), [documentation](extras/semantic.md)                                  |
 | `support`             | Extra support for features like: incremental, infinite, auto-scroll pagination                                                               | [support.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/support.rb), [documentation](extras/support.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)                                              |
 
@@ -47,12 +47,16 @@ A few extras require the [pagy/extras/shared](https://github.com/ddnexus/pagy/bl
 
 A few helpers use javascript, and they are clearly recognizable by the `js` suffix:
 
-- `pagy_*_nav_js`
-- `pagy_*_compact_nav_js`
+- `pagy*_nav_js`
+- `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).
 
+### Add the oj gem
+
+Although it's not a requirement, if you are on ruby 2.0+ (not jruby), you should add the `gem 'oj'` to your Gemfile. When available, Pagy will automatically use it to boost the performance.
+
 ### In rails apps
 
 #### With the asset pipeline

diff --git a/docs/extras/bootstrap.md b/docs/extras/bootstrap.md
@@ -21,7 +21,7 @@ with a fast helper:
 ```erb
 <%== pagy_bootstrap_nav(@pagy) %>
 <%== pagy_bootstrap_nav_js(@pagy) %>
-<%== pagy_bootstrap_compact_nav_js(@pagy) %>
+<%== pagy_bootstrap_combo_nav_js(@pagy) %>
 ```
 
 or with a template:
@@ -30,7 +30,7 @@ or with a template:
 <%== render 'pagy/bootstrap_nav', locals: {pagy: @pagy} %>
 ```
 
-Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_nav_js` or `pagy_bootstrap_compact_nav_js`.
+Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_nav_js` or `pagy_bootstrap_combo_nav_js`.
 
 ## Files
 
@@ -57,12 +57,12 @@ This method is the same as the `pagy_nav_js`, but customized for the Bootstrap f
 See more details in the [javascript navs](navs.md#javascript-navs) documentation.
 
 
-### pagy_bootstrap_compact_nav_js(pagy, ...)
+### pagy_bootstrap_combo_nav_js(pagy, ...)
 
-This method is the same as the `pagy_compact_nav_js`, but customized for the Bootstrap framework.
+This method is the same as the `pagy_combo_nav_js`, but customized for the Bootstrap framework.
 
 Here is an example:
 
-![bootstrap_compact_nav_js](../assets/images/bootstrap_compact_nav_js-g.png)
+![bootstrap_combo_nav_js](../assets/images/bootstrap_combo_nav_js-g.png)
 
-See more details in the [javascript compact navs](navs.md#javascript-compact-navs) documentation.
+See more details in the [javascript compact navs](navs.md#javascript-combo-navs) documentation.
diff --git a/docs/extras/bulma.md b/docs/extras/bulma.md
@@ -21,7 +21,7 @@ with a fast helper:
 ```erb
 <%== pagy_bulma_nav(@pagy) %>
 <%== pagy_bulma_nav_js(@pagy) %>
-<%== pagy_bulma_compact_nav_js(@pagy) %>
+<%== pagy_bulma_combo_nav_js(@pagy) %>
 ```
 
 or with a template:
@@ -30,7 +30,7 @@ or with a template:
 <%== render 'pagy/bulma_nav', locals: {pagy: @pagy} %>
 ```
 
-Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_nav_js` or `pagy_bulma_compact_nav_js`.
+Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_nav_js` or `pagy_bulma_combo_nav_js`.
 
 ## Files
 
@@ -55,12 +55,12 @@ This method is the same as the `pagy_nav_js`, but customized for the Bulma CSS f
 
 See more details in the [javascript navs](navs.md#javascript-navs) documentation.
 
-### pagy_bulma_compact_nav_js(pagy, ...)
+### pagy_bulma_combo_nav_js(pagy, ...)
 
-This method is the same as the `pagy_compact_nav_js`, but customized for the Bulma CSS framework.
+This method is the same as the `pagy_combo_nav_js`, but customized for the Bulma CSS framework.
 
 Here is an example:
 
-![bulma_compact_nav_js](../assets/images/bulma_compact_nav_js-g.png)
+![bulma_combo_nav_js](../assets/images/bulma_combo_nav_js-g.png)
 
-See more details in the [compact_navs_js](navs.md#javascript-compact-navs)  documentation.
+See more details in the [compact_navs_js](navs.md#javascript-combo-navs)  documentation.
diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md
@@ -28,7 +28,7 @@ or with a template:
 <%== render 'pagy/foundation_nav', locals: {pagy: @pagy} %>
 ```
 
-Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_nav_js` or `pagy_foundation_compact_nav_js`.
+Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_nav_js` or `pagy_foundation_combo_nav_js`.
 
 ## Files
 
@@ -53,8 +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.
 
-### pagy_foundation_compact_nav_js(pagy, ...)
+### pagy_foundation_combo_nav_js(pagy, ...)
 
-This method is the same as the `pagy_compact_nav_js`, but customized for the Foundation framework.
+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-compact-navs)  documentation.
+See more details in the [compact_navs_js](navs.md#javascript-combo-navs)  documentation.