Skip to content

Commit

Permalink
Docs: fixes and improvements, code indentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed Jan 7, 2024
1 parent 2d313e8 commit 8405937
Show file tree
Hide file tree
Showing 10 changed files with 81 additions and 72 deletions.
4 changes: 2 additions & 2 deletions docs/api/javascript/ajax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If you AJAX-render any of the javascript helpers mentioned above, you should als
```ruby
def pagy_remote_nav_js
# notice the link_extra to enable Ajax
@pagy, @products = pagy(Product.all, link_extra: 'data-remote="true"')
@pagy, @products = pagy(collection, link_extra: 'data-remote="true"')
end
```
|||
Expand All @@ -40,7 +40,7 @@ Pagy.init(document.getElementById('container'));
````
|||

!!!primary Don't forget to re-initialize!
!!!warning Don't forget to re-initialize!
The `document.getElementById('container')` argument will re-init the pagy elements just AJAX-rendered in the container div. If you miss it, it will not work.
!!!
55 changes: 28 additions & 27 deletions docs/api/pagy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ Experimental: Its only function in the `Pagy` class is supporting the API of var
==- `label_for(page)`

Experimental: Its only function in the `Pagy` class is supporting the API of various frontend methods that require labelling for `Pagy::Calendar` instances. It returns the page label that will get displayed in the helpers/templates.
===

===

## Variables

Expand All @@ -125,39 +125,40 @@ They are all integers:

### Other Variables

