a few fixes and doc improvements [ci skip]

ddnexus · ddnexus · commit d0e4ba6407ef · 2019-05-02T16:19:39.000+07:00
diff --git a/docs/api/frontend.md b/docs/api/frontend.md
@@ -90,8 +90,6 @@ You need this section only if you are going to override a `pagy_nav*` helper or
 
 **Important**: This method is not intended to be overridden, however you could just replace it in your overridden `pagy_nav*` helpers or templates with some generic helper like the rails `link_to`. If you intend to do so, be sure to have a very good reason, since using `pagy_link_proc` is a lot faster than the rails `link_to` (benchmarked at ~22x faster using ~18x less memory on a 20 links nav).
 
-**Warning**: This is a peculiar way to create page links and it works only for that purpose. It is not intended to be used for generic links.
-
 This method returns a specialized proc that you call to produce the page links. The reason it is a two steps process instead of a single method call is performance. Indeed the method calls the potentially expensive `pagy_url_for` only once and generates the proc, then calling the proc will just interpolates the strings passed to it.
 
 Here is how you should use it: in your helper or template call the method to get the proc (just once):
@@ -190,7 +188,7 @@ Pagy::I18n.load(locale: 'de')
 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
+# the first :locale will be used also as the default locale
 Pagy::I18n.load({locale: 'de'},
                 {locale: 'en'},
                 {locale: 'es'})
