Merge pull request #1930 from wheels-dev/peter/pagination-helpers-1915

Add composable pagination view helpers

Author: bpamiri

.ai/wheels/views/helpers/pagination.md

@@ -0,0 +1,53 @@
+# Pagination View Helpers
+
+Composable helpers for building custom pagination UIs. All read from pagination metadata set by `findAll(page=...)` or `setPagination()`.
+
+## Helpers
+
+### paginationInfo(handle, format, encode)
+Text summary. Default format: `"Showing [startRow]-[endRow] of [totalRecords] records"`.
+Tokens: `[startRow]`, `[endRow]`, `[totalRecords]`, `[currentPage]`, `[totalPages]`.
+Returns `"No records found"` when totalRecords is 0.
+
+### previousPageLink(text, handle, name, class, disabledClass, showDisabled, pageNumberAsParam, encode)
+Link to previous page. Renders `<span class="disabled">` on first page (or empty string if `showDisabled=false`).
+
+### nextPageLink(text, handle, name, class, disabledClass, showDisabled, pageNumberAsParam, encode)
+Link to next page. Renders disabled span on last page.
+
+### firstPageLink(text, handle, name, class, disabledClass, showDisabled, pageNumberAsParam, encode)
+Link to first page. Disabled when already on page 1.
+
+### lastPageLink(text, handle, name, class, disabledClass, showDisabled, pageNumberAsParam, encode)
+Link to last page. Disabled when already on last page.
+
+### pageNumberLinks(windowSize, handle, name, class, classForCurrent, linkToCurrentPage, prependToPage, appendToPage, pageNumberAsParam, encode)
+Windowed page numbers. Current page renders as `<span class="current">` unless `linkToCurrentPage=true`.
+
+### paginationNav(handle, navClass, showFirst, showLast, showPrevious, showNext, showInfo, showSinglePage, encode)
+Complete `<nav class="pagination">` composing all above helpers. Returns empty string for single page unless `showSinglePage=true`.
+
+## Defaults (config/settings.cfm)
+```cfm
+set(functionName="previousPageLink", text="&laquo; Prev");
+set(functionName="nextPageLink", text="Next &raquo;");
+set(functionName="paginationInfo", format="Page [currentPage] of [totalPages]");
+set(functionName="pageNumberLinks", windowSize=5);
+```
+
+## Multiple Handles
+```cfm
+// Controller
+users = model("User").findAll(page=params.userPage, perPage=10, handle="users", order="name");
+// View
+#paginationNav(handle="users")#
+```
+
+## Relationship to paginationLinks()
+These helpers complement (not replace) the existing `paginationLinks()` monolithic helper. Use `paginationLinks()` for quick defaults; use these composable helpers when you need custom layouts.
+
+## Implementation
+- File: `vendor/wheels/view/pagination.cfc`
+- Defaults: `vendor/wheels/events/init/functions.cfm`
+- Tests: `tests/specs/view/PaginationHelpersSpec.cfc`
+- All helpers use `$args()` for defaults, `pagination()` for metadata, and `linkTo()` for link generation.

CHANGELOG.md

@@ -21,6 +21,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 ## [Unreleased]
 
 ### Added
+- Composable pagination view helpers: `paginationInfo()`, `previousPageLink()`, `nextPageLink()`, `firstPageLink()`, `lastPageLink()`, `pageNumberLinks()`, and `paginationNav()` for building custom pagination UIs
 - Route model binding with `binding=true` on resource routes or `set(routeModelBinding=true)` globally to auto-resolve model instances from route key parameters
 - Chainable query builder with `where()`, `orWhere()`, `whereNull()`, `whereBetween()`, `whereIn()`, `orderBy()`, `limit()`, and more for injection-safe fluent queries
 - Enum support with `enum()` for named property values, auto-generated `is*()` checkers, auto-scopes, and inclusion validation

docs/src/SUMMARY.md

@@ -157,6 +157,7 @@
 * [Layouts](displaying-views-to-users/layouts.md)
 * [Form Helpers and Showing Errors](displaying-views-to-users/form-helpers-and-showing-errors.md)
 * [Displaying Links for Pagination](displaying-views-to-users/displaying-links-for-pagination.md)
+* [Pagination Helpers](displaying-views-to-users/pagination-helpers.md)
 * [Date, Media, and Text Helpers](displaying-views-to-users/date-media-and-text-helpers.md)
 * [Creating Custom View Helpers](displaying-views-to-users/creating-custom-view-helpers.md)
 * [Localization](displaying-views-to-users/localization.md)

docs/src/displaying-views-to-users/pagination-helpers.md

@@ -0,0 +1,182 @@
+# Pagination Helpers
+
+Wheels provides composable pagination helpers that give you fine-grained control over pagination UI. Unlike `paginationLinks()` which generates a complete pagination block, these helpers let you build custom layouts by combining individual components.
+
+All helpers read from the same pagination metadata set by `findAll(page=...)` or `setPagination()`.
+
+## Quick Start
+
+```cfm
+<!--- Controller --->
+<cfscript>
+    users = model("User").findAll(page=params.page, perPage=25, order="lastName");
+</cfscript>
+
+<!--- View --->
+#paginationNav()#
+```
+
+This renders a complete `<nav>` element with first/previous/page numbers/next/last links.
+
+## Individual Helpers
+
+### paginationInfo
+
+Displays a text summary of the current pagination state.
+
+```cfm
+#paginationInfo()#
+<!--- Output: "Showing 26-50 of 1,000 records" --->
+
+#paginationInfo(format="Page [currentPage] of [totalPages]")#
+<!--- Output: "Page 2 of 40" --->
+```
+
+Available tokens: `[startRow]`, `[endRow]`, `[totalRecords]`, `[currentPage]`, `[totalPages]`.
+
+### previousPageLink / nextPageLink
+
+```cfm
+#previousPageLink()#  <!--- "Previous" link or disabled span --->
+#nextPageLink()#      <!--- "Next" link or disabled span --->
+
+<!--- Custom text --->
+#previousPageLink(text="&laquo;")#
+#nextPageLink(text="&raquo;")#
+
+<!--- Hide when disabled instead of showing span --->
+#previousPageLink(showDisabled=false)#
+```
+
+### firstPageLink / lastPageLink
+
+```cfm
+#firstPageLink()#  <!--- "First" link or disabled span --->
+#lastPageLink()#   <!--- "Last" link or disabled span --->
+```
+
+### pageNumberLinks
+
+Renders a windowed set of page number links around the current page.
+
+```cfm
+#pageNumberLinks()#
+<!--- Output: 1 2 <span class="current">3</span> 4 5 --->
+
+<!--- Larger window --->
+#pageNumberLinks(windowSize=5)#
+
+<!--- With list markup --->
+#pageNumberLinks(prependToPage="<li>", appendToPage="</li>")#
+```
+
+### paginationNav
+
+Composes all helpers into a semantic `<nav>` element.
+
+```cfm
+<!--- Full navigation --->
+#paginationNav()#
+
+<!--- Without first/last links --->
+#paginationNav(showFirst=false, showLast=false)#
+
+<!--- With info text --->
+#paginationNav(showInfo=true)#
+
+<!--- Custom CSS class --->
+#paginationNav(navClass="my-pagination")#
+```
+
+## Building a Custom Pagination UI
+
+The real power comes from combining helpers individually:
+
+```cfm
+<nav class="pagination" aria-label="Pagination">
+    <div class="pagination-info">
+        #paginationInfo()#
+    </div>
+    <ul class="pagination-links">
+        <li>#previousPageLink(text="&laquo; Prev", disabledClass="text-muted")#</li>
+        #pageNumberLinks(
+            prependToPage="<li>",
+            appendToPage="</li>",
+            classForCurrent="active"
+        )#
+        <li>#nextPageLink(text="Next &raquo;", disabledClass="text-muted")#</li>
+    </ul>
+</nav>
+```
+
+## Bootstrap 5 Example
+
+```cfm
+<nav aria-label="Page navigation">
+    <ul class="pagination">
+        <li class="page-item">#previousPageLink(text="&laquo;", class="page-link", disabledClass="page-link")#</li>
+        #pageNumberLinks(
+            prependToPage="<li class='page-item'>",
+            appendToPage="</li>",
+            class="page-link",
+            classForCurrent="page-link active"
+        )#
+        <li class="page-item">#nextPageLink(text="&raquo;", class="page-link", disabledClass="page-link")#</li>
+    </ul>
+</nav>
+```
+
+## Common Parameters
+
+All helpers support these parameters:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `handle` | `"query"` | Handle for the paginated query |
+| `encode` | `true` | HTML-encode output |
+
+Link helpers (`previousPageLink`, `nextPageLink`, `firstPageLink`, `lastPageLink`) also support:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `text` | Varies | Link text |
+| `name` | `"page"` | Query parameter name |
+| `class` | `""` | CSS class for the link |
+| `disabledClass` | `"disabled"` | CSS class for disabled state |
+| `showDisabled` | `true` | Show disabled span or return empty string |
+| `pageNumberAsParam` | `true` | Page as query param vs route segment |
+
+## Multiple Paginated Queries
+
+Use the `handle` parameter when paginating multiple queries:
+
+```cfm
+<!--- Controller --->
+users = model("User").findAll(page=params.userPage, perPage=10, handle="users", order="name");
+posts = model("Post").findAll(page=params.postPage, perPage=5, handle="posts", order="title");
+
+<!--- View --->
+<h2>Users</h2>
+#paginationNav(handle="users")#
+
+<h2>Posts</h2>
+#paginationNav(handle="posts")#
+```
+
+## Changing Defaults
+
+Override defaults in `config/settings.cfm`:
+
+```cfm
+<cfscript>
+    // Change default text
+    set(functionName="previousPageLink", text="&laquo; Prev");
+    set(functionName="nextPageLink", text="Next &raquo;");
+
+    // Change info format
+    set(functionName="paginationInfo", format="Page [currentPage] of [totalPages]");
+
+    // Larger page number window
+    set(functionName="pageNumberLinks", windowSize=5);
+</cfscript>
+```