docs and comments refactoring, also updated for pagy-extras v0.2.0

ddnexus · May 27, 2018 · 92260b5 · 92260b5
1 parent 46f235e
commit 92260b5
Show file tree

Hide file tree

Showing 13 changed files with 150 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -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
 

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -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>

diff --git a/docs/api/backend.md b/docs/api/backend.md
@@ -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
 
@@ -31,7 +27,6 @@ end
 def index
   @pagy, @records = pagy(Product.some_scope, some_option: 'some option for this instance')
 end
-
 ```
 
 ## Methods
@@ -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.
 
 
@@ -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
+```
diff --git a/docs/api/frontend.md b/docs/api/frontend.md
@@ -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
 

diff --git a/docs/api/pagy.md b/docs/api/pagy.md
@@ -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.
 

diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
@@ -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;
+    }
   }
 }
 

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

diff --git a/docs/migration-tips.md b/docs/migration-tips.md
@@ -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
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