Router classThe Router class is the only thing you need to get started
with Vaadin Router. Depending on your project setup, there are several
ways to access it.
In modern browsers that support ES modules the
Router class can be imported directly into a script tag on a page:
<script type="module">
import {Router} from 'https://unpkg.com/@vaadin/router';
</script>In Webpack / Rollup / Polymer CLI projects the Router class can
be imported from the @vaadin/router npm package:
import {Router} from '@vaadin/router';
In older browsers without the ES modules support the
Router class is exposed as a member of the Vaadin
namespace after the vaadin-router UMD bundle is loaded:
<script src="https://unpkg.com/@vaadin/router/dist/vaadin-router.umd.min.js"></script>
<script>
var Router = Vaadin.Router;
</script>Vaadin Router automatically listens to navigation events and
asynchronously renders a matching Web Component into the given DOM node
(a.k.a. the router outlet). By default, navigation events are
triggered by popstate events on the window, and
by click events on <a> elements on the
page.
The routes config maps URL paths to Web Components. Vaadin Router goes through the routes until it finds the first match, creates an instance of the route component, and inserts it into the router outlet (replacing any pre-existing outlet content). For details on the route path syntax see the Route Parameters demos.
Route components can be any Web Components regardless of how they are built: vanilla JavaScript, Polymer, Stencil, SkateJS, Angular, Vue, etc.
Vaadin Router follows the lifecycle callbacks convention described in WebComponentInterface: if a route component defines any of these callback methods, Vaadin Router will call them at the appropriate points in the navigation lifecycle. See the Lifecycle Callbacks section for more details.
In addition to that Vaadin Router also sets a
location
property on every route Web Component so that you could access the
current location details via an instance property (e.g.
this.location.pathname).
this.location
If you use Polymer and JavaScript to build your view components,
the location property does not require a declaration.
It is recommended to add it to the properties of your
component for consistency, though:
static get properties() {
return {
// ...
location: Object
};
}
For LitElement and TypeScript a declaration in the component is required.
Declare the location property in the class and initialize it
from the router Vaadin Router instance:
import {router} from './index';
import {customElement, html, LitElement, property} from 'lit-element';
@customElement('my-view')
class MyViewElement extends LitElement {
@property({type: Object}) location = router.location;
render() {
return html`
Current location URL: ${this.location.getUrl()}
`;
}
}This property is automatically updated on navigation.
If Vaadin Router does not find a matching route, the promise returned
from the render() method gets rejected, and any content in
the router outlet is removed. In order to show a user-friendly 'page not
found' view, a fallback route with a wildcard '(.*)' path can
be added to the end of the routes list.
There can be different fallbacks for different route prefixes, but since the route resolution is based on the first match, the fallback route should always be after other alternatives.
The path that leads to the fallback route is available to the route
component via the location.pathname property.
Each route can have child routes, which makes it easier to group related routes together under a common parent. This is optional, i.e. the same routes config can be expressed as a flat list, or as a parent-children tree. The routes config in the example below is effectively the same as in the "Getting Started" example above.
The leading '/' in child route paths is optional—they
are always relative to the path of the parent route.
In certain cases, for instance when creating a navigation bar shown on certain application pages,
it is useful to define a common layout and reuse it. Vaadin Router supports this by specifying
the component property both in parent and child route objects.
In this case child route's component will be rendered as a light DOM child of parent route's component.
When using Web Components, in order to display the children rendered by Vaadin Router, parent component should contain
the <slot>
tag in its Shadow DOM. The parent layout component stays in the DOM when you switch between the child routes.
Vaadin Router supports cases when the app is deployed to a subpath, for
example, example.com/shop/. The
baseUrl property
defines a common prefix for all URLs handled by a router instance.
The <base href="..."> tag in
the <head>of the document is used to set the base URL
globally. Alternatively, the base URL can be configured on the router
instance using with the constructor option.
When the base URL is set, only the links matching the base URL are handled by the router. Links that do no match the base URL are considered external, clicking such a link will result in a regular navigation.
When some <a> links are external for the app, Vaadin
Router can be configured to ignore them and let the browser handle these
links in the default way:
<a href="/users" router-ignore>Users</a>
When an large set of URLs needs to be ignored (e.g. all URLs starting
with /external), it may be impractical to add the
router-ignore attribute to each link separately.
For such cases a more practical approach would be to add a special route
to the top of the router config: