Skip to content

Commit

Permalink
replaced responsive with nav_js; reordered methods and test normaliza…
Browse files Browse the repository at this point in the history 
…tion
  • Loading branch information
@ddnexus
ddnexus committed Apr 25, 2019
1 parent ec7d754 commit d4be9dd
Show file tree
Hide file tree
Showing 30 changed files with 558 additions and 831 deletions.
2 changes: 2 additions & 0 deletions Gemfile
View file
Expand Up @@ -22,3 +22,5 @@ gem 'rubocop', '~> 0.63.1' unless ENV['SKIP_RUBOCOP']

# docs server
gem "github-pages", '193', group: :jekyll_plugins

gem 'oj'
4 changes: 3 additions & 1 deletion Gemfile.lock
View file
Expand Up @@ -209,6 +209,7 @@ GEM
mini_portile2 (~> 2.4.0)
octokit (4.13.0)
sawyer (~> 0.8.0, >= 0.5.3)
oj (3.7.11)
parallel (1.13.0)
parser (2.6.0.0)
ast (~> 2.4.0)
Expand Down Expand Up @@ -263,10 +264,11 @@ DEPENDENCIES
github-pages (= 193)
i18n
minitest
oj
rack
rake
rubocop (~> 0.63.1)
single_cov (~> 1.3)

BUNDLED WITH
1.17.2
2.0.1
2 changes: 1 addition & 1 deletion docs/api/countless.md
View file
Expand Up @@ -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` helpers that use the total `count` are not supported.
The `pagy_info` and all the `*_compact_nav_js` helpers that use the total `count` are not supported.

## How countless pagination works

Expand Down
28 changes: 15 additions & 13 deletions docs/extras.md
View file
Expand Up @@ -39,14 +39,16 @@ Extras don't define any new module or class, they just re-open the `Pagy` class

## Methods

All the added methods are documented in the respective extras.
A few extras require the [pagy/extras/shared](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/shared.rb) file. It defines only 3 methods used internally, so you don't actually need to use them directly.

**Notice**: All the other added methods are documented in the respective extras doc.

## Javascript

A few helpers use javascript:

- `pagy_*_compact_nav`
- `pagy_*_responsive_nav`
- `pagy_*_compact_nav_js`
- `pagy_*_nav_js`
- `pagy_items_selector`

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).
Expand Down Expand Up @@ -126,34 +128,34 @@ $( window ).load(function() {

### Using AJAX with javascript-enabled helpers

If you AJAX-render any of the javascript helpers mentioned above, you should also execute `Pagy.init(container_element);` in the javascript template. Here is an example for a `pagy_bootstrap_responsive_nav` AJAX-render:
If you AJAX-render any of the javascript helpers mentioned above, you should also execute `Pagy.init(container_element);` in the javascript template. Here is an example for a `pagy_bootstrap_nav_js` AJAX-render:

`pagy_remote_responsive` controller action (notice the `link_extra` to enable AJAX):
`pagy_remote_nav_js` controller action (notice the `link_extra` to enable AJAX):

```ruby
def pagy_remote_responsive
def pagy_remote_nav_js
@pagy, @records = pagy(Product.all, link_extra: 'data-remote="true"')
end
```

`pagy_remote_responsive.html.erb` template for non-AJAX render (first page-load):
`pagy_remote_nav_js.html.erb` template for non-AJAX render (first page-load):

```erb
<div id="container">
<%= render partial: 'responsive_nav' %>
<%= render partial: 'nav_js' %>
</div>
```

`_responsive_nav.html.erb` partial shared for AJAX and non-AJAX rendering:
`_nav_js.html.erb` partial shared for AJAX and non-AJAX rendering:

```erb
<%== pagy_bootstrap_responsive_nav(@pagy) %>
<%== pagy_bootstrap_nav_js(@pagy) %>
```

`pagy_remote_responsive.js.erb` javascript template used for AJAX:
`pagy_remote_nav_js.js.erb` javascript template used for AJAX:

```js-erb
$('#container').html("<%= j(render 'responsive_nav')%>");
```erb
$('#container').html("<%= j(render 'nav_js')%>");
Pagy.init(document.getElementById('container'));
```

Expand Down
14 changes: 7 additions & 7 deletions docs/extras/bootstrap.md
View file
Expand Up @@ -20,8 +20,8 @@ with a fast helper:

