Chapter 12: Path of Pilgrimage - Walk from page to page

setResponsePage

Use setResponsePage() for event-driven navigation in handlers such as link clicks and form submit success paths.

BookmarkablePageLink

BookmarkablePageLink creates stable URLs that users can share and revisit directly.

PageParameters

Use PageParameters for route context: IDs, filters, and read-only hints. Validate parameters before use.

Flow Design

Design navigation as explicit user journeys: entry, action, feedback, and return path. Clear flow prevents accidental dead ends.

Practical Pitfalls

Problem
After login, users do not return to the page they originally requested.

Cause
Original destination is not preserved and flow always redirects to a fixed page.

Solution
Implement post-auth return-to-original-destination flow.
Problem
Shared URLs fail to reproduce expected state.

Cause
Navigation is over-optimized for hidden state and loses bookmarkable reproducibility.

Solution
Balance privacy and reproducibility; keep public flows bookmarkable where possible.
Problem
Back button or duplicated tabs trigger PageExpired/Stale exceptions.

Cause
Users interact with outdated render-count state.

Solution
Provide clear recovery guidance and reduce multi-action conflicts on update-heavy pages.
Problem
Parallel tab usage increases random update failures.

Cause
Same page instance state is manipulated concurrently from multiple tabs.

Solution
Design update screens with multi-tab behavior in mind and add operation constraints when needed.
Problem
Users are confused by unexpected stale-state failures.

Cause
Even non-standard actions (like source view paths) can create state divergence in some flows.

Solution
Use explicit error text that tells users to reload and continue safely.
Problem
Root-cause analysis for stale exceptions takes too long.

Cause
Teams inspect logs only and skip user-operation scenario replay.

Solution
Start diagnosis with reproducible scenarios: back, duplicate tab, and double-submit paths.