@@ -222,7 +220,7 @@ That instance variable will be used by the [pagy_t](#pagy_tpath-vars) method inc
 
 When Pagy uses its own i18n implementation, it has only access to the strings in its own files and not in other `I18n` files used by the rest of the app.
 
-That means that if you use the `pagy_info` helper with the specific model names instead of the generic "items" string, you may need to add entries for the models in the pagy dictionary files. For example:
+That means that if you use the `pagy_info` or `pagy_items_selector` helpers with the specific model names instead of the generic "items" string, you may need to add entries for the models in the pagy dictionary files. For example:
 
 ```yaml
 en:
diff --git a/docs/extras.md b/docs/extras.md
@@ -92,16 +92,16 @@ If your app uses Webpacker, ensure that the webpacker `erb` loader is installed:
 bundle exec rails webpacker:install:erb
 ```
 
-Then create a `pagy.js.erb` to render the content of `pagy.js` and add the event listener into it:
+Then create a `pagy.js.erb` in order to render the content of `pagy.js` and add the event listener into it:
 
-```
-// app/javascript/src/javascripts/pagy.js.erb
+```erb
 <%= Pagy.root.join('javascripts', 'pagy.js').read %>
 window.addEventListener("load", Pagy.init)
 ```
-and import it:
+
+and import it in `app/javascript/application.js`:
+
 ```js
-// app/javascript/application.js
 import '../src/javascripts/pagy.js.erb'
 ```
 
@@ -116,7 +116,9 @@ import '../src/javascripts/pagy.js.erb'
 
 ### In non-rails apps
 
-Ensure the `pagy/extras/javascripts/pagy.js` script gets served with the page and add an event listener like:
+Ensure the `pagy/extras/javascripts/pagy.js` script gets served with the page.
+
+Add an event listener like:
 
 ```js
 window.addEventListener('load', Pagy.init);
diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md
@@ -20,6 +20,8 @@ with a fast helper:
 
 ```erb
 <%== pagy_foundation_nav(@pagy) %>
+<%== pagy_foundation_nav_js(@pagy) %>
+<%== pagy_foundation_combo_nav_js(@pagy) %>
 ```
 
 or with a template:
diff --git a/docs/extras/overflow.md b/docs/extras/overflow.md
@@ -28,13 +28,13 @@ Pagy::VARS[:overflow] = :exception
 
 ## Files
 
--[overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb)
+- [overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb)
 
 ## Variables
 
-| Variable    | Description                                              | Default       |
-|:------------|:---------------------------------------------------------|:--------------|
-| `:overflow` | one of `:last_page`, `:empty_page` or `:exception` modes | `:empty_page` |
+| Variable    | Description                                                                         | Default       |
+|:------------|:------------------------------------------------------------------------------------|:--------------|
+| `:overflow` | the modes in case of overflowing page (`:last_page`, `:empty_page` or `:exception`) | `:empty_page` |
 
 As usual, depending on the scope of the customization, you have a couple of options to set the variables:
 
@@ -50,32 +50,15 @@ Pagy::VARS[:overflow] = :empty_page
 
 These are the modes accepted by the `:overflow` variable:
 
-### :last_page
-
-**Notice**: Not available for `Pagy::Countless` instances.
-
-It is useful in apps with an UI, in order to avoid to redirect to the last page.
-
-Regardless the overflowing page requested, Pagy will set the page to the last page and paginate exactly as if the last page has been requested. For example:
-
-```ruby
-# no exception passing an overflowing page (Default mode :last_page)
-pagy = Pagy.new(count: 100, page: 100)
-
-pagy.overflow?          #=> true
-pagy.vars[:page]        #=> 100 (requested page)
-pagy.page               #=> 5   (current/last page)
-pagy.last == pagy.page  #=> true
-```
-
 ### :empty_page
 
 This is the default mode; it will paginate the actual requested page, which - being overflowing - is empty. It is useful with APIs, where the client expects an empty set of results in order to stop requesting further pages.
 
 Example for `Pagy` instance:
 
 ```ruby
-pagy = Pagy.new(count: 100, page: 100, overflow: :empty_page)
+# no exception passing an overflowing page
+pagy = Pagy.new(count: 100, page: 100)
 
 pagy.overflow?          #=> true
 pagy.vars[:page]        #=> 100 (requested page)
@@ -96,7 +79,7 @@ Example for `Pagy::Countless` instance:
 require 'pagy/countless'
 require 'pagy/extras/overflow'
 
-pagy = Pagy::Countless.new(count: 100, page: 100, overflow: :empty_page).finalize(0)
+pagy = Pagy::Countless.new(count: 100, page: 100).finalize(0)
 
 pagy.overflow?          #=> true
 pagy.vars[:page]        #=> 100 (requested page)
@@ -111,9 +94,34 @@ pagy.to                 #=> 0
 pagy.series             #=>  [] (no pages)
 ```
 
+### :last_page
+
+**Notice**: Not available for `Pagy::Countless` instances since for countless instances the last page is not known.
+
+It is useful in apps with an UI, in order to avoid to redirect to the last page.
+
+Regardless the overflowing page requested, Pagy will set the page to the last page and paginate exactly as if the last page has been requested. For example:
+
+```ruby
+pagy = Pagy.new(count: 100, page: 100, overflow: :last_page)
+
+pagy.overflow?          #=> true
+pagy.vars[:page]        #=> 100 (requested page)
+pagy.page               #=> 5   (current/last page)
+pagy.last == pagy.page  #=> true
+```
+
 ### :exception
 
-This mode raises the `Pagy::OverflowError` as usual, so you can rescue from and do what is needed. It is useful when you need to use your own custom mode even in presence of this extra (which would not raise any error).
+This mode raises the `Pagy::OverflowError` as usual, so you can rescue from and implement your own custom mode even in presence of this extra.
+
+```ruby
+begin
+  pagy = Pagy.new(count: 100, page: 100, overflow: :exception)
+rescue Pagy::OverflowError => e
+  ...
+end
+```
 
 ## Methods
 
diff --git a/docs/extras/semantic.md b/docs/extras/semantic.md
@@ -20,8 +20,8 @@ with a fast helper:
 
 ```erb
 <%== pagy_semantic_nav(@pagy) %>
-<%== pagy_semantic_combo_nav_js(@pagy) %>
 <%== pagy_semantic_nav_js(@pagy) %>
+<%== pagy_semantic_combo_nav_js(@pagy) %>
 ```
 
 ## Files
diff --git a/docs/extras/support.md b/docs/extras/support.md
@@ -17,7 +17,7 @@ require 'pagy/extras/support'
 
 ## Support for alternative pagination types and features
 
-Besides the classic navbar pagination, the `compact` and the `responsive` UI components, Pagy offers a few helpers to support a few alternative types of pagination and related features.
+Besides the classic `pagy*_nav` pagination, the `pagy*_nav_js` and the `pagy*_combo_nav_js` UI components, Pagy offers a few helpers to support a few alternative types of pagination and related features.
 
 ### Countless
 
diff --git a/docs/how-to.md b/docs/how-to.md
@@ -80,7 +80,7 @@ Pagy works out of the box assuming that:
 Pagy can also work in any other scenario assuming that:
 
 - If your framework doesn't have a `params` method you may need to define the `params` method or override the `pagy_get_vars` (which uses the `params` method) in your controller
-- If the collection you are paginating doesn't respond to `offset` and `limit` you may need to override the `pagy_get_items` method in your controller (to get the items out of your specific collection) or use a specific extra if available (e.g. `array`, `searchkick`, ...)
+- If the collection you are paginating doesn't respond to `offset` and `limit` you may need to override the `pagy_get_items` method in your controller (to get the items out of your specific collection) or use a specific extra if available (e.g. `array`, `searchkick`, `elasticsearch_rais`)
 - If your framework doesn't have a `request` method you may need to override the `pagy_url_for` (which uses `Rack` and `request`) in your view
 
 **Notice**: the total overriding you may need is usually just a handful of lines at worse, and it doesn't need monkey patching or writing any sub-class or module.
@@ -165,7 +165,7 @@ You can also override the `pagy_get_vars` if you need some special way to get th
 If you need to customize some HTML attribute of the page links, you may not need to override the `pagy_nav*` helper. It might be enough to pass some extra attribute string with the `:link_extra` variable. For example:
 
 ```ruby
-# for all the Pagy instance
+# for all the Pagy instances
 Pagy::VARS[:link_extra] = 'data-remote="true" class="my-class"'
 
 # for a single Pagy instance (if you use the Pagy::Backend#pagy method)
@@ -189,13 +189,13 @@ def pagy_get_params(params)
 end
 ```
 
-You can also use the `:param` and : `:anchor` non core variables to add arbitrary params to the URLs of the pages. For example:
+You can also use the `:param` and : `:anchor` variables to add arbitrary params to the URLs of the pages. For example:
 
 ```ruby
 @pagy, @records = pagy(some_scope, params: {custom: 'param'}, anchor: '#your-anchor')
 ```
 
-**IMPORTANT**: For performance reasons the `:anchor` string must include the `#`.
+**IMPORTANT**: For performance reasons the `:anchor` string must include the `"#"`.
 
 ## Customizing the URL
 
@@ -353,14 +353,14 @@ These helpers take the Pagy object and return the HTML string with the paginatio
 
 **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_bootstrap_nav`, `pagy_bootstrap_combo_nav_js`, `pagy_bootstrap_nav_js`       |
-| [bulma](extras/bulma.md)             | `pagy_bulma_nav`, `pagy_bulma_combo_nav_js`, `pagy_bulma_nav_js`                   |
-| [foundation](extras/foundation.md)   | `pagy_foundation_nav`, `pagy_foundation_combo_nav_js`, `pagy_foundation_nav_js`    |
-| [materialize](extras/materialize.md) | `pagy_materialize_nav`, `pagy_materialize_combo_nav_js`, `pagy_materialize_nav_js` |
-| [navs](extras/navs.md)               | `pagy_combo_nav_js`, `pagy_nav_js`                                                 |
-| [semantic](extras/semantic.md)       | `pagy_semantic_nav`, `pagy_semantic_combo_nav_js`, `pagy_semantic_nav_js`          |
+| Extra                                | Helpers                                                                            |
+|:-------------------------------------|:-----------------------------------------------------------------------------------|
+| [bootstrap](extras/bootstrap.md)     | `pagy_bootstrap_nav`, `pagy_bootstrap_nav_js`, `pagy_bootstrap_combo_nav_js`       |
+| [bulma](extras/bulma.md)             | `pagy_bulma_nav`, `pagy_bulma_nav_js`, `pagy_bulma_combo_nav_js`                   |
+| [foundation](extras/foundation.md)   | `pagy_foundation_nav`, `pagy_foundation_nav_js`, `pagy_foundation_combo_nav_js`    |
+| [materialize](extras/materialize.md) | `pagy_materialize_nav`, `pagy_materialize_nav_js`, `pagy_materialize_combo_nav_js` |
+| [navs](extras/navs.md)               | `pagy_nav_js`, `pagy_combo_nav_js`                                                                    |
+| [semantic](extras/semantic.md)       | `pagy_semantic_nav`, `pagy_semantic_nav_js`, `pagy_semantic_combo_nav_js`          |
 
 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 and edit it there. It is a simple concatenation of strings with a very simple logic.
 
@@ -496,7 +496,7 @@ Here are a few options for manually handling the error in apps:
 
    private
 
-   def redirect_to_last_page(e)
-     redirect_to url_for(page: e.pagy.last), notice: "Page ##{params[:page]} is overflowing. Showing page #{e.pagy.last} instead."
+   def redirect_to_last_page(exception)
+     redirect_to url_for(page: exception.pagy.last), notice: "Page ##{params[:page]} is overflowing. Showing page #{exception.pagy.last} instead."
    end
    ```
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
@@ -60,7 +60,7 @@ Pagy::VARS[:items] = 10
 Pagy::VARS[:size]  = [5,4,4,5]
 ```
 
-Remove all the old settings and uncomment and edit the new settings in the `pagy.rb` initializer _(see [Configuration](how-to.md#global-configuration))_.
+Remove all the legacy settings of the old gem(s) and uncomment and edit the new settings in the `pagy.rb` initializer _(see [Configuration](how-to.md#global-configuration))_.
 
 #### Cleanup the Models
 
@@ -70,7 +70,7 @@ The other gems are careless about adding methods, scopes, and even configuration
 
 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:
+If the app used the `page` scope in some of its methods or scopes in some model, that should be removed (including removing the argument used to pass the page number to the method/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:
 
 ```ruby
 #@records = Product.paginated_scope(params[:page])
@@ -125,10 +125,8 @@ Please take a look at the topics in the [how-to](how-to.md) documentation: that
 
 ### CSSs
 
-The css styling that you may have applied to the pagination elements may need some minor change. However if the app uses the pagination from bootstrap (or some other framework), the same CSSs should work seamlessly with the pagy nave helpers or with any of the bootstrap templates.
+The css styling that you may have applied to the pagination elements may need some minor change. However if the app uses the pagination from bootstrap (or some other framework), the same CSSs should work seamlessly with the pagy nav helpers or with any of the bootstrap templates.
 
 ### I18n
 
-If the app uses `I18n` you should follow the [I18n doc](api/frontend.md#i18n)
-
-See also [I18n](api/frontend.md#i18n).
+If the app uses `I18n` you should follow the [I18n doc](api/frontend.md#i18n).
