docs improvements

ddnexus · Mar 28, 2019 · 95cdf61 · 95cdf61
1 parent 310c804
commit 95cdf61
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -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)
@@ -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
 
@@ -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
 
@@ -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
@@ -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
 

diff --git a/docs/how-to.md b/docs/how-to.md
@@ -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
@@ -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`:

diff --git a/lib/config/pagy.rb b/lib/config/pagy.rb
@@ -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