Skip to content

Commit

Permalink
doc improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed Jun 23, 2018
1 parent 99081ee commit 8ca5013
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 22 deletions.
20 changes: 10 additions & 10 deletions docs/extras.md
View file
Expand Up @@ -5,13 +5,13 @@ title: Extras

Pagy comes with a few optional extensions/extras:

| Extra | Description | Links |
| ------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `array` | Paginate arrays efficiently avoiding expensive array-wrapping and wihout overriding | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md) |
| `bootstrap` | Nav helper and templates for Bootstrap pagination | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md) |
| `compact` | An alternative UI that combines the pagination with the nav info in a single compact element | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [documentation](extras/compact.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) |
| Extra | Description | Links |
| ------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `array` | Paginate arrays efficiently avoiding expensive array-wrapping and wihout overriding | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md) |
| `bootstrap` | Nav helper and templates for Bootstrap pagination | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md) |
| `compact` | An alternative UI that combines the pagination with the nav info in a single compact element | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [documentation](extras/compact.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) |
| `responsive` | On resize, the number of page links will adapt in real-time to the available window or container width | [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb), [documentation](extras/responsive.md) |

## Synopsys
Expand All @@ -25,7 +25,7 @@ require 'pagy/extras/...'

## Description

Extras don't define any new module or class, they just re-open the `Pagy` class and modules, adding the extra methods as they were part of the loaded `pagy` gem. This neatly separates the core code from the optional extras, still keeping its usage as simple as it were part of the core gem.
Extras don't define any new module or class, they just re-open the `Pagy` class and modules, adding the extra methods as they were part of the loaded `pagy` gem. This neatly separates the core code from the optional extras, still keeping its usage as simple as it were part of the core.

## Methods

Expand Down Expand Up @@ -67,6 +67,6 @@ or execute the `Pagy.init()` using jQuery:

```js
$( window ).load(function() {
Pagy.init();
Pagy.init()
});
```
```
20 changes: 8 additions & 12 deletions docs/extras/items.md
View file
Expand Up @@ -18,17 +18,11 @@ Pagy::VARS[:items_param] = :custom_param # default :items
Pagy::VARS[:max_items] = 100 # default
```

Configure [javascript](../extras.md#javascript)

Then you may want to use the `pagy_items_selector` helper in any view:

```erb
<%== pagy_items_selector(@pagy) %>
```
Configure [javascript](../extras.md#javascript) (only if you use the `pagy_items_selector` UI)

## Files

This extra is composed of the [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb) and uses the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file.
This extra is composed of the [items.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/items.rb) and may use the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy.js) file.

## Variables

Expand Down Expand Up @@ -57,7 +51,7 @@ pagy(scope, items_param: :custom_param, max_items: 50)
Pagy.new(count:100, items_param: :custom_param, max_items: 50)
```

**Notice**: you can override items that the client send with the params by passing the `:items` explicitly. For example:
**Notice**: you can override the items that the client send with the params by passing the `:items` explicitly. For example:

```ruby
# this will ignore the params[:item] (or any custom :param_name)
Expand All @@ -71,16 +65,18 @@ The `items` extra overrides a couple of builtin methods and adds a helper to the

### pagy_get_vars(collection, vars)

This extra overrides the `pagy_get_vars` method of the `Pagy::Backend` module in order to set the `:items` variable, pulled from the request-params. The built-in `pagy_get_vars` method is aliased as `built_in_pagy_get_vars` and is called internally and still available.
This extra overrides the `pagy_get_vars` method of the `Pagy::Backend` module in order to set the `:items` variable, pulled from the request-params. The built-in `pagy_get_vars` method is aliased as `built_in_pagy_get_vars` and it's called internally and still available.

### pagy_url_for(page, pagy)

This extra overrides also the `pagy_url_for` method of the `Pagy::Frontend` module in order to add the `:items_param` param to the url of the links.

### pagy_items_selector(pagy)

This helper provides an items selector UI, which allows the user to select any arbitrary number of items per page below the `:max_items` number in a numeric input field. It looks like:
This helper provides an items selector UI, which allows the user to select any arbitrary number of items per page (below the `:max_items` number) in a numeric input field. It looks like:

<span>Show <input type="number" min="1" max="100" value="20" style="padding: 0; text-align: center; width: 3rem;"> items per page</span>

When the items number is changed with the selector, pagy will reload the pagination UI using the selected items per page. It will also request the _right_ page number calculated in order to contain the first item of the previously displayed page. That way the new displayed page will roughly show the same items in the collection.
You can change/translate its text by editing the [dictionaray YAML file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml) at the `pagy.items` path.

When the items number is changed with the selector, pagy will reload the pagination UI using the selected items per page. It will also request the _right_ page number calculated in order to contain the first item of the previously displayed page. That way the new displayed page will roughly show the same items in the collection before the items change.

0 comments on commit 8ca5013

Please sign in to comment.