Skip to content

Commit

Permalink
implemented :page_param and updated the doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed May 29, 2018
1 parent fc1c4a8 commit c035ac8
Show file tree
Hide file tree
Showing 9 changed files with 93 additions and 77 deletions.
19 changes: 11 additions & 8 deletions docs/api/backend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
10 changes: 5 additions & 5 deletions docs/api/frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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):
```
Expand All @@ -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
Expand Down Expand Up @@ -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 ...)

Expand Down
52 changes: 26 additions & 26 deletions docs/api/pagy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down
Loading

0 comments on commit c035ac8

Please sign in to comment.