```erb
<%== pagy_bootstrap_nav(@pagy) %>
<%== pagy_bootstrap_responsive_nav(@pagy) %>
<%== pagy_bootstrap_compact_nav(@pagy) %>
<%== pagy_bootstrap_nav_js(@pagy) %>
<%== pagy_bootstrap_compact_nav_js(@pagy) %>
```

or with a template:
Expand All @@ -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_responsive_nav` or `pagy_bootstrap_compact_nav`.
Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_nav_js` or `pagy_bootstrap_compact_nav_js`.

## Files

Expand All @@ -49,19 +49,19 @@ This method is the same as the `pagy_nav`/`pagy_plain_nav`, but customized for B

The `bootstrap_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.

### pagy_bootstrap_compact_nav(pagy, ...)
### pagy_bootstrap_compact_nav_js(pagy, ...)

This method is the same as the `pagy_plain_compact_nav`, but customized for the Bootstrap framework.
This method is the same as the `pagy_plain_compact_nav_js`, but customized for the Bootstrap framework.

Here is an example:

![pagy-compact](../assets/images/pagy-compact-g.png)

See more details in the [compact navs](plain.md#compact-navs) documentation.

### pagy_bootstrap_responsive_nav(pagy, ...)
### pagy_bootstrap_nav_js(pagy, ...)

This method is the same as the `pagy_plain_responsive_nav`, but customized for the Bootstrap framework.
This method is the same as the `pagy_plain_nav_js`, but customized for the Bootstrap framework.

See more details in the [responsive navs](plain.md#responsive-navs) documentation.

Expand Down
14 changes: 7 additions & 7 deletions docs/extras/bulma.md
View file
Expand Up @@ -20,8 +20,8 @@ with a fast helper:

```erb
<%== pagy_bulma_nav(@pagy) %>
<%== pagy_bulma_responsive_nav(@pagy) %>
<%== pagy_bulma_compact_nav(@pagy) %>
<%== pagy_bulma_nav_js(@pagy) %>
<%== pagy_bulma_compact_nav_js(@pagy) %>
```

or with a template:
Expand All @@ -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_responsive_nav` or `pagy_bulma_compact_nav`.
Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_nav_js` or `pagy_bulma_compact_nav_js`.

## Files

Expand All @@ -49,19 +49,19 @@ This method is the same as the `pagy_nav`/`pagy_plain_nav`, but customized for B

The `bulma_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.

### pagy_bulma_compact_nav(pagy, ...)
### pagy_bulma_compact_nav_js(pagy, ...)

This method is the same as the `pagy_plain_compact_nav`, but customized for the Bulma CSS framework.
This method is the same as the `pagy_plain_compact_nav_js`, but customized for the Bulma CSS framework.

Here is an example:

![pagy-compact-bulma](../assets/images/pagy-compact-bulma-g.png)

See more details in the [compact navs](plain.md#compact-navs) documentation.

### pagy_bulma_responsive_nav(pagy, ...)
### pagy_bulma_nav_js(pagy, ...)

This method is the same as the `pagy_plain_responsive_nav`, but customized for the Bulma CSS framework.
This method is the same as the `pagy_plain_nav_js`, but customized for the Bulma CSS framework.

See more details in the [responsive navs](plain.md#responsive-navs) documentation.

Expand Down
10 changes: 5 additions & 5 deletions docs/extras/foundation.md
View file
Expand Up @@ -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_responsive_nav` or `pagy_foundation_compact_nav`.
Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_nav_js` or `pagy_foundation_compact_nav_js`.

## Files

Expand All @@ -47,15 +47,15 @@ This method is the same as the `pagy_nav`/`pagy_plain_nav`, but customized for F

The `foundation_nav.*` templates produce the same output, and can be used as an easier (but slower) starting point to override it.

### pagy_foundation_compact_nav(pagy, ...)
### pagy_foundation_compact_nav_js(pagy, ...)

This method is the same as the `pagy_plain_compact_nav`, but customized for the Foundation framework.
This method is the same as the `pagy_plain_compact_nav_js`, but customized for the Foundation framework.

See more details in the [compact navs](plain.md#compact-navs) documentation.

### pagy_foundation_responsive_nav(pagy, ...)
### pagy_foundation_nav_js(pagy, ...)

This method is the same as the `pagy_plain_responsive_nav`, but customized for the Foundation framework.
This method is the same as the `pagy_plain_nav_js`, but customized for the Foundation framework.

See more details in the [responsive navs](plain.md#responsive-navs) documentation.

Expand Down
14 changes: 7 additions & 7 deletions docs/extras/materialize.md
View file
Expand Up @@ -20,11 +20,11 @@ with a fast helper:

```erb
<%== pagy_materialize_nav(@pagy) %>
<%== pagy_materialize_responsive_nav(@pagy) %>
<%== pagy_materialize_compact_nav(@pagy) %>
<%== pagy_materialize_nav_js(@pagy) %>
<%== pagy_materialize_compact_nav_js(@pagy) %>
```

Configure [javascript](../extras.md#javascript) if you use `pagy_materialize_responsive_nav` or `pagy_materialize_compact_nav`.
Configure [javascript](../extras.md#javascript) if you use `pagy_materialize_nav_js` or `pagy_materialize_compact_nav_js`.

## Files

Expand All @@ -38,19 +38,19 @@ This extra adds 3 nav helpers to the `Pagy::Frontend` module. You can customize

This method is the same as the `pagy_nav`/`pagy_plain_nav`, but customized for Materialize.

### pagy_materialize_compact_nav(pagy, ...)
### pagy_materialize_compact_nav_js(pagy, ...)

This method is the same as the `pagy_plain_compact_nav`, but customized for the Materialize CSS framework.
This method is the same as the `pagy_plain_compact_nav_js`, but customized for the Materialize CSS framework.

Here is an example:

![pagy-compact-materialize](../assets/images/pagy-compact-materialize-g.png)

See more details in the [compact navs](plain.md#compact-navs) documentation.

### pagy_materialize_responsive_nav(pagy, ...)
### pagy_materialize_nav_js(pagy, ...)

This method is the same as the `pagy_plain_responsive_nav`, but customized for the Materialize CSS framework.
This method is the same as the `pagy_plain_nav_js`, but customized for the Materialize CSS framework.

See more details in the [responsive navs](plain.md#responsive-navs) documentation.

Expand Down
62 changes: 30 additions & 32 deletions docs/extras/plain.md
View file
Expand Up @@ -3,7 +3,7 @@ title: Plain
---
# Plain Extra

This extra adds a couple of nav helpers to the `Pagy::Frontend` module: `pagy_plain_compact_nav` and `pagy_plain_responsive_nav`. It also adds the `:pagy_plain_nav` alias (pointing to the `:pagy_nav` for naming consistency). These are the plain/unstyled nav helpers for pagination.
This extra adds a couple of nav helpers to the `Pagy::Frontend` module: `pagy_plain_compact_nav_js` and `pagy_plain_nav_js`. It also adds the `:pagy_plain_nav` alias (pointing to the `:pagy_nav` for naming consistency). These are the plain/unstyled nav helpers for pagination.

Other extras (e.g. [bootstrap](bootstrap.md), [bulma](bulma.md), [foundation](foundation.md), [materialize](materialize.md), [semantic](semantic.md)) provide framework-styled versions of the same `nav`, `responsive` and `compact` helpers, so you may not need this extra if you use one of those.

Expand Down Expand Up @@ -34,26 +34,26 @@ It is especially useful for small size screens, but it is used also with wide la
Use the responsive helper(s) in any view:

```erb
<%== pagy_plain_compact_nav(@pagy) %>
<%== pagy_plain_compact_nav_js(@pagy) %>
```

Other extras provide also the following framework-styled helpers:

```erb
<%== pagy_bootstrap_compact_nav(@pagy) %>
<%== pagy_bulma_compact_nav(@pagy) %>
<%== pagy_foundation_compact_nav(@pagy) %>
<%== pagy_materialize_compact_nav(@pagy) %>
<%== pagy_semantic_compact_nav(@pagy) %>
<%== pagy_bootstrap_compact_nav_js(@pagy) %>
<%== pagy_bulma_compact_nav_js(@pagy) %>
<%== pagy_foundation_compact_nav_js(@pagy) %>
<%== pagy_materialize_compact_nav_js(@pagy) %>
<%== pagy_semantic_compact_nav_js(@pagy) %>
```

## Methods

### pagy_plain_compact_nav(pagy, ...)
### pagy_plain_compact_nav_js(pagy, ...)

Renders a compact navigation with a style similar to the `pagy_nav` helper.

It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_responsive_nav` or `pagy_*_compact_nav` call in the same line for the same page.
It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_nav_js` or `pagy_*_compact_nav_js` call in the same line for the same page.

**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.

Expand All @@ -68,65 +68,63 @@ Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav
## Synopsis

```ruby
# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance)
Pagy::VARS[:breakpoints] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] }
# set your default custom sizes (width/size pairs) globally (it can be overridden per Pagy instance)
Pagy::VARS[:sizes] = { 0 => [1,0,0,1], 540 => [2,3,3,2], 720 => [3,4,4,3] }
```

Use the responsive helper(s) in any view:

```erb
<%== pagy_plain_responsive_nav(@pagy) %>
<%== pagy_plain_nav_js(@pagy) %>
```

Other extras provide also the following framework-styled helpers:

```erb
<%== pagy_bootstrap_responsive_nav(@pagy) %>
<%== pagy_bulma_responsive_nav(@pagy) %>
<%== pagy_foundation_responsive_nav(@pagy) %>
<%== pagy_materialize_responsive_nav(@pagy) %>
<%== pagy_semantic_responsive_nav(@pagy) %>
<%== pagy_bootstrap_nav_js(@pagy) %>
<%== pagy_bulma_nav_js(@pagy) %>
<%== pagy_foundation_nav_js(@pagy) %>
<%== pagy_materialize_nav_js(@pagy) %>
<%== pagy_semantic_nav_js(@pagy) %>
```

## Variables

### :breakpoints
### :sizes

The `:breakpoints` variable is a non-core variable used by the `responsive` navs. It allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the Pagy `:size` variables to be applied for that width.
The `:sizes` variable is a non-core variable used by the `responsive` navs. It allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the widths in pixels and the values are the Pagy `:size` variables to be applied for that width.
For example:

```ruby
Pagy::VARS[:breakpoints] = { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] }
Pagy::VARS[:sizes] = { 0 => [2,3,3,2], 540 => [3,5,5,3], 720 => [5,7,7,5] }
```

The above statement means that from `0` to `540` pixels width, Pagy will use the `[2,3,3,2]` size, from `540` to `720` it will use the `[3,5,5,3]` size and over `720` it will use the `[5,7,7,5]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section).

**IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing.
**IMPORTANT**: You can set any number of sizes with any arbitrary width and size. The only requirement is that the `:sizes` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing.

**Notice**: Each added breakpoint slowers down Pagy of less than 10%. For example: with 5 breakpoints the nav will be rendered rougly in less than twice the normal time. That will still run about 16 times faster than Kaminari and 7 times faster than WillPaginate, so it doesn't look like an issue.
#### Setting the right sizes

#### Setting the right breakpoints

Setting the width and the size of your breakpoints is what can create a nice transition between sizes... or some apparently erratic behavior.
Setting the width and the size of your sizes is what can create a nice transition between sizes... or some apparently erratic behavior.

Here is what you should consider/ensure:

1. The pagy size can only change in discrete steps: each widht/size pair in your `:breakpoints` represents a step.
1. The pagy size can only change in discrete steps: each widht/size pair in your `:sizes` represents a step.

2. The transition from one breakpoint/size to another depends on the width available to the pagy nav. That width is the _internal available width_ of its container (excluding eventual horizontal padding).
2. The transition from one size to another depends on the width available to the pagy nav. That width is the _internal available width_ of its container (excluding eventual horizontal padding).

3. You should ensure that each pagy `:size` in your breakpoints produces a nav that can be contained in its its width.
3. You should ensure that each pagy `:size` in your `sizes` produces a nav that can be contained in its its width.

4. You should ensure that the minimum internal width for the container div be equal (or a bit bigger) to the smaller positive `:breakpoints` width. (`540` pixels in our previous example).
4. You should ensure that the minimum internal width for the container div be equal (or a bit bigger) to the smaller positive `:sizes` width. (`540` pixels in our previous example).

5. If the container width snaps to specific widths in discrete steps, you should sync the quantity and widths of the pagy `:brakpoints` to the quantity and internal widths for each discrete step of the container.
5. If the container width snaps to specific widths in discrete steps, you should sync the quantity and widths of the pagy `:sizes` to the quantity and internal widths for each discrete step of the container.

## Methods

### pagy_plain_responsive_nav(pagy, ...)
### pagy_plain_nav_js(pagy, ...)

Similar to the `pagy_nav` helper, with added responsiveness.

It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_responsive_nav` or `pagy_*_compact_nav` call in the same line for the same file.
It can take an extra `id` argument, which is used to build the `id` attribute of the `nav` tag. Since the internal automatic id assignation is based on the code line where you use the helper, you _must_ pass an explicit id if you are going to use more than one `pagy_*_nav_js` or `pagy_*_compact_nav_js` call in the same line for the same file.

**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.

0 comments on commit d4be9dd

Please sign in to comment.