From 8e7e88afad116fb6ffcad611c219c7f738a5476e Mon Sep 17 00:00:00 2001
From: Domizio Demichelis
Date: Sat, 29 Jun 2024 09:49:33 +0700
Subject: [PATCH] Improve how-to docs
---
docs/how-to.md | 49 +++++++++++++++++++++++++------------------------
1 file changed, 25 insertions(+), 24 deletions(-)
diff --git a/docs/how-to.md b/docs/how-to.md
index a4a08292b..a01e130da 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -47,7 +47,7 @@ You can control the number and position of the page links in the navigation thro
==- Fast nav
You can set the `:size` variable to an Integer representing the maximum page/gap slots rendered. The current
-page will be placed as centered as possible in the series. For that reason, `:size` works better when it's a odd number.
+page will be placed as centered as possible in the series. For that reason, `:size` works better when it's an odd number.
For example:
@@ -109,8 +109,8 @@ pagy.series
==- Customize the series
If changing the `:size` is not enough for your requirements (e.g. if you need to add intermediate segments or midpoints in place
-of gaps) you should override the `series` method. See more details and
-examples [here](https://github.com/ddnexus/pagy/issues/245).
+of gaps) you should override the `series` method. See more details and examples
+[here](https://github.com/ddnexus/pagy/issues/245).
===
@@ -177,8 +177,8 @@ You may want to customize that, for example to make it more readable in your lan
collections in the same action. Depending on the scope of the customization, you have a couple of options:
1. `Pagy::DEFAULT[:page_param] = :custom_param` will be used as the global default
-2. `pagy(scope, page_param: :custom_param)` or `Pagy.new(count:100, page_param: :custom_param)` will be used for a single
- instance (overriding the global default)
+2. `pagy(collection, page_param: :custom_param)` or `Pagy.new(count:100, page_param: :custom_param)` will be used for a
+ single instance (overriding the global default)
You can also override the [pagy_get_page](/docs/api/backend.md#pagy-get-page-vars) if you need some special way to get the page number.
@@ -214,7 +214,7 @@ An example using `except` and `merge!`:
@pagy, @records = pagy(collection, params: ->(params) { params.except('not_useful').merge!('custom' => 'useful') })
```
-You can also use the `:fragment` variable to add a fragment the URLs of the pages:
+You can also use the `:fragment` variable to add a fragment to the URLs of the pages:
```ruby controller
@pagy, @records = pagy(collection, fragment: '#your-fragment')
@@ -427,7 +427,7 @@ the [metadata extra](extras/metadata.md) and pass the pagination metadata in you
## Paginate search framework results
-Pagy has a few of extras for gems returning search results:
+Pagy has a few extras dedicated to gems returning search results:
- [elasticsearch_rails](extras/elasticsearch_rails.md)
- [searchkick](extras/searchkick.md)
@@ -449,7 +449,7 @@ By default pagy tries to derive parameters and variables from the request and th
it to the `pagy*` method. That is very handy, but assumes you are paginating a single collection per request.
When you need to paginate multiple collections in a single request, you need to explicitly differentiate the pagination
-objects. You have the following commong ways to do so:
+objects. You have the following common ways to do so:
==- Pass the request path
@@ -565,17 +565,19 @@ to different existing statements.
# pagy without calendar
@pagy, @record = pagy(collection, any_vars: value, ...)
# wrapped with pagy_calendar
-@calendar, @pagy, @records = pagy_calendar(collection, year: { ... },
- month: { ... },
- pagy: { any_vars: value, ... })
+@calendar, @pagy, @records = pagy_calendar(collection,
+ year: {},
+ month: {},
+ pagy: { any_vars: value, ... })
# any other backend constructors (e.g. pagy_searchkick)
@pagy, @record = pagy_searchkick(pagy_search_args, any_vars: value, ...)
# wrapped with pagy_calendar
-@calendar, @pagy, @records = pagy_calendar(pagy_search_args, year: { ... },
- month: { ... },
- pagy: { backend: :pagy_searchkick,
- 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.
@@ -587,12 +589,12 @@ In order to limit the pagination to a maximum number of pages, you can pass the
For example:
```ruby
-@pagy, @records = pagy(scope, max_pages: 50, items: 20)
+@pagy, @records = pagy(collection, max_pages: 50, items: 20)
@records.size #=> 20
@pagy.count #=> 10_000
@pagy.last #=> 50
-@pagy, @records = pagy(scope, max_pages: 50, items: 20, page: 51)
+@pagy, @records = pagy(collection, max_pages: 50, items: 20, page: 51)
#=> Pagy::OverflowError: expected :page in 1..50; got 51
```
@@ -642,7 +644,7 @@ metadata:
#,#,...]...>
```
-As you can see it contains the pagination metadata that you can use to setup the pagination with pagy:
+As you can see, it contains the pagination metadata that you can use to setup the pagination with pagy:
```ruby controller
# get the paginated collection
@@ -727,7 +729,7 @@ use a storage system like any SQL DB, there is no way to paginate and provide a
to get the collection count. That is usually not a problem if your DB is well organized and maintained, but that may not be always
the case.
-Sometimes you may have to deal with some not very efficient legacy apps/DBs that you cannot totally control. In that case the
+Sometimes you may have to deal with not very efficient legacy apps/DBs that you cannot totally control. In that case the
extra count query may affect the performance of the app quite badly.
You have 2 possible solutions in order to improve the performance.
@@ -762,7 +764,7 @@ DB writing, and probably not particularly useful with a DB in constant change.
==- Avoid the count
-When the count caching is not an option, you may want to use the [countless extra](extras/countless.md), which totally avoid the
+When the count caching is not an option, you may want to use the [countless extra](extras/countless.md), which totally avoids the
need for a count query, still providing an acceptable subset of the full pagination features.
===
@@ -815,8 +817,7 @@ Pass an overflowing `:page` number and Pagy will raise a `Pagy::OverflowError` e
This often happens because users/clients paginate over the end of the record set or records go deleted and a user went to a stale
page.
-You can handle the exception by using the [overflow extra](extras/overflow.md) which provides easy and ready to use solutions for
-a few common cases, or you can rescue the exception manually and do whatever fits better.
+You can handle the exception by using the [overflow extra](extras/overflow.md) which provides a few easy and ready to use solutions for a few common cases, or you can rescue the exception manually and do whatever fits you better.
Here are a few options for manually handling the error in apps:
@@ -836,8 +837,8 @@ end
```
!!!warning Rescue from `Pagy::OverflowError` first
-All Pagy exceptions are subclasses of `ArgumentError`, so if you need to `rescue_from ArgumentError, ...` along
-with `rescue_from Pagy::OverflowError, ...` then the `Pagy::OverflowError` line should go BEFORE the `ArgumentError` line or it
+All Pagy exceptions are subclasses of `ArgumentError`, so if you need to `rescue_from ArgumentError, ...` along with
+`rescue_from Pagy::OverflowError, ...` then the `Pagy::OverflowError` line should go BEFORE the `ArgumentError` line or it
will never get rescued.
!!!