implemented :page_param and updated the doc

docs/api/backend.md

@@ -15,12 +15,12 @@ __Notice__: Currently, the only available backend extra is the [array extra](../
 ## Synopsys
 
 ```ruby
-# typically in your controller
+# in your controller
 include Pagy::Backend
 
-# optional overriding of some sub-method (e.g. get the page number from the :seite param)
-def pagy_get_vars(collection)
- { count: collection.count, page: params[:seite] } 
+# optional overriding of some sub-method 
+def pagy_get_vars(collection, vars)
+ #...
 end
 
 # use it in some action
@@ -54,18 +54,21 @@ def pagy_custom(collection, vars={})
 end
 ```
 
-### pagy_get_vars(collection)
+### pagy_get_vars(collection, vars)
 
 Sub-method called only by the `pagy` method, it returns the hash of variables used to initialize the pagy object.
 
 Here is its source:
 
 ```ruby
-def pagy_get_vars(collection)
- { count: collection.count, page: params[:page] }
+# sub-method called only by #pagy: here for easy customization of variables by overriding
+def pagy_get_vars(collection, vars)
+ # return the merged variables to initialize the pagy object
+ { count: collection.count,
+ page: params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
 end
 ```
-Override it if you need to add or change some variable. For example you may want to add the `:item_path` or the `:item_name` to customize the `pagy_info` output, or get the `:page` from a different param, or even cache the `count`.
+Override it if you need to add or change some variable. For example you may want to add the `:item_path` or the `:item_name` to customize the `pagy_info` output, or even cache the `count`.
 
 _IMPORTANT_: `:count` and `:page` are the only 2 required pagy core variables, so be careful not to remove them from the returned hash.
 

docs/api/frontend.md

@@ -28,7 +28,7 @@ use some of its method in some view:
 
 ## Methods
 
-All the methods in this module are prefixed with the `"pagy_"` string, to avoid any possible conflict with your own methods when you include the module in your helper. The methods prefixed with the `"pagy_get_"` string are sub-methods/getter methods that are intended to be overridden and not used directly.
+All the methods in this module are prefixed with the `"pagy_"` string in order to avoid any possible conflict with your own methods when you include the module in your helper. The methods prefixed with the `"pagy_get_"` string are sub-methods/getter methods that are intended to be overridden and not used directly.
 
 Please, keep in mind that overriding any method is very easy with pagy. Indeed you can do it right where you are using it: no need of monkey-patching or subclassing or tricky gymnic.
 
@@ -69,7 +69,7 @@ Displaying Products <b>476-500</b> of <b>1000</b> in total
 See also [Using the pagy_info helper](../how-to.md#using-the-pagy_info-helper).
 
 
-### pagy_url_for(n)
+### pagy_url_for(n, page_param)
 
 This method is called internally in order to produce the url of a page by passing it its number. For standard usage it works out of the box and you can just ignore it.
 
@@ -102,7 +102,7 @@ You need this section only if you are going to override a `pagy_nav*` helper or
 
 **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 any other generic links to any URLs different than a page link.
 
-This method returns a specialized proc that you call to produce the page links. The reason it is a 2 steps process instead of a single method call is performance.
+This method returns a specialized proc that you call to produce the page links. The reason it is a 2 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):
 ```
@@ -118,7 +118,7 @@ link.call( page_number [, text [, extra_attributes_string ]])
 
 If you need to add some HTML attribute to the page links, you can pass some extra attribute string at many levels, depending on the scope you want your attributes to be added.
 
-**Important**: For performance reasons, the extra attributes strings must be formatted as valid HTML attribute/value pairs. _All_ the stringa spassed at any level will get inserted verbatim in the HTML of the link.
+**Important**: For performance reasons, the extra attributes strings must be formatted as valid HTML attribute/value pairs. _All_ the string spassed at any level will get inserted verbatim in the HTML of the link.
 
 1. For all pagy objects: set the global variable `:link_extra`:
  ```ruby
@@ -168,7 +168,7 @@ _(see I18n below)_
 
 Pagy is I18n ready. That means that all the UI strings that pagy uses are stored in a [dictionaray YAML file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml), ready to be customized and/or translated/pluralized.
 
-The YAML file is available at `Pagy.root.join('locales', 'pagy.yml')`. It contains a few entries used in the the UI by helpers and templates through the [pagy_t method](api/frontend.md#pagy_tpath-vars) (eqivalent to the `I18n.t` or rails `t` helper).
+The YAML file is available at `Pagy.root.join('locales', 'pagy.yml')`. It contains a few entries used in the the UI by helpers and templates through the [pagy_t method](#pagy_tpath-vars) (eqivalent to the `I18n.t` or rails `t` helper).
 
 By default, the `pagy_t` method uses the pagy implementation of I18n, which does not depend on the `I18n` gem in any way. It's _5x faster_ and uses _3.5x less memory_, but it provides only pluralization/interpolation without translation, so it's only useful with single language apps (i.e. only `fr` or only `en` or only ...)
 

docs/api/pagy.md

@@ -60,31 +60,31 @@ _Notice_: If you use the `Pagy::Backend` its `pagy` method will instantiate and
 
 The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object. The only mandatory variable is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1. All the other variables not explicitly in the list of core-variables (the non-core variables) passed/merged to the new method will be kept in the object and passed around with it.
 
+__Notice__: Pagy replaces the blank values of the passed variables with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+
 
 ### Core Variables
 
 These are the core-variables (i.e. instance variables that define the pagination object itself) consumed by the `new` method. They are all integers:
 
-| Variable | Description | Default |
-|----------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|
-| `:count` | the total count of the collection to paginate (mandatory argument) | `nil` |
-| `:page` | the requested page number | `1` |
-| `:items` | the _requested_ number of items for the page | `20` |
-| `:outset` | the initial offset of the collection to paginate: pass it only if the collection was pre-offset(ted) | `0` |
-| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |
-
-__Notice__: Pagy replaces the blank values of scalar core variables (so excluding `:size`) with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
-
+| Variable | Description | Default |
+|----------:|:-----------------------------------------------------------------------------------------------|:--------|
+| `:count` | the total count of the collection to paginate (mandatory argument) | `nil` |
+| `:page` | the requested page number | `1` |
+| `:items` | the _requested_ number of items for the page | `20` |
+| `:outset` | the initial offset of the collection to paginate: pass it only if the collection had an offset | `0` |
 
 
 ### Non-core Variables
 
-These are the non-core variables used in the `Pagy::Frontend`: as for the core-variables they can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method, but they don't become instance variables. Instead they are items of the `@vars` instance variable hash and are accessible through the `vars` reader.
+These are the non-core variables: as for the core-variables they can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method, but they don't become instance variables. Instead they are items of the `@vars` instance variable hash and are accessible through the `vars` reader.
 
-| Variable | Description | Default |
-|--------------:|:------------------------------------------------------------------------------------------------------|:--------|
-| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `nil` |
-| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `nil` |
+| Variable | Description | Default |
+|--------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|
+| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. (see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |
+| `:page_param` | the name of the page param name used in the url. (see [Customizing the page param](../how-to.md#customizing-the-page-param) | `:page` |
+| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `nil` |
+| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `nil` |
 
 There is no specific default nor validation for non-core variables, which are just optional strings.
 
@@ -126,17 +126,17 @@ That is self-contained, simple and efficient.
 The lowest possible limit of the pagination is reached when the collection has `0` count. In that case the pagy object created has the following peculiar attributes:
 
 | Attribute | Value |
-|:----------|:--------|
-| `count`  | `0` |
-| `page` | `1` |
-| `items`  | `0` |
-| `pages`  | `1` |
-| `last` | `1` |
-| `from` | `0` |
-| `to` | `0` |
-| `prev` | `nil` |
-| `next` | `nil` |
-| `series`  | `["1"]` |
+|----------:|:--------|
+|  `count` | `0` |
+| `page` | `1` |
+|  `items` | `0` |
+|  `pages` | `1` |
+| `last` | `1` |
+| `from` | `0` |
+| `to` | `0` |
+| `prev` | `nil` |
+| `next` | `nil` |
+|  `series` | `["1"]` |
 
 Which means: