You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/extras.md
+15-13Lines changed: 15 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,14 +39,16 @@ Extras don't define any new module or class, they just re-open the `Pagy` class
39
39
40
40
## Methods
41
41
42
-
All the added methods are documented in the respective extras.
42
+
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.
43
+
44
+
**Notice**: All the other added methods are documented in the respective extras doc.
43
45
44
46
## Javascript
45
47
46
48
A few helpers use javascript:
47
49
48
-
-`pagy_*_compact_nav`
49
-
-`pagy_*_responsive_nav`
50
+
-`pagy_*_compact_nav_js`
51
+
-`pagy_*_nav_js`
50
52
-`pagy_items_selector`
51
53
52
54
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).
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:
131
+
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:
130
132
131
-
`pagy_remote_responsive` controller action (notice the `link_extra` to enable AJAX):
133
+
`pagy_remote_nav_js` controller action (notice the `link_extra` to enable AJAX):
Copy file name to clipboardExpand all lines: docs/extras/plain.md
+30-32Lines changed: 30 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ title: Plain
3
3
---
4
4
# Plain Extra
5
5
6
-
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.
6
+
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.
7
7
8
8
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.
9
9
@@ -34,26 +34,26 @@ It is especially useful for small size screens, but it is used also with wide la
34
34
Use the responsive helper(s) in any view:
35
35
36
36
```erb
37
-
<%== pagy_plain_compact_nav(@pagy) %>
37
+
<%== pagy_plain_compact_nav_js(@pagy) %>
38
38
```
39
39
40
40
Other extras provide also the following framework-styled helpers:
41
41
42
42
```erb
43
-
<%== pagy_bootstrap_compact_nav(@pagy) %>
44
-
<%== pagy_bulma_compact_nav(@pagy) %>
45
-
<%== pagy_foundation_compact_nav(@pagy) %>
46
-
<%== pagy_materialize_compact_nav(@pagy) %>
47
-
<%== pagy_semantic_compact_nav(@pagy) %>
43
+
<%== pagy_bootstrap_compact_nav_js(@pagy) %>
44
+
<%== pagy_bulma_compact_nav_js(@pagy) %>
45
+
<%== pagy_foundation_compact_nav_js(@pagy) %>
46
+
<%== pagy_materialize_compact_nav_js(@pagy) %>
47
+
<%== pagy_semantic_compact_nav_js(@pagy) %>
48
48
```
49
49
50
50
## Methods
51
51
52
-
### pagy_plain_compact_nav(pagy, ...)
52
+
### pagy_plain_compact_nav_js(pagy, ...)
53
53
54
54
Renders a compact navigation with a style similar to the `pagy_nav` helper.
55
55
56
-
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.
56
+
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.
57
57
58
58
**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.
59
59
@@ -68,65 +68,63 @@ Here is a screenshot (from the `bootstrap`extra) of how the same pagination nav
68
68
## Synopsis
69
69
70
70
```ruby
71
-
# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance)
Other extras provide also the following framework-styled helpers:
82
82
83
83
```erb
84
-
<%== pagy_bootstrap_responsive_nav(@pagy) %>
85
-
<%== pagy_bulma_responsive_nav(@pagy) %>
86
-
<%== pagy_foundation_responsive_nav(@pagy) %>
87
-
<%== pagy_materialize_responsive_nav(@pagy) %>
88
-
<%== pagy_semantic_responsive_nav(@pagy) %>
84
+
<%== pagy_bootstrap_nav_js(@pagy) %>
85
+
<%== pagy_bulma_nav_js(@pagy) %>
86
+
<%== pagy_foundation_nav_js(@pagy) %>
87
+
<%== pagy_materialize_nav_js(@pagy) %>
88
+
<%== pagy_semantic_nav_js(@pagy) %>
89
89
```
90
90
91
91
## Variables
92
92
93
-
### :breakpoints
93
+
### :sizes
94
94
95
-
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.
95
+
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.
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).
103
103
104
-
**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.
104
+
**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.
105
105
106
-
**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.
106
+
#### Setting the right sizes
107
107
108
-
#### Setting the right breakpoints
109
-
110
-
Setting the width and the size of your breakpoints is what can create a nice transition between sizes... or some apparently erratic behavior.
108
+
Setting the width and the size of your sizes is what can create a nice transition between sizes... or some apparently erratic behavior.
111
109
112
110
Here is what you should consider/ensure:
113
111
114
-
1. The pagy size can only change in discrete steps: each widht/size pair in your `:breakpoints` represents a step.
112
+
1. The pagy size can only change in discrete steps: each widht/size pair in your `:sizes` represents a step.
115
113
116
-
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).
114
+
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).
117
115
118
-
3. You should ensure that each pagy `:size` in your breakpoints produces a nav that can be contained in its its width.
116
+
3. You should ensure that each pagy `:size` in your `sizes` produces a nav that can be contained in its its width.
119
117
120
-
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).
118
+
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).
121
119
122
-
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.
120
+
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.
123
121
124
122
## Methods
125
123
126
-
### pagy_plain_responsive_nav(pagy, ...)
124
+
### pagy_plain_nav_js(pagy, ...)
127
125
128
126
Similar to the `pagy_nav` helper, with added responsiveness.
129
127
130
-
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.
128
+
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.
131
129
132
130
**Notice**: passing an explicit id is also a bit faster than having pagy to generate one.
0 commit comments