Skip to content

Commit

Permalink
docs and comments refactoring, also updated for pagy-extras v0.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed May 27, 2018
1 parent 46f235e commit 92260b5
Show file tree
Hide file tree
Showing 13 changed files with 150 additions and 67 deletions.
44 changes: 28 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,53 +72,65 @@ Or - if you prefer - render the navigation links with a template:
<%== render 'pagy/nav', locals: {pagy: @pagy} %>
```

### Easy to extend
## Easy to extend

Use the official extras contained in the [pagy-extras](https://github.com/ddnexus/pagy-extras) gem, or write your own in just a few lines:
Use the official extras contained in the [pagy-extras](https://github.com/ddnexus/pagy-extras) gem, or write your own in just a few lines.

### Frontend Extras

#### Bootstrap Extra

This extra adds a nav helper and a few templates compatible with the Bootstrap pagination ([more info...](http://ddnexus.github.io/pagy/pagy-extras/bootstrap)).
Nav helper and templates for Bootstrap pagination. ([More info...](http://ddnexus.github.io/pagy/pagy-extras/bootstrap))

#### Responsive Extra

This extra adds responsiveness to the pagination UI. The number of page links will adapt in real-time to the available window or container width. Here is an example of how the same pagination nav will look like by resizing the browser window:
On resize, the number of page links will adapt in real-time to the available window or container width.

![pagy-responsive](docs/assets/images/pagy-responsive-w.png)

([more info...](http://ddnexus.github.io/pagy/pagy-extras/responsive))
([More info...](http://ddnexus.github.io/pagy/pagy-extras/responsive))

#### Compact Extra

This extra adds an alternative pagination UI that joins the pagination feature with the navigation info in one compact element. It is especially useful for small size screens.
An alternative UI that combines the pagination feature with the navigation info in one compact element.

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

([more info...](http://ddnexus.github.io/pagy/pagy-extras/compact))
([More info...](http://ddnexus.github.io/pagy/pagy-extras/compact))

### Backend Extras

More specialized backend methods for specific types of collection that play well with each other and avoid overriding.

## Support, Comments and Feature Requests
#### Array Extra

[![Join the chat at https://gitter.im/ruby-pagy/Lobby](https://badges.gitter.im/ruby-pagy/Lobby.svg)](https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Paginate arrays effiently avoiding expensive array-wrapping and wihout overriding. ([More info...](http://ddnexus.github.io/pagy/pagy-extras/array))

## Chat Support and Feedback

[Chat on Gitter](https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## Useful Links

- [Documentation](https://ddnexus.github.io/pagy/index)
- [Gems Comparison](https://ddnexus.github.io/pagination-comparison/gems.html)
- [Pagination Comparison App Repository](http://github.com/ddnexus/pagination-comparison)
- [Benchmarks and Memory Profiles Source](http://github.com/ddnexus/pagination-comparison)

## Help Wanted

Pagy is a fresh project and your help would be great. If you like it, you have a few options to contribute:

- write a tutorial or a post or even just a tweet (pagy is young and needs to be known)
- write a "How To" topic (the documentation is covering the basics and there is a lot of space for additions)
- submit some cool extra
- submit a pull request to make pagy even faster, save more memory or improve its usability
- create an issue if anything should be improved/fixed
- Write a tutorial or a post or even just a tweet (pagy is young and needs to be known)
- Write a "How To" topic (the documentation is covering the basics and there is a lot of space for additions)
- Submit some cool extra
- Submit a pull request to make pagy even faster, save more memory or improve its usability
- Create an issue if anything should be improved/fixed

## Branches and Pull Requests

`master` is the latest rubygem-published release: you should use it as the base branch for pull requests, because it will not be force-rebased. `dev` is the development branch that will receive your pull requests, and that get merged into `master` before a new release. Expect `dev` to be force-rebased, so it's probably wise not to use it as the base for your commits.
`master` is the latest rubygem-published release (plus documentation-only changes about the current version): you should use it as the base branch for pull requests, because it will not be force-rebased.

`dev` is the development branch that is kept rebased on top of `master`, so expect it to be force-rebased (i.e. do not use it as the base for your commits). Use `dev` as a preview for trying the new code that will be merged in the next release, but please, don't use it as the base branch for pull requests.

## License

Expand Down
3 changes: 2 additions & 1 deletion docs/_layouts/default.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@
<a href="{{ site.baseurl }}/pagy-extras/bootstrap"><p class="indent1" {% if page.title == 'Bootstrap' %}id="active"{% endif %} >Bootstrap</p></a>
<a href="{{ site.baseurl }}/pagy-extras/responsive"><p class="indent1" {% if page.title == 'Responsive' %}id="active"{% endif %} >Responsive</p></a>
<a href="{{ site.baseurl }}/pagy-extras/compact"><p class="indent1" {% if page.title == 'Compact' %}id="active"{% endif %} >Compact</p></a>
<a href="{{ site.baseurl }}/pagy-extras/array"><p class="indent1" {% if page.title == 'Array' %}id="active"{% endif %} >Array</p></a>
<a href="{{ site.baseurl }}/migration-tips"><p {% if page.title == 'Migration Tips' %}id="active"{% endif %} >Migration Tips</p></a>
<p id="gitter-badge"><a href="https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" rel="nofollow" target="_blank"><img src="https://camo.githubusercontent.com/1adf5e58915e2093fd2e856136ae26c99e2ae214/68747470733a2f2f6261646765732e6769747465722e696d2f727562792d706167792f4c6f6262792e737667" alt="Join the chat at https://gitter.im/ruby-pagy/Lobby" data-canonical-src="https://badges.gitter.im/ruby-pagy/Lobby.svg" style="max-width:100%;"></a></p>
<p id="gitter-support"><a href="https://gitter.im/ruby-pagy/Lobby" rel="nofollow" target="_blank">&gt; Chat Support on Gitter &lt;</a></p>
</div>

</header>
Expand Down
35 changes: 19 additions & 16 deletions docs/api/backend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,13 @@ title: Pagy::Backend

# Pagy::Backend

The only scope of this module is encapsulating a couple of verbose statements in one single slick `pagy` method, that returns the pagy instance and the page of records from the collection. _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb))_
This module provides a _generic_ pagination method (`pagy`) that works out of the box with any ORM collection (e.g. `ActiveRecord`, `Sequel`, `Mongoid`, ... collections), plus two sub-methods that you may want to override in order to customize it for any type of collection (e.g. Array, elasticsearch results, etc.) _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb))_

Including this module in your controller allows you to have a predefined `pagy` method plus a couple of sub-methods (i.e. getter methods called only by the predefined method), which are handy if you need to override some specific aspect of the predefined `pagy` method.
If you use also the `pagy-extras` gem, this module will get extended by a few _specific_ pagination methods, very convenient to use with _specific_ types of collections like Array, elasticsearch results, etc.

You can also write your own `pagy` method in your controller without including this module: it's just a couple of lines. For example, the following may be enough for your app:
```ruby
def pagy(collection, vars={})
pagy = Pagy.new(count: collection.count, page: params[:page], _vars)
return pagy, collection.offset(pagy.offset).limit(pagy.items)
end
```
__Notice__: Currently, the only available backend extra is the [array extra](../pagy-extras/array.md), but stay tuned, because there will be more in the near future.

_(see the [pagy-extras](../pagy-extras.md) doc for more details)_

## Synopsys

Expand All @@ -31,7 +27,6 @@ end
def index
@pagy, @records = pagy(Product.some_scope, some_option: 'some option for this instance')
end

```

