WIP Docs

ddnexus · Feb 12, 2025 · 3dec25b · 3dec25b
1 parent bbb0258
commit 3dec25b
Show file tree

Hide file tree

Showing 37 changed files with 1,183 additions and 722 deletions.
diff --git a/README.md b/README.md
@@ -64,14 +64,14 @@ Pagination with JSON:API:
 @pagy, @records = pagy_offset(Product.all, jsonapi: true)
 @pagy, @records = pagy_keyset(Product.all, jsonapi: true)
 render json: { data:  @records,
-               links: pagy_links(@pagy) }
+               links: pagy_links_hash(@pagy) }
 ```
 
 JSON-client pagination:
 
 ```ruby
 render json: { data: @records,
-               @pagy: pagy_data(@pagy) }
+               pagy: pagy_extract_hash(@pagy) }
 ```
 
 Search code:
@@ -81,10 +81,10 @@ Search code:
 extend Pagy::Search
 
 # Paginate with pagy:
-arguments        = Product.pagy_search(params[:q])
-@pagy, @response = pagy_elasticsearch_rails(arguments)
-@pagy, @results  = pagy_meilisearch(arguments)
-@pagy, @results  = pagy_searchkick(arguments)
+search = Product.pagy_search(params[:q])
+@pagy, @response = pagy_elasticsearch_rails(search)
+@pagy, @results  = pagy_meilisearch(search)
+@pagy, @results  = pagy_searchkick(search)
 
 # Or get pagy from paginated results:
 @results = Product.search(params[:q])
@@ -130,16 +130,7 @@ View helpers:
 | [`pagy_limit_selector_js`](https://ddnexus.github.io/pagy/docs/api/javascript/)                                                                                                                                                      | ![`pagy_limit_selector_js`](/docs/assets/images/limit_selector_js.png) |
 | [`pagy_nav(@calendar[:year])`](https://ddnexus.github.io/pagy/docs/extras/calendar/)<br/>[`pagy_nav(@calendar[:month])`](https://ddnexus.github.io/pagy/docs/extras/calendar/)<br/> (other units: `:quarter`, `:week`, `:day` and custom) | ![calendar extra](/docs/assets/images/calendar-app.png)                |
 
-_(See the [Quick Start](https://ddnexus.github.io/pagy/quick-start))_
-
-
-<br> 
-
-See also the [How To](https://ddnexus.github.io/pagy/docs/how-to)
-
-## 🤓 It's well documented and supported
-
-### Documentation
+## Documentation
 
 - [Migrate from WillPaginate and Kaminari](https://ddnexus.github.io/pagy/docs/migration-guide) (practical guide)
 - [Quick Start](https://ddnexus.github.io/pagy/quick-start)
@@ -153,44 +144,6 @@ See also the [How To](https://ddnexus.github.io/pagy/docs/how-to)
 - [Discussions](https://github.com/ddnexus/pagy/discussions/categories/q-a)
 - [Issues](https://github.com/ddnexus/pagy/issues)
 
-### Recent Posts and Tutorials
-
-- [Build Load More Pagination with Pagy and Rails Hotwire](https://maful.web.id/posts/build-load-more-pagination-with-pagy-and-rails-hotwire/ '2023-09-17')
-  by Maful. (This tutorial shows how you can turbo_stream with GET requests)
-- [Pagination and infinite scrolling with Rails and the Hotwire stack](https://www.colby.so/posts/infinite-scroll-with-turbo-streams-and-stimulus '2022-04-19')
-  by David Colby
-- [Pagination with Hotwire](https://www.beflagrant.com/blog/pagination-with-hotwire '2021-09-23') by Jonathan Greenberg
-- [Pagination for Beginners: What is it? Why bother?](https://benkoshy.github.io/2021/11/03/pagination-basics.html '2021-11-03')
-  by Ben Koshy
-- [Endless Scroll / Infinite Loading with Turbo Streams & Stimulus](https://www.stefanwienert.de/blog/2021/04/17/endless-scroll-with-turbo-streams/ '2021-04-17')
-  by Stefan Wienert
-- [How to make your pagination links sticky + bounce at the bottom of your page](https://benkoshy.github.io/2020/09/15/sticky-menu.html '2020-09-15')
-  by Ben Koshy
-- [How to Override pagy methods only in specific circumstances](https://benkoshy.github.io/2020/02/01/overriding-pagy-methods.html  '2020-02-01')
-  by Ben Koshy
-- [Handling Pagination When POSTing Complex Search Forms](https://benkoshy.github.io/2019/10/09/paginating-search-results-with-a-post-request.html '2019-10-09')
-  by Ben Koshy
-- [Pagination with Pagy](https://www.imaginarycloud.com/blog/paginating-ruby-on-rails-apps-with-pagy '2018-04-19') by Tiago Franco
-- [日本語の投稿](https://qiita.com/search?q=pagy)
-
-### Recent Screencasts
-
-[<img src="https://img.youtube.com/vi/bVvLNpJyZuw/0.jpg" width="150" title="9:29 min - Intermediate - Infinite Scrolling with Pagy Keyset, Turbo (Rails 8) (2024-10-19)">](https://www.youtube.com/watch?v=bVvLNpJyZuw)
-[<img src="https://img.youtube.com/vi/EDyZIB8FU-g/0.jpg" title="12:52 min - Intermediate Skill Level - Calendar sarch with Pagy (2024-01-21)" width="150">](https://www.youtube.com/watch?v=EDyZIB8FU-g)
-[<img src="https://img.youtube.com/vi/zni3nMA5_AY/0.jpg" width="150" title="10:53 - Urdu Language (2024-01-15)">](https://www.youtube.com/watch?v=zni3nMA5_AY)
-[<img src="https://img.youtube.com/vi/4nrmf5KfD8Y/0.jpg" width="150" title="14:28 min - Intermediate - Infinite Scrolling with Turbo Streams (Rails 7) (2023-06-09)">](https://www.youtube.com/watch?v=4nrmf5KfD8Y)
-[<img src="https://img.youtube.com/vi/Qoq6HZ8gdDE/0.jpg" title="12:52 min - Intermediate Skill Level - API based pagination + using pagy_data (2023-05-18)" width="150">](https://www.youtube.com/watch?v=Qoq6HZ8gdDE)
-[<img src="https://img.youtube.com/vi/1sNpvTMrxl4/0.jpg" width="150" title="31 min - Beginner - Basic Pagy Use (Tailwind, Overflow, Common Use cases) + Deep dive into building a sample Blogging Application (2023-04-05)">](https://www.youtube.com/watch?v=1sNpvTMrxl4)
-[<img src="https://img.youtube.com/vi/A9q6YwhLCyI/0.jpg" title="17 min - Intermediate Skill Level - Pagination with Search (Ransack) and Hotwire + Infinite (Countless) Pagination (2022-12-09)" width="150">](https://www.youtube.com/watch?v=A9q6YwhLCyI)
-[<img src="https://img.youtube.com/vi/HURqvNJF4T0/0.jpg" width="150" title="5:21 min - Intermediate - Using Pagy - with a strong focus on Hotwire and filtering search results (2022-04-20)">](https://www.youtube.com/watch?v=HURqvNJF4T0)
-[<img src="https://img.youtube.com/vi/ScxUqW29F7E/0.jpg" width="150" title="18 min - Intermediate Skill Level - 'Load More' pagination using Turbo Streams (2022-03-22)">](https://www.youtube.com/watch?v=ScxUqW29F7E)
-[<img src="https://img.youtube.com/vi/0RtYhDIKmBY/0.jpg" width="150" title="5:44 min - Beginner - How to Install Pagy + Using Tailwind CSS to create a page of 'listing' (2022-03-18)">](https://www.youtube.com/watch?v=0RtYhDIKmBY)
-[<img src="https://img.youtube.com/vi/ArBUAxEA6vM/0.jpg" width="150" title="30:00 min - Advanced - Using Pagy In the Context of a Chat Room (Infinite Scroll, Hotwire, Stimulus JS + Using Pagy APIs) (2022-03-04)">](https://www.youtube.com/watch?v=ArBUAxEA6vM)
-[<img src="https://img.youtube.com/vi/1tsWL4EjhMo/0.jpg" width="150" title="15 min - Beginner friendly - Shows installation and use of some pagy extras (2021-05-05)">](https://www.youtube.com/watch?v=1tsWL4EjhMo)
-[<img src="https://img.youtube.com/vi/aILtxj_LVuA/0.jpg" width="150" title="7:23 min - Beginner - Installing Pagy + Working through errors (step-by-step) (2021-03-12)">](https://www.youtube.com/watch?v=aILtxj_LVuA)
-[<img src="https://img.youtube.com/vi/_j3gtKf5rRs/0.jpg" width="150" title="10:45 - Spanish Language (2020-09-11)">](https://www.youtube.com/watch?v=_j3gtKf5rRs)
-
-<br>
 
 ## Top 💯 Contributors
 

diff --git a/docs/api/backend.md b/docs/api/backend.md
diff --git a/docs/api/backend_methods.md b/docs/api/backend_methods.md
@@ -0,0 +1,20 @@
+---
+title: Backend Methods
+order: 100
+---
+
+Include this module in your controller to have the methods to paginate your collections:
+
+```ruby ApplicationController
+include Pagy::Backend
+```
+
+!!!success Pagy loads ONLY the methods that you actually use
+
+The rest of the pagy code will never use any memory
+!!!
+
+!!!warning Don't instantiate any Pagy class directly
+
+Use the paginator methods that know which implementer class to use, and how to initialize it.
+!!!
diff --git a/docs/api/backend_methods/helpers/extract_hash.md b/docs/api/backend_methods/helpers/extract_hash.md
@@ -0,0 +1,60 @@
+---
+title: pagy_extract_hash
+order: 100
+---
+
+`pagy_extract_hash` extracts a hash of the key/values that you pluck from the pagy object. It is useful to export the pagination
+data to Javascript frameworks like Vue.js, react.js, etc.
+
+```ruby Controller (action)
+@pagy, @records = pagy_offset(collection, **options)
+pagy_hash       = pagy_extract_hash(@pagy, pluck_keys: %i[page previous next previous_url next_url ...])
+#=> { page: 3, previous: 2, next: 4, previous_url: ... } 
+render json: { data: @records, pagy: pagy_hash }
+```
+
+==- Options
+
+- `pluck_keys`
+
+  - For efficiency reasons you should always set the `:pluck_keys` option t restrict the output to ONLY the keys that you use.
+    Notice that you can also add other pagy method names not included in the default below:
+
+    - count
+    - first_url
+    - from
+    - in
+    - last
+    - last_url
+    - limit
+    - next
+    - next_url
+    - options
+    - page
+    - page_url
+    - pages
+    - previous
+    - previous_url
+    - sequels
+    - series
+    - to
+    - url_template
+
+==- Usage of `:url_template`
+
+This is a URL string containing the `"P "` page token in place of the page value. 
+
+For example: `'/foo?page=P &bar=baz'`).
+
+You can replace with Javascript to create th actual page URLs:
+
+```js
+pageUrl = url_template.replace("P ", pageValue)
+```
+
+!!!warning You may not need it for simple cases!
+
+Consider to use the few `:*_url` pluck_keys directly, instead of using the `:url_template`.
+!!!
+
+===
diff --git a/docs/api/backend_methods/helpers/links_hash.md b/docs/api/backend_methods/helpers/links_hash.md
@@ -0,0 +1,20 @@
+---
+title: pagy_links_hash
+---
+
+`pagy_links_hash` returns the `:first`, `:previous`, `:next`, `:last` non`nil` URLs hash.
+
+It respects `jsonapi: true` if passed with `@pagy`.
+
+```ruby Controller
+link_hash = pagy_links_hash(@pagy, **options)
+```
+
+=== Options
+
+- `absolute: true` 
+  - URL absolute
+- `fragment: '#...'`
+  - URL fragment string
+
+===