updated docs

ddnexus · Mar 12, 2019 · 4e83993 · 4e83993
1 parent 8bd19d6
commit 4e83993
Show file tree

Hide file tree

Showing 18 changed files with 32 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ Pagy is the ultimate pagination gem that outperforms the others in each and ever
 ## Improvements in v2.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) compilant 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)

diff --git a/docs/api.md b/docs/api.md
@@ -8,7 +8,7 @@ title: API
 The whole core structure of Pagy is very simple: it is organized around 3 small modules of just ~100 lines of code in total:
 
 | Module           | Description                                                                                                     | Links                                                                                                        |
-| ---------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+|:-----------------|:----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------|
 | `Pagy`           | The small class that keeps track of the variables involved in the pagination                                    | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy.rb), [documentation](api/pagy.md)              |
 | `Pagy::Backend`  | The optional module that you can include in your controllers in order to automatically create the Pagy instance | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb), [documentation](api/backend.md)   |
 | `Pagy::Frontend` | The module to include in your views in order to get a few helpers for the HTML output                           | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb), [documentation](api/frontend.md) |

diff --git a/docs/api/pagy.md b/docs/api/pagy.md
@@ -73,7 +73,7 @@ The only mandatory instance variable to be passed is the `:count` of the collect
 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`    |
@@ -82,7 +82,7 @@ They are all integers:
 ### Other Variables
 
 | Variable      | Description                                                                                                                                                                                      | Default     |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------|
 | `: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]` |
 | `:page_param` | the name of the page param name used in the url. _(see [Customizing the page param](../how-to.md#customizing-the-page-param))_                                                                   | `:page`     |
 | `:params`     | the arbitrary param hash to add to the url. _(see [Customizing the params](../how-to.md#customizing-the-params))_                                                                                | `{}`        |
@@ -98,7 +98,7 @@ There is no specific validation for non-instance variables.
 Pagy exposes all the instance variables needed for the pagination through a few attribute readers. They all return integers (or `nil`), except the `vars` hash:
 
 | Reader   | Description                                                                                                        |
-| -------- | ------------------------------------------------------------------------------------------------------------------ |
+|:---------|:-------------------------------------------------------------------------------------------------------------------|
 | `count`  | the collection `:count`                                                                                            |
 | `page`   | the current page number                                                                                            |
 | `items`  | the _actual_ number of items in the current non-empty page (can be less than the requested `:items` variable)      |
@@ -132,7 +132,7 @@ That is self-contained, simple and efficient.
 The lowest possible limit of the pagination is reached when the collection has `0` count. In that case the Pagy object created has the following peculiar attributes:
 
 | Attribute | Value   |
-| --------- | ------- |
+|:----------|:--------|
 | `count`   | `0`     |
 | `page`    | `1`     |
 | `pages`   | `1`     |

diff --git a/docs/extras/array.md b/docs/extras/array.md
@@ -28,8 +28,6 @@ In a controller:
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb)
 
 ## Methods

diff --git a/docs/extras/bootstrap.md b/docs/extras/bootstrap.md
@@ -34,8 +34,6 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_bootstrap_respo
 
 ## Files
 
-This extra is composed of 4 files:
-
 - [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb)
 - [bootstrap_nav.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/bootstrap_nav.html.erb) (optional template)
 - [bootstrap_nav.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/bootstrap_nav.html.haml) (optional template)

diff --git a/docs/extras/bulma.md b/docs/extras/bulma.md
@@ -34,8 +34,6 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_bulma_responsiv
 
 ## Files
 
-This extra is composed of 4 files:
-
 - [bulma.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bulma.rb)
 - [bulma_nav.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/bulma_nav.html.erb) (optional template)
 - [bulma_nav.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/bulma_nav.html.haml) (optional template)

diff --git a/docs/extras/countless.md b/docs/extras/countless.md
@@ -27,8 +27,6 @@ In a controller:
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [countless.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/countless.rb)
 
 ## Methods

diff --git a/docs/extras/elasticsearch_rails.md b/docs/extras/elasticsearch_rails.md
@@ -43,8 +43,6 @@ records = Article.pagy_search(params[:q]).records
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [elasticsearch_rails.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/elasticsearch_rails.rb)
 
 ## Pagy.new_from_elasticsearch_rails

diff --git a/docs/extras/foundation.md b/docs/extras/foundation.md
@@ -32,8 +32,6 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_foundation_resp
 
 ## Files
 
-This extra is composed of 4 files:
-
 - [foundation.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/foundation.rb)
 - [foundation_nav.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/foundation_nav.html.erb) (optional template)
 - [foundation_nav.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/foundation_nav.html.haml) (optional template)

diff --git a/docs/extras/headers.md b/docs/extras/headers.md
@@ -79,20 +79,11 @@ Total-Count 1000
 
 #### Customize the header names
 
-If you are replacing any of the existing API-pagination gems in some already working app, you may want to customize the header names so you will not have to change the client app that consumes them. You can do so by using the `:headers` variable, set as usual at the global level or instance level.
-
-For example, the following will change the header names and will suppres the `:pages` ('Total-Pages') header:
-
-```ruby
-# globally
-Pagy::VARS[:headers] = {items: 'Per-Page', pages: false, count: 'Total'}
-# or for single instance
-pagy, records = pagy(collection, items: 'Per-Page', pages: false, count: 'Total'}
-```
+If you are replacing any of the existing API-pagination gems in some already working app, you may want to customize the header names so you will not have to change the client app that consumes them. You can do so by using the `:headers` variable _(see [variables](#variables) below)_
 
 #### Countless Pagination
 
-If your requirements allow to save one count-query per rendering by using the `pagy_countless` constructor, the headers will miss only the `rel="last"` link and the `Total-Count` (unknown with countless pagination).
+If your requirements allow to save one count-query per rendering by using the `pagy_countless` constructor, the headers will not have the `rel="last"` link, the `Total-Count` and the `Total-Pages` that are unknown with countless pagination.
 
 Example of HTTP headers produced from a `Pagy::Countless` object:
 
@@ -101,9 +92,27 @@ Link <https://example.com:8080/foo?page=1>; rel="first", <https://example.com:80
 Page-Items 20 
 ```
 
