diff --git a/docs/extras/calendar.md b/docs/extras/calendar.md index 4142ccb68..0c8a66a4a 100644 --- 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 index 7e8648805..59fb4a192 100644 --- 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 index 999aa445a..d085d138d 100644 --- 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 index 164953da1..55a9e50fb 100644 --- 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 index dc1fdeb11..1bc28a8a4 100644 --- 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 index 3a1116ed0..d9cf8cb2c 100644 --- 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.