| 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 [How to control the page links](/docs/how-to.md#control-the-page-links))_ | `[1,4,4,1]` |
| `:page_param` | The name of the page param name used in the url. _(see [How to customize the page param](/docs/how-to.md#customize-the-page-param))_ | `:page` |
| `:params` | It can be a `Hash` of params to add to the URL, or a `Proc` that can edit/add/delete the request params _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `{}` |
| `:fragment` | The arbitrary fragment string (including the "#") to add to the url. _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `""` |
| `:link_extra` | The extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [How to customize the link attributes](/docs/how-to.md#customize-the-link-attributes))_ | `""` |
| `:i18n_key` | The i18n key to lookup the `item_name` that gets interpolated in a few helper outputs (see [How to customize the item name](/docs/how-to.md#customize-the-item-name)) | `"pagy.item_name"` |
| `:cycle` | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` |
| `:request_path` | Allows overriding the request path for pagination links. If left blank, helpers will use `request.path`. NB: Do not pass in a full URL, but the path: For example, given `https://ddnexus.github.io/pagy/docs/api/pagy/` the path to be passed in is: `pagy/docs/api/pagy/`. (See: [Customize the request path](/docs/how-to.md#customize-the-request-path) )| `request.path` |
| 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 [How to control the page links](/docs/how-to.md#control-the-page-links))_ | `[1,4,4,1]` |
| `:page_param` | The name of the page param name used in the url. _(see [How to customize the page param](/docs/how-to.md#customize-the-page-param))_ | `:page` |
| `:params` | It can be a `Hash` of params to add to the URL, or a `Proc` that can edit/add/delete the request params _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `{}` |
| `:fragment` | The arbitrary fragment string (including the "#") to add to the url. _(see [How to customize the params](/docs/how-to.md#customize-the-params))_ | `""` |
| `:link_extra` | The extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [How to customize the link attributes](/docs/how-to.md#customize-the-link-attributes))_ | `""` |
| `:i18n_key` | The i18n key to lookup the `item_name` that gets interpolated in a few helper outputs (see [How to customize the item name](/docs/how-to.md#customize-the-item-name)) | `"pagy.item_name"` |
| `:cycle` | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` |
| `:request_path` | Allows overriding the request path for pagination links. If left blank, helpers will use `request.path`. NB: Do not pass in a full URL, but the path: For example, given `https://ddnexus.github.io/pagy/docs/api/pagy/` the path to be passed in is: `pagy/docs/api/pagy/`. (See: [Customize the request path](/docs/how-to.md#customize-the-request-path) ) | `request.path` |
| `jsonapi` | Enable `jsonapi` compliance of the pagy query params | `false` |

There is no specific validation for non-instance variables.

### Attribute Readers

Pagy exposes all the instance variables needed for the pagination through a few attribute readers. They all return integers (or `nil`), except the `vars` hash:

| Reader | Description |
|:---------|:-------------------------------------------------------------------------------------------------------------------|
| `count` | The collection `:count` |
| `page` | The current page number |
| `items` | The requested number of items for the page |
| `pages` | The number of total pages in the collection (same as `last` but with cardinal meaning) |
| `in` | The number of the items in the page |
| `last` | The number of the last page in the collection (same as `pages` but with ordinal meaning) |
| `offset` | The number of items skipped from the collection in order to get the start of the current page (`:outset` included) |
| `from` | The collection-position of the first item in the page (`:outset` excluded) |
| `to` | The collection-position of the last item in the page (`:outset` excluded) |
| `prev` | The previous page number or `nil` if there is no previous page |
| `next` | The next page number or `nil` if there is no next page |
| `vars` | The variables hash |
| `params` | The `:params` variable (`Hash` or `Proc`) |
| `request_path` | The request path used for pagination helpers. If blank, helpers will use `request.path` |
| Reader | Description |
|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `count` | The collection `:count` |
| `page` | The current page number |
| `items` | The requested number of items for the page |
| `pages` | The number of total pages in the collection (same as `last` but with cardinal meaning) |
| `in` | The number of the items in the page |
| `last` | The number of the last page in the collection (same as `pages` but with ordinal meaning) |
| `offset` | The number of items skipped from the collection in order to get the start of the current page (`:outset` included) |
| `from` | The collection-position of the first item in the page (`:outset` excluded) |
| `to` | The collection-position of the last item in the page (`:outset` excluded) |
| `prev` | The previous page number or `nil` if there is no previous page |
| `next` | The next page number or `nil` if there is no next page |
| `vars` | The variables hash |
| `params` | The `:params` variable (`Hash` or `Proc`) |
| `request_path` | The request path used for pagination helpers. If blank, helpers will use `request.path` |

### Lowest limit analysis

Expand Down
10 changes: 5 additions & 5 deletions docs/extras/gearbox.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,19 +44,19 @@ Pagy::DEFAULT[:gearbox_items] = [10, 20, 50] # your own default
||| Controller (action)
```ruby
# Optionally override the :gearbox_items variable to a constructor to have it only for that instance
@pagy, @records = pagy(Product.all, gearbox_items: [30, 60, 100], ...)
@pagy, @records = pagy(collection, gearbox_items: [30, 60, 100], ...)

# You can still use instances with fixed pagination even after requiring the extra
# use the default Pagy::DEFAULT[:items]
@pagy, @records = pagy(Product.all, gearbox_extra: false)
@pagy, @records = pagy(collection, gearbox_extra: false)
# use the passed items: 30
@pagy, @records = pagy(Product.all, gearbox_extra: false, items: 30)
@pagy, @records = pagy(collection, gearbox_extra: false, items: 30)

# If you use also the items extra it must be disabled in the instance that use the gearbox
# use the default Pagy::DEFAULT[:gearbox_items]
@pagy, @records = pagy(Product.all, items_extra: false)
@pagy, @records = pagy(collection, items_extra: false)
# use the passed gearbox_items: [30, 60, 100]
@pagy, @records = pagy(Product.all, items_extra: false, gearbox_items: [30, 60, 100])
@pagy, @records = pagy(collection, items_extra: false, gearbox_items: [30, 60, 100])
```
|||

Expand Down
6 changes: 3 additions & 3 deletions docs/extras/headers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ require 'pagy/extras/headers'
||| Controller (action)
```ruby
# paginate as usual with any pagy_* backend constructor
pagy, records = pagy(Product.all)
pagy, records = pagy(collection)
# explicitly merge the headers to the response
pagy_headers_merge(pagy)
render json: records
Expand All @@ -44,7 +44,7 @@ Instead of explicitly merging the headers before each rendering, if you use rail
after_action { pagy_headers_merge(@pagy) if @pagy }

# and use it in any action (notice @pagy that enables the merging)
@pagy, records = pagy(Product.all)
@pagy, records = pagy(collection)
render json: records
```
|||
Expand All @@ -60,7 +60,7 @@ def pagy_render(collection, vars={})
end

# and use it in your standard actions:
pagy_render(Product.all)
pagy_render(collection)
```
|||

Expand Down
Loading

0 comments on commit 8405937

Please sign in to comment.