Docs updates

jyuvaraj03 · Nov 23, 2021 · fed44c7 · fed44c7
1 parent 9e532e3
commit fed44c7
Show file tree

Hide file tree

Showing 6 changed files with 67 additions and 30 deletions.
diff --git a/docs/extras/calendar.md b/docs/extras/calendar.md
@@ -14,7 +14,7 @@ _Screenshot from the single-file self-contained [pagy_calendar_app.ru](https://g
 
 This extra makes sense when the result to paginate have some _time continuity_ and you want to provide a simple chronological browsing. For example: a movie catalog could allow the user to browse all the movies by year, or you may want to browse a long list of events by jumping and narrowing between years, months, days.
 
-On the other hand it does not make much sense for the result of a search that hits just a few sparse records scattered over a possibly long period of time. In that case the calendar extra has an `:active` switch that can inactivate the calendar and fallback to the regular pagination. No need to maintain different UIs for wide browsing and narrow searching. 
+On the other hand it does not make much sense for the result of a search that hits just a few sparse records scattered over a possibly long period of time. For that case the calendar extra has an `:active` switch that can be used to inactivate the calendar and fallback to the regular pagination. No need to maintain different UIs for wide browsing and narrow searching. 
 
 ## Synopsis
 
@@ -62,7 +62,9 @@ Use the calendar and pagy objects in your views:
 <%== pagy_nav(@pagy) %>
 ```
 
-**Notice** For a more complete and detailed example, see the [pagy_calendar_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_calendar_app.ru).
+See also a few examples for [wrapping existing pagination with pagy_calendar](../how-to.md#wrapping-existing-pagination-with-pagy_calendar).
+
+**Notice** For a complete and detailed example, see the [pagy_calendar_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_calendar_app.ru).
 
 ## Usage
 
@@ -134,7 +136,7 @@ If the `:pagy` key/value is omitted, a default `Pagy` instance will be created b
 
 The calendar is active by default, however you can add an optional `:active` boolean flag to the `conf` hash in order to switch it ON or OFF, depending on its usefulness in different conditions (see the [Use cases](#use-cases)).
 
-Take a look at the [pagy_calendar_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_calendar_app.ru) for a simple example of a manual toggle in the UI.
+Take a look at the [pagy_calendar_app.ru](https://github.com/ddnexus/pagy/blob/master/apps/pagy_calendar_app.ru) for a simple example of a manual toggle in the UI. 
 
 ### pagy_calendar_period(collection)
 

diff --git a/docs/extras/countless.md b/docs/extras/countless.md
@@ -51,7 +51,7 @@ If you enable the `:countless_minimal` variable, then:
 
 - The returned `pagy` object will contain just a handful of variables and will miss the finalization, so you cannot use it with any helpers
 - The returned paginated collection (`@records`) will be a regular scope (i.e. no record has been load yet) so an eventual fragment caching can work as expected
-- You will need to check the size of the paginated collection (`@records`) in order to know if it is the last page or not. You can tell if it by checking `@records.size < @pagy.vars[:items]`. Notice that IF the last page has exactly the `@pagy.vars[:items]` in it you will not be able to know it. In infinite scroll that would just try to load the next page returning 0 items, so it will be perfectly acceptable anyway.
+- You will need to check the size of the paginated collection (`@records`) in order to know if it is the last page or not. You can tell it by checking `@records.size < @pagy.vars[:items]`. Notice that IF the last page has exactly the `@pagy.vars[:items]` in it you will not be able to know it. In infinite scroll that would just try to load the next page returning 0 items, so it will be perfectly acceptable anyway.
 
 ## Variables
 

diff --git a/docs/extras/elasticsearch_rails.md b/docs/extras/elasticsearch_rails.md
@@ -45,18 +45,22 @@ response         = Article.pagy_search(params[:q])
 
 - [elasticsearch_rails.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/elasticsearch_rails.rb)
 
-## Pagy.new_from_elasticsearch_rails
+## Passive Mode
+
+### Pagy.new_from_elasticsearch_rails(response, ...)
 
 This constructor accepts an `Elasticsearch::Model::Response::Response` as the first argument, plus the usual optional variable hash. It sets the `:items`, `:page` and `:count` pagy variables extracted/calculated out of the `Elasticsearch::Model::Response::Response` object.
 
 ```ruby
-@response = Model.search('*', from: 0; size: 10, ...)
+@response = Model.search('*', from: 0, size: 10, ...)
 @pagy     = Pagy.new_from_elasticsearch_rails(@response, ...)
 ```
 
 **Notice**: you have to take care of manually manage all the params for your search, however the method extracts/calculates the `:items`, `:page` and `:count` from the response object, so you don't need to pass that again. If you prefer to manage the pagination automatically, see below.
 
-## Pagy::ElasticsearchRails
+## Active mode
+
+### Pagy::ElasticsearchRails module
 
 Extend your model with the `Pagy::ElasticsearchRails` micro-module:
 
@@ -66,25 +70,27 @@ extend Pagy::ElasticsearchRails
 
 The `Pagy::ElasticsearchRails` adds the `pagy_search` class method that you must use in place of the standard `search` method when you want to paginate the search response.
 
-### pagy_search(...)
+#### pagy_search(...)
 
 This method accepts the same arguments of the `search` method and you must use it in its place. This extra uses it in order to capture the arguments, automatically merging the calculated `:from` and `:size` options before passing them to the standard `search` method internally.
 
-## Variables
+### Variables
 
-| Variable                             | Description                                                                                | Default      |
-|:-------------------------------------|:-------------------------------------------------------------------------------------------|:-------------|
-| `:elasticsearch_rails_search_method` | customizable name of the `:pagy_search` method | :pagy_search |
+| Variable                             | Description                            | Default      |
+|:-------------------------------------|:---------------------------------------|:-------------|
+| `:elasticsearch_rails_search_method` | customizable name of the search method | :pagy_search |
 
-## Methods
+### Methods
 
 This extra adds the `pagy_elasticsearch_rails` method to the `Pagy::Backend` to be used when you have to paginate a `ElasticsearchRails` object. It also adds a `pagy_elasticsearch_rails_get_variables` sub-method, used for easy customization of variables by overriding.
 
-### pagy_elasticsearch_rails(Model.pagy_search(...), vars={}})
+#### pagy_elasticsearch_rails(pagy_search_args, vars = {}})
 
 This method is similar to the generic `pagy` method, but specialized for Elasticsearch Rails. (see the [pagy doc](../api/backend.md#pagycollection-varsnil))
 
-It expects to receive a `Model.pagy_search(...)` result and returns a paginated response. You can use it in a couple of ways:
+It expects to receive a `Model.pagy_search(...)` result as the first argument and an optional hash of variables. It returns a paginated response. 
+
+You can use it in a couple of ways:
 
 ```ruby
 @pagy, @response = pagy_elasticsearch_rails(Model.pagy_search(params[:q]), ...)

diff --git a/docs/extras/meilisearch.md b/docs/extras/meilisearch.md
@@ -45,7 +45,9 @@ results         = Article.pagy_search(params[:q])
 
 - [meilisearch.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/meilisearch.rb)
 
-## Pagy.new_from_meilisearch
+## Pasive mode
+
+### Pagy.new_from_meilisearch
 
 This constructor accepts a Meilisearch as the first argument, plus the usual optional variable hash. It sets the `:items`, `:page` and `:count` pagy variables extracted/calculated out of the Meilisearch object.
 
@@ -56,7 +58,9 @@ This constructor accepts a Meilisearch as the first argument, plus the usual opt
 
 **Notice**: you have to take care of manually manage all the params for your search, however the method extracts the `:items`, `:page` and `:count` from the results object, so you don't need to pass that again. If you prefer to manage the pagination automatically, see below.
 
-## Pagy::Meilisearch
+## Active Mode
+
+### Pagy::Meilisearch module
 
 Extend your model with the `Pagy::Meilisearch` micro-module:
 
@@ -70,11 +74,11 @@ The `Pagy::Meilisearch` adds the `pagy_search` class method that you must use in
 
 This method accepts the same arguments of the `search` method and you must use it in its place. This extra uses it in order to capture the arguments, automatically merging the calculated `:offset` and `:limit` options before passing them to the standard `search` method internally.
 
-## Variables
+### Variables
 
-| Variable                    |                                                | Description    | Default |
-|:----------------------------|:-----------------------------------------------|:---------------|:--------|
-| `:meilisearch_search_method` | customizable name of the `:pagy_search` method | `:pagy_search` |         |
+| Variable                     | Description                            | Default        |
+|:-----------------------------|:---------------------------------------|:---------------|
+| `:meilisearch_search_method` | customizable name of the search method | `:pagy_search` | 
 
 ## Methods
 

diff --git a/docs/extras/searchkick.md b/docs/extras/searchkick.md
@@ -62,7 +62,9 @@ results         = Searchkick.pagy_search(params[:q], models: [Article, Categorie
 
 - [searchkick.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/searchkick.rb)
 
-## Pagy.new_from_searchkick
+## Passive mode
+
+### Pagy.new_from_searchkick(results, vars = {})
 
 This constructor accepts a `Searchkick::Results` as the first argument, plus the usual optional variable hash. It sets the `:items`, `:page` and `:count` pagy variables extracted/calculated out of the `Searchkick::Results` object.
 
@@ -73,7 +75,9 @@ This constructor accepts a `Searchkick::Results` as the first argument, plus the
 
 **Notice**: you have to take care of manually manage all the params for your search, however the method extracts the `:items`, `:page` and `:count` from the results object, so you don't need to pass that again. If you prefer to manage the pagination automatically, see below.
 
-## Pagy::Searchkick
+## Active Mode
+
+## Pagy::Searchkick module
 
 Extend your model with the `Pagy::Searchkick` micro-module:
 
@@ -87,17 +91,17 @@ The `Pagy::Searchkick` adds the `pagy_search` class method that you must use in
 
 This method accepts the same arguments of the `search` method and you must use it in its place. This extra uses it in order to capture the arguments, automatically merging the calculated `:page` and `:per_page` options before passing them to the standard `search` method internally.
 
-## Variables
+### Variables
 
-| Variable                    |                                                | Description    | Default |
-|:----------------------------|:-----------------------------------------------|:---------------|:--------|
-| `:searchkick_search_method` | customizable name of the `:pagy_search` method | `:pagy_search` |         |
+| Variable                    | Description                            | Default        |
+|:----------------------------|:---------------------------------------|:---------------|
+| `:searchkick_search_method` | customizable name of the search method | `:pagy_search` |
 
-## Methods
+### Methods
 
 This extra adds the `pagy_searchkick` method to the `Pagy::Backend` to be used when you have to paginate a `Searchkick::Results` object. It also adds a `pagy_searchkick_get_vars` sub-method, used for easy customization of variables by overriding.
 
-### pagy_searchkick(Model.pagy_search(...), vars={}})
+#### pagy_searchkick(pagy_search_args, vars={}})
 
 This method is similar to the generic `pagy` method, but specialized for Searchkick. (see the [pagy doc](../api/backend.md#pagycollection-varsnil))
 
@@ -112,6 +116,6 @@ It expects to receive a `Model.pagy_search(...)` result and returns a paginated
 @pagy, @records = pagy_searchkick(Model.pagy_search(params[:q]).results, ...)
 ```
 
-### pagy_searchkick_get_vars(array)
+#### pagy_searchkick_get_vars(array)
 
 This sub-method is similar to the `pagy_get_vars` sub-method, but it is called only by the `pagy_searchkick` method. (see the [pagy_get_vars doc](../api/backend.md#pagy_get_varscollection-vars)).
diff --git a/docs/how-to.md b/docs/how-to.md
@@ -645,6 +645,27 @@ If your app uses ruby as pure backend and some javascript frameworks as the fron
 
 In that case you don't need the `Pagy::Frontend` nor any frontend extra. You should only require the [metadata extra](extras/metadata.md) and pass the pagination metadata in your JSON response.
 
+## Wrapping existing pagination with pagy_calendar
+
+You can easily wrap your existing pagination with the `pagy_calendar` method. Here are a few examples adding `:year` and `:month` to different existing statements.
+
+```ruby
+# given this statements:
+@pagy, @record = pagy(collection, any_vars: value, ...)
+@pagy, @record = pagy_searchkick(pagy_search_args, any_vars: value, ...)
+
+# wrap them with the calendar
+@calendar, @pagy, @records = pagy_calendar(collection, year: {...},
+                                                       month: {...},
+                                                       pagy: { any_vars: value, ... } )
+@calendar, @pagy, @records = pagy_calendar(pagy_search_args, year: {...},
+                                                             month: {...},
+                                                             pagy: { backend: :pagy_searchkick,
+                                                                     any_vars: value, ...} )
+```
+
+Then follow the [calendar extra documentation](extras/calendar.md) for more details.
+
 ## Maximizing Performance
 
 Here are some tips that will help choosing the best way to use Pagy, depending on your requirements and environment.