Skip to content

Commit

Permalink
Merge branch 'dev'
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed Apr 9, 2024
2 parents 55c6955 + 79dd031 commit df9a960
Show file tree
Hide file tree
Showing 43 changed files with 337 additions and 274 deletions.
37 changes: 33 additions & 4 deletions .github/ISSUE_TEMPLATE/Code.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ body:
attributes:
label: Before submitting...
options:
- label: I upgraded to pagy version 8.0.2
- label: I upgraded to pagy version 8.1.0
required: true
- label: I searched through the [Documentation](https://ddnexus.github.io/pagy/)
required: true
Expand All @@ -37,17 +37,46 @@ body:
OR it will be automatically closed!**
#### Valid code files
#### VALID code files
- Edited copy of a single-file APP from the [Pagy Playground](https://ddnexus.github.io/pagy/playground)
- Link to a pagy fork containing an added test file
- A plain ruby file that can run as a single command `ruby issue_123.rb`
- A plain ruby file that can run as a single command like `ruby my_issue.rb`
_(without any other setup step, installation or guessing, and with no or minimal interaction required)_
#### INVALID "code"
- EVERYTHING other than the above!
- Totally useless things like (but not limited to):
- Code snippets
- Multiple files
- Complex setup
- Complete applications
- Any description of errors generated by running your own code
- Rationalizations about "WHY" and "WHAT" you think it's a bug
Please, understand that we won't guess your environment/usage/configuration/conflicts out of some snippet
or description, nor clone/install/setup/debug your complete application.
Please, start from a [pagy APP](https://ddnexus.github.io/pagy/playground/#pagy-apps)
and add the minimum that makes it fail. It's a very simple process and, most of the times,
it will make your issue just "disappear". ;)
_If anything is unclear to you, please ask for [support](https://github.com/ddnexus/pagy/discussions/categories/q-a).
We will be happy to help._
Expand All @@ -66,7 +95,7 @@ body:
attributes:
label: Description
placeholder: >
1. Describe what actually happens
1. Describe what actually happens WITH THE CODE FILE you provided
2. Describe what should happen instead
validations:
Expand Down
15 changes: 6 additions & 9 deletions .github/latest_release_body.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,18 @@ If you wish to keep your favorites alive, please, [vote here](https://github.com
### ✴ What's new in 8.+ ✴

- Better frontend helpers
- New `:max_pages` variable to limit the pagination regardless the actual count
- New [Pagy Playground](https://ddnexus.github.io/pagy/playground/) to showcase, clone and develop pagy APPs without any setup on
your side (try the [pagy demo](https://ddnexus.github.io/pagy/playground.md#3-demo-app))
- See the [CHANGELOG](https://ddnexus.github.io/pagy/changelog) for possible breaking changes

### Changes
### Changes in 8.1.0

<!-- changes start -->
- Minor change in rails app and RM run config
- Fix canonical gem root:
- Correct script.build: "NODE_PATH=\"$(bundle show 'pagy')/javascripts\"
- Move pagy.gemspec inside the gem root dir
- Fix for Turbo not intercepting changes in window.location
- Use require_relative for gem/lib files
- Complete translation of aria.nav for "ru" locale (close #599)
- Docs improvement and fixes
- Implement max_pages to limit the pagination regardless the actual count
- Improve efficiency of params in pagy_url_for
- Remove nil variables from DEFAULT
- Removed redundant @pages, aliased with @last
<!-- changes end -->

[CHANGELOG](https://ddnexus.github.io/pagy/changelog)
10 changes: 9 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,17 @@ If you upgrade from version `< 8.0.0` see the following:

## Deprecations

None
- Protected method `Pagy#setup_pages_var`. Use `Pagy#setup_last_var` instead

<hr>

## Version 8.1.0

- Implement max_pages to limit the pagination regardless the actual count
- Improve efficiency of params in pagy_url_for
- Remove nil variables from DEFAULT
- Removed redundant @pages, aliased with @last

## Version 8.0.2

- Minor change in rails app and RM run config
Expand Down
10 changes: 5 additions & 5 deletions Gemfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ group :apps do
gem 'sinatra-contrib'
end

group :performance do
gem 'benchmark-ips'
gem 'kalibera'
gem 'memory_profiler'
end
# group :performance do
# gem 'benchmark-ips'
# gem 'kalibera'
# gem 'memory_profiler'
# end
12 changes: 1 addition & 11 deletions Gemfile.lock
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ GEM
ansi (1.5.0)
ast (2.4.2)
base64 (0.2.0)
benchmark-ips (2.13.0)
bigdecimal (3.1.7)
builder (3.2.4)
concurrent-ruby (1.2.3)
Expand All @@ -40,18 +39,13 @@ GEM
i18n (1.14.4)
concurrent-ruby (~> 1.0)
json (2.7.2)
kalibera (0.1.2)
memoist (~> 0.16)
rbzip2 (~> 0.3)
language_server-protocol (3.17.0.3)
listen (3.9.0)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
llhttp-ffi (0.5.0)
ffi-compiler (~> 1.0)
rake (~> 13.0)
memoist (0.16.2)
memory_profiler (1.0.1)
minitest (5.22.3)
minitest-reporters (1.6.1)
ansi
Expand Down Expand Up @@ -87,15 +81,14 @@ GEM
rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)
rbzip2 (0.3.0)
readline-ext (0.2.0)
regexp_parser (2.9.0)
rematch (2.1.0)
rerun (0.14.0)
listen (~> 3.0)
rexml (3.2.6)
rouge (4.2.1)
rubocop (1.62.1)
rubocop (1.63.0)
json (~> 2.3)
language_server-protocol (>= 3.17.0)
parallel (~> 1.10)
Expand Down Expand Up @@ -149,11 +142,8 @@ PLATFORMS

DEPENDENCIES
activesupport
benchmark-ips
http
i18n
kalibera
memory_profiler
minitest
minitest-reporters
oj
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file

Large diffs are not rendered by default.

83 changes: 39 additions & 44 deletions docs/api/pagy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,48 +113,44 @@ for `Pagy::Calendar` instances. It returns the page label that will get displaye

## Variables

All the variables passed to the new method will be merged with the `Pagy::DEFAULT` hash and will be kept in the object, passed
All the variables passed to the new method are merged with the `Pagy::DEFAULT` hash and are kept in the object, passed
around with it and accessible through the `pagy.vars` hash.

They can be set globally by using the `Pagy::DEFAULT` hash or passed to the `Pagy.new` method and are accessible through
the `vars` reader.

**Notice**: Pagy replaces the blank values of the passed variables with their default values coming from the `Pagy::DEFAULT` hash.
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.

### Instance Variables
!!!success
Pagy replaces the blank values of the passed variables with their default values coming from the `Pagy::DEFAULT` hash.
It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without any problem.
For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
!!!

A few variables are particularly important for the calculation of the pagination, and therefore are validated and used to
initialize a few instance variables.
### Variables

The only mandatory instance variable to be passed 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.
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 had an offset | `0` |

### Other Variables

| Variable | Description | Default |
|:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
| `:size` | The size of the page links to show: can be an array of initial pages, before current page, after current page, final pages or the total page size. _(see also [How to control the page links](/docs/how-to.md#control-the-page-links))_ | `7` |
| `: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))_ | `''` |
| `:anchor_string` | 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))_ | `nil` |
| `: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. Pass the path only (not the absolute url). _(see [Customize the request path](/docs/how-to.md#customize-the-request-path))_ | `nil` |
| `jsonapi` | Enable `jsonapi` compliance of the pagy query params | `false` |
| `count_args` | The arguments passed to the `collection.count`. You may want to set it to `[]` in ORMs different than ActiveRecord | [:all] |

There is no specific validation for non-instance variables.

| Variable | Description | Default |
|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
| `:anchor_string` | The extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links _(see [Customize the link attributes](/docs/how-to.md#customize-the-link-attributes))_ | `nil` |
| `:count` | The total count of the collection to paginate (mandatory argument) | `nil` |
| `:count_args` | The arguments passed to the `collection.count`. You may want to set it to `[]` in ORMs different than ActiveRecord | [:all] |
| `:cycle` | Enable cycling/circular/infinite pagination: `true` sets `next` to `1` when the current page is the last page | `false` |
| `:fragment` | The arbitrary fragment string (including the "#") to add to the url. _(see [Customize the params](/docs/how-to.md#customize-the-params))_ | `nil` |
| `:items` | The requested number of items for the page | `20` |
| `:jsonapi` | Enable `jsonapi` compliance of the pagy query params | `false` |
| `:max_pages` | Paginate only `:max_pages`. _(see also [Paginate only max_pages](/docs/how-to.md#paginate-only-max_pages-regardless-the-count))_ | `nil` |
| `:outset` | The initial offset of the collection to paginate: pass it only if the collection had an offset | `0` |
| `:page` | The requested page number: extracted from the `request.params`, or forced by passeing a variable | `1` |
| `:page_param` | The name of the page param name used in the url. _(see [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 [Customize the params](/docs/how-to.md#customize-the-params))_ | `{}` |
| `:request_path` | Allows overriding the request path for pagination links. Pass the path only (not the absolute url). _(see [Customize the request path](/docs/how-to.md#customize-the-request-path))_ | `nil` |
| `:size` | The size of the page links to show: can be an array of 4 items or the integer of the total page size. _(see also [Control the page links](/docs/how-to.md#control-the-page-links))_ | `7` |

!!!
Extras may add and document their own variables
!!!

### Attribute Readers

Expand All @@ -164,19 +160,19 @@ 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 |
| `in` | The number of the items in the page |
| `items` | The requested number of items for the page |
| `last` | The number of the last page in the collection (ordinal meaning) |
| `next` | The next page number or `nil` if there is no next page |
| `vars` | The variables hash |
| `offset` | The number of items skipped from the collection in order to get the start of the current page (`:outset` included) |
| `page` | The current page number |
| `pages` | Alias for `last` (cardinal meaning) |
| `params` | The `:params` variable (`Hash` or `Proc`) |
| `prev` | The previous page number or `nil` if there is no previous page |
| `request_path` | The request path used for pagination helpers. If nil, helpers will use `request.path` |
| `to` | The collection-position of the last item in the page (`:outset` excluded) |
| `vars` | The variables hash |

### Lowest limit analysis

Expand All @@ -187,7 +183,6 @@ the following peculiar attributes:
|:----------|:--------|
| `count` | `0` |
| `page` | `1` |
| `pages` | `1` |
| `last` | `1` |
| `in` | `0` |
| `from` | `0` |
Expand All @@ -199,12 +194,12 @@ the following peculiar attributes:
Which means:

- there is always a `page` #`1` in the pagination, even if it's empty
- `pages` and `last` are always at least both `1`
- `last` is always at least `1`
- the `series` array contains always at least the page #`1`, which for a single page is also the current page, thus a string.
With `size: []` the `series` method returns `[]`
- `in`, `from` and `to` of an empty page are all `0`
- `prev` and `next` of a single page (not necessary an empty one) are both `nil` (i.e. there is no other page)

===

## Exceptions
Expand Down
Loading

0 comments on commit df9a960

Please sign in to comment.