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 may or may not return a value. If it does, that completes
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.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.
HTMLElement (e.g. created with
commands.component('tag-name')
commands.redirect('/new/path')
commands.prevent()
null or undefined
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.