Skip to content

Commit

Permalink
docs improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
ddnexus committed Mar 28, 2019
1 parent 310c804 commit 95cdf61
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 38 deletions.
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Pagy

[![Gem Version](https://img.shields.io/gem/v/pagy.svg?label=pagy&colorA=99004d&colorB=cc0066)](https://rubygems.org/gems/pagy)
![ruby](https://img.shields.io/badge/ruby-v1.9+-ruby.svg?colorA=99004d&colorB=cc0066)
![jruby](https://img.shields.io/badge/jruby-v1.7+-jruby.svg?colorA=99004d&colorB=cc0066)
![ruby](https://img.shields.io/badge/ruby-1.9+-ruby.svg?colorA=99004d&colorB=cc0066)
![jruby](https://img.shields.io/badge/jruby-1.7+-jruby.svg?colorA=99004d&colorB=cc0066)
[![Build Status](https://img.shields.io/travis/ddnexus/pagy/master.svg?colorA=1f7a1f&colorB=2aa22a)](https://travis-ci.org/ddnexus/pagy/branches)
[![MIT license](https://img.shields.io/badge/license-MIT-mit.svg?colorA=1f7a1f&colorB=2aa22a)](http://opensource.org/licenses/MIT)
![Commits](https://img.shields.io/github/commit-activity/y/ddnexus/pagy.svg?label=commits&colorA=004d99&colorB=0073e6)
Expand All @@ -11,13 +11,13 @@

Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.

## Improvements in v2.0+
## Improvements in 2.0+

- Lower ruby requirements (ruby v1.9+ || jruby v1.7+) make Pagy very convenient also on older systems
- Added [RFC-8288](https://tools.ietf.org/html/rfc8288) compliant http response `headers` extra
- Lower ruby requirements (ruby 1.9+ || jruby 1.7+) make Pagy very convenient also on older systems
- Added RFC-8288 compliant http response `headers` extra
- The i18n internal implementation now includes full dynamic support for multi-language apps, it's ~18x faster and uses ~10x less memory than the i18n gem
- The `searchkick` and `elasticsearch_rails` extras have been refactored with more and better options
- Pagy v2.0+ is even faster and lighter than v1.0+ (see charts below)
- Pagy 2.0+ is even faster and lighter than 1.0+ (see charts below)

## Comparison with other gems

Expand Down Expand Up @@ -69,7 +69,7 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
- It works with fast helpers OR easy to edit templates _(see [more...](https://ddnexus.github.io/pagy/how-to#using-templates))_
- It raises real `Pagy::OverflowError` exceptions that you can rescue from _(see [how...](https://ddnexus.github.io/pagy/how-to#handling-pagyoutofrangeerror-exception))_ or use the [overflow extra](http://ddnexus.github.io/pagy/extras/overflow) for a few ready to use common behaviors
- It does not impose any difficult-to-override logic or output _(see [why...](https://ddnexus.github.io/pagy/index#really-easy-to-customize))_
- It also works on legacy systems starting from ruby v1.9+ and jruby v1.7+
- It also works on legacy systems starting from ruby 1.9+ and jruby 1.7+

### Easy to use

Expand Down Expand Up @@ -117,7 +117,7 @@ Use the official extras, or write your own in just a few lines. Extras add speci

### Feature Extras

- [headers](http://ddnexus.github.io/pagy/extras/headers): Add [RFC-8288](https://tools.ietf.org/html/rfc8288) compliant http response headers (and other helpers) useful for API pagination
- [headers](http://ddnexus.github.io/pagy/extras/headers): Add RFC-8288 compliant http response headers (and other helpers) useful for API pagination
- [i18n](http://ddnexus.github.io/pagy/extras/i18n): Use the `I18n` gem instead of the pagy-i18n implementation
- [items](http://ddnexus.github.io/pagy/extras/items): Allow the client to request a custom number of items per page with an optional selector UI
- [overflow](http://ddnexus.github.io/pagy/extras/overflow): Allow for easy handling of overflowing pages
Expand Down Expand Up @@ -149,6 +149,7 @@ Besides the classic pagination `nav`, Pagy offers a few ready to use alternative
- [Integrating Pagy with Hanami](http://katafrakt.me/2018/06/01/integrating-pagy-with-hanami/) by Paweł Świątkowski
- [Detailed Gems Comparison](https://ddnexus.github.io/pagination-comparison/gems.html) (charts and analysis)
- [Benchmarks and Memory Profiles Source](http://github.com/ddnexus/pagination-comparison) (Rails app repository)
- [日本語の投稿](https://qiita.com/search?q=pagy)

### Docs

Expand Down
71 changes: 42 additions & 29 deletions docs/how-to.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,14 +226,55 @@ end

That would produce links that look like e.g. `<a href="2">2</a>`. Then you can attach a javascript "click" event on the page links. When triggered, the `href` content (i.e. the page number) should get copied to a hidden `"page"` input and the form should be posted.

## Paginate an Array

Please, use the [array](extras/array.md) extra.

## Paginate ActiveRecord collections

Pagy works out of the box with `ActiveRecord` collections.

## Paginate Ransack results

Ransack `result` returns an `ActiveRecord` collection, which can be paginated out of the box. For example:

```ruby
@q = Person.ransack(params[:q])
@pagy, @people = pagy(@q.result)
```

## Paginate Elasticsearch results

Pagy has a couple of extras for gems returning elasticsearch results: [elasticsearch_rails](extras/elasticsearch_rails.md) and [searchkick](extras/searchkick.md)

## Paginate pre-offsetted and pre-limited collections

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:

```ruby
subset = Product.offset(100).limit(315)
@pagy, @paginated_subset = pagy(subset, outset: 100)
```

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.

## Paginate non-ActiveRecord collections

The `pagy_get_vars` method works out of the box with `ActiveRecord` collections; for other collections (e.g. `mongoid`, etc.) you may need to override it in your controller, usually by simply removing the `:all` argument passed to `count`:

```ruby
#count = collection.count(:all)
count = collection.count
```

## Paginate Any Collection

Pagy doesn't need to know anything about the kind of collection you paginate. It can paginate any collection, because every collection knows its count and has a way to extract a chunk of items given an `offset` and a `limit`. It does not matter if it is an `Array` or an `ActiveRecord` scope or something else: the simple mechanism is the same:

1. Create a Pagy object using the count of the collection to paginate
2. Get the page of items from the collection using `pagy.offset` and `pagy.items`

An example with an array:
Here is an example with an array. (Please, notice that this is only a convenient example but you should use the [array](extras/array.md) extra to paginate arrays).

```ruby
# paginate an array
Expand Down Expand Up @@ -262,34 +303,6 @@ 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:

1. Implementing the above _how-to_ (probably not the most convenient way, besides being a good example)
2. Using the `pagy` method and overriding `pagy_get_items` _(see [pagy_get_items](api/backend.md#pagy_get_itemscollection-pagy)_
3. Using `pagy_array` offered by the `array` extra _(see [array extra](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:

```ruby
subset = Product.offset(100).limit(315)
@pagy, @paginated_subset = pagy(subset, outset: 100)
```

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.

## Paginate non-ActiveRecord collections

The `pagy_get_vars` method works out of the box with `ActiveRecord` collections; for other collections (e.g. `mongoid`, etc.) you may need to override it in your controller, usually by simply removing the `:all` argument passed to `count`:

```ruby
#count = collection.count(:all)
count = collection.count
```

## Custom count for custom scopes

Your scope might become complex and the default pagy `collection.count(:all)` may not get the actual count. In that case you can get the right count with some custom statement, and pass it to `pagy`:
Expand Down
2 changes: 1 addition & 1 deletion lib/config/pagy.rb
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# encoding: utf-8
# frozen_string_literal: true

# Pagy initializer file (v2.1.4)
# Pagy initializer file (2.1.4)
# Customize only what you really need and notice that Pagy works also without any of the following lines.
# Should you just cherry pick part of this file, please maintain the require-order of the extras

Expand Down

0 comments on commit 95cdf61

Please sign in to comment.