## Methods
Expand Down Expand Up @@ -63,6 +58,8 @@ end
```
Override it if you need to add or change some variable. For example you may want to add the `:item_path` or the `:item_name` to customize the `pagy_info` output, or get the `:page` from a different param, or even cache the `count`.

_IMPORTANT_: `:count` and `:page` are the only 2 required pagy core variables, so be careful not to remove them from the returned hash.

See also the [How To](../how-to.md) wiki page for some usage example.


Expand All @@ -72,9 +69,15 @@ Sub-method called by the `pagy` method, it returns the page items (i.e. the reco

Here is its source (it works with most ORMs like `ActiveRecord`, `Sequel`, `Mongoid`, ...):

```ruby
def pagy_get_items(collection, pagy)
collection.offset(pagy.offset).limit(pagy.items)
end
```
Override it if the extraction of the items from your collection works in a different way.
```ruby
def pagy_get_items(collection, pagy)
collection.offset(pagy.offset).limit(pagy.items)
end
```
Override it if the extraction of the items from your collection works in a different way. For example, if you need to paginate an array:

```ruby
def pagy_get_items(array, pagy)
array[pagy.offset, pagy.items]
end
```
1 change: 1 addition & 0 deletions docs/api/frontend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ title: Pagy::Frontend

This module provides a few methods to deal with the navigation aspect of the pagination. You will usually include it in some helper module, making its methods available (and overridable) in your views. _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb))_

If you use also the `pagy-extras` gem, this module will get extended by a few more `nav_*` helpers _(see the [pagy-extras](../pagy-extras.md) doc for more details)_

## Synopsys

Expand Down
14 changes: 7 additions & 7 deletions docs/api/pagy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,13 +65,13 @@ The `Pagy.new` method accepts a single hash of variables that will be merged wit

These are the core-variables (i.e. instance variables that define the pagination object itself) consumed by the `new` method. 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 was pre-offset(ted) | `0` |
| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also 





[Control the page links](../how-to.md#control-the-page-links))_ | `[1,4,4,1]` |
| 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 was pre-offset(ted) | `0` |
| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also 











[Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |

__Notice__: Pagy replaces the blank values of scalar core variables (so excluding `:size`) with their default values. 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.

Expand Down
12 changes: 10 additions & 2 deletions docs/assets/css/style.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,19 @@ header {

#toc {
margin: 2em 0;
white-space: nowrap;
p {
margin: .4em 0;
}
p.indent1 {
margin-left: 2rem;
}
p#gitter-badge {
margin-top: 1.6em;
p#gitter-support {
font-weight: bold;
margin-top: 2em;
a:hover {
font-weight: bold;
}
}
}

Expand Down
39 changes: 23 additions & 16 deletions docs/how-to.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,19 @@ or with a template:
<%== render 'pagy/nav', locals: {pagy: @pagy} %>
```

