This feature is for advanced use cases. Please make sure to read the documentation carefully.
Route resolution is an async operation started by a navigation event, or
by an explicit render() method call. In that process
Vaadin Router goes through the routes config and tries to resolve
each matching route from the root onwards. The default route resolution
rule is to create and return an instance of the route's component
(see the API docs for the setRoutes() method for
details on other route properties and how they affect the route resolution).
Vaadin Router provides a flexible API to customize the default route
resolution rule. Each route may have an action functional
property that defines how exactly that route is resolved. An action
function can return a result either directly, or within
a Promise resolving to the result. If the action result
is an HTMLElement instance,
a commands.component(name) result,
a commands.redirect(path) result,
or a context.next() result, the resolution pass, and
the returned value is what gets rendered. Otherwise, the resolution
process continues to check the other properties of the route and apply
the default resolution rules, and then further to check other
matching routes.
The action(context, commands) function receives a context
parameter with the following properties:
context.pathname [string] the pathname being resolved
context.search [string] the search query stringcontext.hash [string] the hash stringcontext.params [object] the route parameterscontext.route [object] the route that is currently being renderedcontext.next() [function] function for asynchronously getting the next route contents from the resolution chain (if any)commands is a helper object with methods to create return
values for the action:
return commands.redirect('/new/path') create and return a
redirect command for the specified path. This command should be
returned from the action to perform an actual redirect.
return commands.prevent() create and return a prevent
command. This command should be returned from the action
to instruct router to stop the current navigation and remain at the
previous location.
return commands.component('tag-name') create and return a
new HTMLElement that will be rendered into the router
outlet. Using the component command ensures that the
created component is initialized as a Vaadin Router view (i.e. the
location property is set according to the current router
context.
component route property: the action result will be
rendered, if the action is in a child route, the result will be
rendered as light dom child of the component from a parent route.
This demo shows how to use the custom action property to
collect visit statistics for each route.
Since route resolution is async, the action() callback may be
async as well and return a promise. One use case for that is to create
a custom route action that makes a remote API call to fetch the data
necessary to render the route component, before navigating to a route.
Note: If a route has both the component and action
properties, action is executed first and if it does
not return a result Vaadin.Router proceeds to check the component
property.
This demo shows a way to perform async tasks before navigating to any
route under /users.
action() can return a command created using the
commands parameter methods to affect the route resolution
result.
The first demo had demonstrated the context.next() usage,
this demo demonstrates using commands.redirect(path) to
redirect to any other defined route by using its path.
All the parameters in current context will be passed to the redirect target.
Note: If you need only to redirect to another route, defining an action might be an overkill. More convenient way is described in Redirects section.
Another command available to a custom action() is
commands.component('tag-name'). It is useful to create a
custom element with current context. All the parameters in current context
will be passed to the rendered element.
Note: If the only thing your action does is custom element creation, it
can be replaced with component property of the route.
See Getting Started
section for examples.
Route action function can access context.search and
context.hash URL parts, even though they are not involved
in matching route paths.
For example, an action can change the route behavior depending on a search parameter, and optionally render, skip to next route or redirect.