docs: rebuild pass-data guides (route/query parameters & templates) on signals#5672
Draft
peholmst wants to merge 5 commits into
Draft
docs: rebuild pass-data guides (route/query parameters & templates) on signals#5672peholmst wants to merge 5 commits into
peholmst wants to merge 5 commits into
Conversation
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>
Preview DeploymentThis 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>
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>
Artur-
reviewed
Jun 13, 2026
| :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. |
Member
There was a problem hiding this comment.
I think the order on this page could be improved as it reads a bit like:
- Accessing the Route Parameter Value
- Optional Parameters
- Wildcard Parameters
- 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
ValueSignalpattern (the router state signal doesn't fitHasUrlParameter), while route templates and query parameters both read reactively fromUI.routerStateSignal().Route Parameters (
HasUrlParameter)ValueSignalas the single source of truth:setParameter()writes the value, components bind to it, and aSignal.effectnavigates the view to itself to keep the URL in sync.Route Templates (router state signal)
UI.getCurrentOrThrow().routerStateSignal(): derive aSignalper parameter and bind components to it, so the UI updates automatically on navigation.orElse) rather than throw (orElseThrow).BeforeEnterObserveras the imperative alternative; converts the optional/wildcard sections to focusedRouteParametersaccessor snippets and removes stray literal snippet markers that were rendering to readers.Query Parameters (router state signal)
routerStateSignal().get().location().getQueryParameters(), derive aSignalper parameter, and two-way bind a field to it withbindValue(signal, setter)— the field reflects the URL, and edits navigate the view to itself with merged parameters.QueryParametersimmutability andmerging()rules; keepsBeforeEnterObserveras the imperative alternative.Master-Detail (follow-up)
add-master-detail.adocwith these guides: drops an over-promising "planned for a future release" note (reading parameters reactively already works viarouterStateSignal(); writes go throughnavigate()) 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