+## Variables
+
+| Variable   | Description                                              | Default                                                               |
+|:-----------|:---------------------------------------------------------|:----------------------------------------------------------------------|
+| `:headers` | Hash variable to customize/suppress the optional headers | `{ items: 'Page-Items', count: 'Total-Count', pages: 'Total-Pages' }` |
+
+As usual, depending on the scope of the customization, you can set the variables globally or for a single pagy instance.
+
+For example, the following will change the header names and will suppres the `:pages` ('Total-Pages') header:
+
+```ruby
+# globally
+Pagy::VARS[:headers] = {items: 'Per-Page', pages: false, count: 'Total'}
+
+# or for single instance
+pagy, records = pagy(collection, headers: {items: 'Per-Page', pages: false, count: 'Total'})
+```
+
 ## Methods
 
-This extra adds a few methods available in your controllers.
+This extra adds a few methods to the `Pagy::Backend` (available in your controllers).
 
 ### pagy_headers_merge(pagy)
 

diff --git a/docs/extras/i18n.md b/docs/extras/i18n.md
@@ -23,6 +23,4 @@ require 'pagy/extras/i18n'
 
 ## Files
 
-This extra is composed of 1 small file:
-
 - [i18n.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/i18n.rb)
diff --git a/docs/extras/materialize.md b/docs/extras/materialize.md
@@ -28,8 +28,6 @@ Configure [javascript](../extras.md#javascript) if you use `pagy_materialize_res
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [materialize.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/materialize.rb)
 
 ## Methods

diff --git a/docs/extras/overflow.md b/docs/extras/overflow.md
@@ -28,12 +28,12 @@ Pagy::VARS[:overflow] = :exception
 
 ## Files
 
-This extra is composed of the [overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb) file.
+-[overflow.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/overflow.rb)
 
 ## Variables
 
-| Variable    | Description                                              | Default      |
-| ------------| -------------------------------------------------------- | ------------ |
+| Variable    | Description                                              | Default       |
+|:------------|:---------------------------------------------------------|:--------------|
 | `:overflow` | one of `:last_page`, `:empty_page` or `:exception` modes | `:empty_page` |
 
 As usual, depending on the scope of the customization, you have a couple of options to set the variables:

diff --git a/docs/extras/plain.md b/docs/extras/plain.md
@@ -21,7 +21,7 @@ Configure [javascript](../extras.md#javascript).
 
 ## Files
 
-This extra is composed of the [plain.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/plain.rb) file and uses the shared [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/pagy.js) file.
+- [plain.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/plain.rb)
 
 # Compact navs
 

diff --git a/docs/extras/searchkick.md b/docs/extras/searchkick.md
@@ -43,8 +43,6 @@ records = Article.pagy_search(params[:q]).results
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [searchkick.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/searchkick.rb)
 
 ## Pagy.new_from_searchkick

diff --git a/docs/extras/semantic.md b/docs/extras/semantic.md
@@ -26,8 +26,6 @@ with a fast helper:
 
 ## Files
 
-This extra is composed of 1 file:
-
 - [semantic.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/semantic.rb)
 
 ## Methods

diff --git a/docs/extras/trim.md b/docs/extras/trim.md
@@ -19,8 +19,6 @@ require 'pagy/extras/trim'
 
 ## Files
 
-This extra is composed of 1 small file:
-
 - [trim.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/trim.rb)
 
 ## Methods

diff --git a/docs/how-to.md b/docs/how-to.md
@@ -313,7 +313,7 @@ These helpers take the Pagy object and return the HTML string with the paginatio
 **Notice**: the [extras](extras.md) add a few other helpers that you can use the same way, in order to get added features (e.g. bootstrap compatibility, responsiveness, compact layouts, etc.)
 
 | Extra                                | Helpers                                                                                   |
-| ------------------------------------ | ----------------------------------------------------------------------------------------- |
+|:-------------------------------------|:------------------------------------------------------------------------------------------|
 | [bootstrap](extras/bootstrap.md)     | `pagy_bootstrap_nav`, `pagy_bootstrap_compact_nav`, `pagy_bootstrap_responsive_nav`       |
 | [bulma](extras/bulma.md)             | `pagy_bulma_nav`, `pagy_bulma_compact_nav`, `pagy_bulma_responsive_nav`                   |
 | [foundation](extras/foundation.md)   | `pagy_foundation_nav`, `pagy_foundation_compact_nav`, `pagy_foundation_responsive_nav`    |