paginationNav() / pageNumberLinks() cannot emit Bootstrap <li class="page-item active"> pattern without regex post-process in app code

[bpamiri]

Severity: medium — same audience as #2715 (Bootstrap-styled 3.x apps). Forces a regex hack in every app's pagination helper.

Surfaced by: titan Phase 2.4 (Wheels 4.0 upgrade), 2026-05-15.

Description

The Bootstrap pagination pattern places the active-page class on the <li> wrapper, not on the <a>:

<ul class=\"pagination\">
  <li class=\"page-item\"><a class=\"page-link\" href=\"...\">1</a></li>
  <li class=\"page-item active\"><a class=\"page-link\" href=\"...\">2</a></li>
  <li class=\"page-item\"><a class=\"page-link\" href=\"...\">3</a></li>
</ul>

Neither paginationLinks() (legacy) nor pageNumberLinks() (4.0 primitive used internally by paginationNav()) can emit this. Both put classForCurrent on the <a>:

<li class=\"page-item\"><a class=\"page-link active\" href=\"...\">2</a></li>

The legacy addActiveClassToPrependedParent arg sounds like it should help, but it only inserts the class into the wrapper's existing class attribute; it doesn't replace the active on the anchor. Apps still need a Replace() regex post-process to move the class from <a> to <li>.

Titan's working pattern (in app/views/helpers.cfm after Phase 2.4 migration) keeps a Replace() hack across the bsPaginationLinks() output:

local.rv = Replace(local.rv, \" active\", \"\", \"all\");  // strip from anchors
// ... then re-insert into <li> via different code path

Suggested fix

Add to pageNumberLinks() (and inherited by paginationNav()) one of:

• activeClassOnPrependedParent — if true, omit classForCurrent from the anchor, append it to prependToPage's class attribute on the current-page iteration only.
• currentPageWrap=\"<li class='page-item active'><a class='page-link'>\" — full override on the current page, regardless of normal prependToPage.

Either lets Bootstrap-styled apps drop the regex hack.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:2718 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

paginationNav() / pageNumberLinks() emit the active class on the <a> tag, but Bootstrap (and most modern CSS pagination components) place the active state on the <li> wrapper — and render the current page as a non-clickable <span>, not an anchor. Bootstrap-styled apps are running Replace() regexes over the helper output to fix this. The issue proposes two candidate knobs (activeClassOnPrependedParent flag, currentPageWrap string), and asks whether a less hacky path exists.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails (kaminari)	"theme" / "partials"	Generator copies 7 partials (_page, _current_page, _first_page, …) to app/views/kaminari/, theme: kwarg picks subdir	Pure ERB — no subclassing; 7 files per theme is a lot but each is tiny	Separate _current_page partial renders <li class="active"><span> (not anchor)
Laravel	"views"	Paginator::useBootstrapFive() preset, defaultView('path'), or vendor:publish Blade templates	3-tier escalation: preset → defaultView → publish. Globally mutable state on Paginator class	Bootstrap 5 view renders current as <li class="page-item active" aria-current="page"><span class="page-link">N</span></li>
Django	"template tag"	Core ships zero helper (write your own template); ecosystem (django-bootstrap-pagination) ships inclusion tag + overridable template	Full control, zero defaults in core; every project reinvents ~15 lines of template	Third-party tag emits <li class="page-item active"><span> — anchor structurally absent on current page
Phoenix (Scrivener.HTML)	"view_style"	Single option: view_style: :bootstrap_v4 (also :bootstrap, :foundation, :semantic, :materialize, :bulma). Escape hatch: raw_pagination_links/2 returns {text, page_number} tuples	Declarative preset for 95%; tuple-list escape hatch for custom markup. Can't register custom themes user-side (PR upstream)	6 built-in styles; current page = <li class="active">; first/prev/next icons accept safe-HTML overrides
Spring Boot (Thymeleaf)	"fragment"	Spring ships only the Page<T> data model; markup is a hand-authored th:fragment per app	Maximum control, zero abstraction. Every project re-implements ~25-40 lines	th:classappend="${pg.number==i} ? 'active'" on <li> directly — wrapper-class problem doesn't exist because devs author the <li>
Symfony (KnpPaginator) — picked as +1 because it ships the most extensive CSS-framework preset library	"template"	knp_paginator.template.pagination: '@KnpPaginator/Pagination/twitter_bootstrap_v5_pagination.html.twig' config key, per-call setTemplate(), or copy to templates/bundles/KnpPaginatorBundle/ to override	Layered: config preset (95%) → per-render arg → fork template. Forked templates can drift on upgrade	~12 built-in presets (Bootstrap 3/4/5, Foundation 5/6, Bulma, Semantic, Materialize, Tailwind, UIKit). Current page swaps <a> for <span> and moves active to <li> inside the template

Dominant pattern

Four of the six frameworks (Laravel, Phoenix, Symfony/KnpPaginator, Rails/kaminari) have converged on a named-preset / swappable-template model where the entire emitted markup is selected by a single declarative knob — not assembled by stacking string-concat arguments like prependToPage + classForCurrent + appendToPage. The remaining two (Django core, Spring/Thymeleaf) opt out of providing a helper at all and force the app to author the markup. No framework researched is doing the string-knob-with-many-flags approach Wheels currently uses — it's an evolutionary dead-end, which is why this issue exists. All four "preset" frameworks share a second structural insight the suggested-fix args miss: the current page is a different DOM shape (<span>, not <a>) — trying to fix this with a flag that moves a class around still leaves the anchor wrong for accessibility (aria-current, keyboard focus). The right fix is not "let me move the active class to the wrapper"; it's "let me pick a CSS-framework preset and have the helper emit the correct shape."

Recommended path for Wheels

Mirror Phoenix's view_style: design — it's the lightest-weight match for Wheels' existing helper API and avoids new infrastructure (no partial-override system, no generator, no global mutable state). Add a single viewStyle argument to paginationNav() (and pass-through to pageNumberLinks()); ship 3-4 named presets covering the common CSS frameworks; default to "plain" for full backwards compatibility. The existing prependToPage / appendToPage knobs stay as-is for callers using the raw primitive pageNumberLinks() directly — viewStyle is an additive opt-in.

// vendor/wheels/view/pagination.cfc — additive viewStyle on paginationNav()
public string function paginationNav(
    string handle = "query",
    string viewStyle,       // "plain" (default) | "bootstrap5" | "bootstrap4" | "tailwind"
    string navClass,
    boolean showFirst,
    boolean showLast,
    boolean showPrevious,
    boolean showNext,
    boolean showInfo,
    boolean showSinglePage,
    any encode
) {
    $args(name = "paginationNav", args = arguments);
    // viewStyle dispatches to $renderPaginationPage() below, which emits
    // the correct wrapper for the chosen CSS framework. "plain" preserves
    // today's behavior byte-for-byte.
}

// Internal renderer dispatched on viewStyle — emits one page's HTML
public string function $renderPaginationPage(
    required numeric pageNumber,
    required boolean isCurrent,
    required string viewStyle,
    required struct linkArgs
) {
    if (arguments.viewStyle == "bootstrap5" || arguments.viewStyle == "bootstrap4") {
        if (arguments.isCurrent) {
            return '<li class="page-item active" aria-current="page">'
                & '<span class="page-link">' & NumberFormat(arguments.pageNumber) & '</span>'
                & '</li>';
        }
        arguments.linkArgs.class = "page-link";
        return '<li class="page-item">' & linkTo(argumentCollection = arguments.linkArgs) & '</li>';
    }
    // ... "tailwind" branch ...
    // ... "plain" falls back to today's pageNumberLinks() output unchanged ...
}

Usage:

##paginationNav(viewStyle="bootstrap5")##                 // canonical Bootstrap 5 markup
##paginationNav(viewStyle="bootstrap4", showInfo=true)##  // BS4 + info text
##paginationNav()##                                       // unchanged — current 4.0 behavior

Lives in: vendor/wheels/view/pagination.cfc (extend paginationNav() + add $renderPaginationPage() private helper).
Composes with: existing pagination() query metadata, linkTo() for anchors, $args() for default resolution, $paginationLinkToArgs() for URL building. No new mixin, no new lifecycle hook, no new DI scope.

Cross-engine notes

None. The proposed sketch uses only string concatenation, struct-key access via dot notation (no obj["key"]()), and argumentCollection passing — all clean on Lucee 6/7, Adobe 2023/2025, and BoxLang. No closures, no struct.map(), no client scope, no array-by-value-in-struct-literal pitfalls. $args() and linkTo() are already cross-engine. The $ prefix on the internal helper avoids the private mixin-integration gotcha from CLAUDE.md ("private mixin functions not integrated").

Open questions

• Which preset names to ship for v1? "bootstrap5", "bootstrap4", "tailwind", "plain" is the minimum useful set; "bulma", "foundation", "semantic" could follow. Phoenix shipped 6; Symfony ~12; Laravel 4-5. Recommend starting with 4 and adding by demand.
• Should pageNumberLinks() also take viewStyle? The issue framing is about paginationNav() (the all-in-one), but apps calling the raw primitive should ideally get the same affordance. Adding it to both is one extra branch.
• Future extension — partial overrides? Kaminari and Symfony both allow users to drop a partial in their app to override a preset entirely. Wheels could support this later (e.g., viewStyle="custom" reads from app/views/wheels/_pagination_page.cfm), but it's not needed for v1 and would be a separate PR.
• Bootstrap 3 support? Phoenix kept it; Laravel dropped it in 9.x. Recommend skipping — Bootstrap 3 is EOL and the BS4/BS5 markup is identical for page-item active.

Confidence: high

The dominant pattern is clear across 4/6 frameworks, the proposed CFML sketch uses only existing primitives ($args, linkTo, dot-notation struct access), no Wheels anti-patterns or cross-engine traps appear, and no new infrastructure is required — viewStyle is one additive argument with a default that preserves current behavior byte-for-byte.

Sources

• Rails — https://github.com/kaminari/kaminari, https://github.com/mislav/will_paginate/wiki/Link-renderer
• Laravel — https://laravel.com/docs/11.x/pagination, https://github.com/laravel/framework/tree/11.x/src/Illuminate/Pagination/resources/views
• Django — https://docs.djangoproject.com/en/5.0/topics/pagination/, https://github.com/jmcclell/django-bootstrap-pagination
• Phoenix — https://hexdocs.pm/scrivener_html/Scrivener.HTML.html, https://github.com/mgwidmann/scrivener_html
• Spring Boot / Thymeleaf — https://www.thymeleaf.org/doc/articles/standardurlsyntax.html, https://www.bezkoder.com/thymeleaf-pagination/
• Symfony / KnpPaginator — https://github.com/KnpLabs/KnpPaginatorBundle, https://github.com/KnpLabs/KnpPaginatorBundle/blob/master/docs/templates.md

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2731

Spec: vendor/wheels/tests/specs/view/paginationHelpersSpec.cfc — new describe blocks for pageNumberLinks(viewStyle=…) and paginationNav(viewStyle=…) presets (bootstrap5, bootstrap4, tailwind, plain). Local test runner was unavailable in the bot sandbox (Wheels CLI not installed), so the failing-then-passing handoff will be validated by the compat-matrix CI on the PR.
Implementation:

• vendor/wheels/view/pagination.cfc — viewStyle arg + $renderPaginationPage / $renderPaginationNav / $renderPaginationNavLink internal helpers
• vendor/wheels/events/init/functions.cfm — viewStyle = "plain" default for both functions

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.