## Items per page

You can control the items per page with the `items` variable. (Default `20`)

You can set its default in an initializer (applied to all instances). For example:
```ruby
Pagy::VARS[:items] = 25
```
You can also pass it as an instance variable to the `Pagy.new` method or to the `pagy` controller method:
```ruby
@pagy, @records = pagy(Product.some_scope, items: 30)
```

## Paginate Any Collection

Pagy doesn't need to know anything about the kind of collection you paginate, it doesn't need to "teach" it how to paginate itself by adding code to it: pagy just needs to know its count.
Expand Down Expand Up @@ -76,6 +89,14 @@ Then of course, regardless the kind of collection, you can render the navigation
```
See the [Pagy::Backend source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb) and the [Pagy::Backend API documentation](api/backend.md) for more details.

## Paginate an Array

You have many ways to paginate an array with pagy:

- implementing the above _how-to_ (probably not very convenient besides being a good example)
- using `pagy` and overriding `pagy_get_items` _(see [pagy_get_items](api/backend.md#pagy_get_itemscollection-pagy)_
- using `pagy_array` offered by the `pagy-extra` gem _(see [array extra](pagy-extras/array.md))_

## Paginate a pre-offsetted and pre-limited collection

With the other pagination gems you cannot paginate a subset of a collection that you got using offset and limit. With Pagy it is as simple as just adding the `:outset` variable, set to the initial offset. For example:
Expand All @@ -87,34 +108,20 @@ subset = Product.offset(100).limit(315)

Assuming the `:items` default of `20`, you will get the pages with the right records you are expecting. The first page from record 101 to 120 of the main collection, and the last page from 401 to 415 of the main collection. Besides the `from` and `to` attribute readers will correctly return the numbers relative to the subset that you are paginating, i.e. from 1 to 20 for the first page and from 301 to 315 for the last page.


## Items per page

You can control the items per page with the `items` variable. (Default `20`)

You can set its default in an initializer (applied to all instances). For example:
```ruby
Pagy::VARS[:items] = 25
```
You can also pass it as an instance variable to the `Pagy.new` method or to the `pagy` controller method:
```ruby
@pagy, @records = pagy(Product.some_scope, items: 30)
```

## Passing the page number

You don't need to explicitly pass the usual `params[:page]` page number to the `pagy` method, because it is pulled in by the `pagy_get_vars` (which is called internally by the `pagy` method). However you can force a `page` number by just passing it to the `pagy` method. For example:

```ruby
pagy(my_scope, page: 3)
@pagy, @records = pagy(my_scope, page: 3)
```

That will explicitly set the `:page` variable, overriding the `params[:page]` default.

__Notice__: If you need to get the page number from another param or in some different way, just override the `pagy_get_vars` method right in your controller.


## Control the page links
## Controlling the page links

You can control the number and position of page links in the navigation through the `:size` variable. It is an array of 4 integers that specify which and how many page link to show.

Expand Down
4 changes: 3 additions & 1 deletion docs/migration-tips.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ title: Migration Tips

# Migration Tips

This page tries to cover most of the standard changes you will need to make in order to to migrate from a legacy pagination, however, if the legacy pagination is higly customized you may need more digging into the Pagy documentation. Feel free to ask on Gitter if you need more assistance:&nbsp;&nbsp;<a href="https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" rel="nofollow" target="_blank"><img src="https://camo.githubusercontent.com/1adf5e58915e2093fd2e856136ae26c99e2ae214/68747470733a2f2f6261646765732e6769747465722e696d2f727562792d706167792f4c6f6262792e737667" alt="Join the chat at https://gitter.im/ruby-pagy/Lobby" data-canonical-src="https://badges.gitter.im/ruby-pagy/Lobby.svg" style="max-width:100%;"></a>
This page tries to cover most of the standard changes you will need to make in order to to migrate from a legacy pagination, however, if the legacy pagination is higly customized you may need more digging into the Pagy documentation.

Feel free to <a href="https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" rel="nofollow" target="_blank">ask on Gitter</a> if you need more assistance.

## Phases

Expand Down
Loading

0 comments on commit 92260b5

Please sign in to comment.