Skip to content

docs: rebuild pass-data guides (route/query parameters & templates) on signals#5672

Draft
peholmst wants to merge 5 commits into
mainfrom
claude/docs-signals-route-params
Draft

docs: rebuild pass-data guides (route/query parameters & templates) on signals#5672
peholmst wants to merge 5 commits into
mainfrom
claude/docs-signals-route-params

Conversation

@peholmst

@peholmst peholmst commented Jun 12, 2026

Copy link
Copy Markdown
Member

Rewrites the three pass-data guides to use Vaadin 25.2 signals for reading URL parameters reactively. The guides stay consistent: route parameters use a manual ValueSignal pattern (the router state signal doesn't fit HasUrlParameter), while route templates and query parameters both read reactively from UI.routerStateSignal().

Route Parameters (HasUrlParameter)

  • Hold the route parameter in a ValueSignal as the single source of truth: setParameter() writes the value, components bind to it, and a Signal.effect navigates the view to itself to keep the URL in sync.
  • Reordered so parameter mechanics (accessing, optional, wildcard) come first and the signal pattern ties it together at the end.

Route Templates (router state signal)

  • Read template parameters reactively from UI.getCurrentOrThrow().routerStateSignal(): derive a Signal per parameter and bind components to it, so the UI updates automatically on navigation.
  • Documents the defensive-read requirement — a binding is first evaluated during view construction, before the router has populated the state, so default (orElse) rather than throw (orElseThrow).
  • Keeps BeforeEnterObserver as the imperative alternative; converts the optional/wildcard sections to focused RouteParameters accessor snippets and removes stray literal snippet markers that were rendering to readers.

Query Parameters (router state signal)

  • Read the parameter reactively from routerStateSignal().get().location().getQueryParameters(), derive a Signal per parameter, and two-way bind a field to it with bindValue(signal, setter) — the field reflects the URL, and edits navigate the view to itself with merged parameters.
  • Keeps the QueryParameters immutability and merging() rules; keeps BeforeEnterObserver as the imperative alternative.

Master-Detail (follow-up)

  • Aligns the "Representing Selection in the URL" note in add-master-detail.adoc with these guides: drops an over-promising "planned for a future release" note (reading parameters reactively already works via routerStateSignal(); writes go through navigate()) and links all three guides.

All example views compile in the docs project, and the runtime behavior of each pattern was validated (direct navigation, self-navigation, optional/missing params, regex-constrained 404s, two-way field binding — no navigation loops or server errors). The route-template and query-parameter idioms match hand-tested reference implementations.

🤖 Generated with Claude Code

peholmst and others added 2 commits June 12, 2026 13:49
Hold the route parameter in a ValueSignal as the single source of
truth: setParameter() writes the value, components bind to it, and a
signal effect navigates the view to itself to keep the URL in sync.
Reorder the guide so parameter mechanics (accessing, optional,
wildcard) come first and the signal pattern ties it together at the
end.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Read route-template parameters reactively from
UI.getCurrentOrThrow().routerStateSignal(): derive a Signal per
parameter and bind components to it, so the UI updates automatically
on navigation. Lead the access section with this pattern, note the
defensive-read requirement (the binding evaluates during construction
before params are populated, so default rather than throw), and keep
BeforeEnterObserver as the imperative alternative. Convert the
optional and wildcard sections to focused RouteParameters accessor
snippets and drop stray literal snippet markers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jun 12, 2026

Copy link
Copy Markdown

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-5672.fly.dev

Built from 379b891

Read the query parameter reactively from
UI.getCurrentOrThrow().routerStateSignal().get().location()
.getQueryParameters(): derive a Signal per parameter and two-way bind
a field to it with bindValue(), so the field reflects the URL and
edits navigate the view to itself with merged parameters. Lead with
reactive reading, keep the QueryParameters immutability/merging rules,
and keep BeforeEnterObserver as the imperative alternative.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@peholmst peholmst changed the title docs: rebuild route parameters & templates guides on signals docs: rebuild pass-data guides (route/query parameters & templates) on signals Jun 12, 2026
peholmst and others added 2 commits June 12, 2026 16:30
Drop the "reading and writing parameters as signals is planned"
note, which over-promised. Reading route and query parameters
reactively already works today through UI.routerStateSignal(); writes
go through navigate(). Point to the Route Parameters, Route Templates,
and Query Parameters guides for the concrete patterns.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
:toclevels: 2

In this guide, you'll learn how to create a view that accepts a single route parameter. You'll also explore the differences between optional and wildcard route parameters.
In this guide, you'll learn how to create a view that accepts a single route parameter, holds it in a <</flow/ui-state#,signal>> so the UI updates reactively, and keeps the browser URL in sync. You'll also explore the differences between optional and wildcard route parameters.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the order on this page could be improved as it reads a bit like:

  1. Accessing the Route Parameter Value
  2. Optional Parameters
  3. Wildcard Parameters
  4. Naah, don't actually do as shown above, do it like this (Holding the Parameter in a Signal)

It could be restructured so you start from "This is how you get a parameter into the UI through a signal", then "optional parameters" -> "wildcard parameters"

I'm not sure you even need to explicitly spell out that you don't have to use a signal, or maybe spell it out like that in the first part.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants