Manage page state. Lazy-load content. Data-bind path variables and query parameters. Use multiple layouts. Navigate with hashchange
and HTML5 pushState
. Animate transitions using core-animated-pages
.
Download or run bower install app-router --save
.
Define how URLs map to pages.
<!doctype html>
<html>
<head>
<title>App Router</title>
<link rel="import" href="/bower_components/app-router/app-router.html">
</head>
<body>
<app-router>
<!-- matches an exact path -->
<app-route path="/home" import="/pages/home-page.html"></app-route>
<!-- matches using a wildcard -->
<app-route path="/customer/*" import="/pages/customer-page.html"></app-route>
<!-- matches using a path variable -->
<app-route path="/order/:id" import="/pages/order-page.html"></app-route>
<!-- matches a pattern like '/word/number' -->
<app-route path="/^\/\w+\/\d+$/i" regex import="/pages/regex-page.html"></app-route>
<!-- matches everything else -->
<app-route path="*" import="/pages/not-found-page.html"></app-route>
</app-router>
</body>
</html>
Click links or call router.go()
.
<!-- hashchange -->
<a href="#/home">Home</a>
<!-- pushState() -->
<a is="pushstate-anchor" href="/home">Home</a>
<!-- router.go(path, options) -->
<script>
document.querySelector('app-router').go('/home');
</script>
The router listens to popstate
and hashchange
events. Changing the URL will find the first app-route
that matches, load the element or template, and replace the current view.
Clicking <a href="#/home">Home</a>
will fire a hashchange
event and tell the router to load the first route that matches /home
. You don't need to handle the event in your Javascript. Hash paths #/home
match routes without the hash <app-route path="/home">
.
You can use the pushstate-anchor or html5-history-anchor to extend <a>
tags with the HTML5 history API.
<a is="pushstate-anchor" href="/home">Home</a>
This will call pushState()
and dispatch a popstate
event.
You can call the router from Javascript to navigate imperatively.
document.querySelector('app-router').go('/home');
// or
document.querySelector('app-router').go('/home', {replace: true});
If you use go(path, options)
you should also set the mode to hash
or pushstate
on the router.
<app-router mode="auto|pushstate|hash">
<!-- app-routes -->
</app-router>
Path variables and query parameters automatically attach to the element's attributes.
<!-- url -->
<a is="pushstate-anchor" href="/order/123?sort=ascending">Order 123</a>
<!-- route -->
<app-route path="/order/:orderId" import="/pages/order-page.html"></app-route>
<!-- will bind 123 to the page's `orderId` attribute and "ascending" to the `sort` attribute -->
<order-page orderId="123" sort="ascending"></order-page>
If you're using Polymer, you can also bind path variables and query parameters to templates.
<app-route path="/order/:orderId">
<template>
<p>Your order number is {{orderId}}</p>
</template>
</app-route>
See it in action here.
Lazy-load a custom element.
<app-route path="/customer/:customerId" import="/pages/customer-page.html" [element="customer-page"]></app-route>
You only need to set the element
attribute if the element's name is different than the file name.
Include the element="element-name"
attribute on the route to use a pre-loaded custom element. This is how you use bundled (vulcanized) custom elements.
<head>
<link rel="import" href="/pages/page-bundle.html">
</head>
<app-router>
<app-route path="/customer/:customerId" element="customer-page"></app-route>
</app-router>
You can import a <template>
instead of a custom element. Just include the template
attribute.
<app-route path="/example" import="/pages/template-page.html" template></app-route>
Finally, you can in-line a <template>
like this.
<app-route path="/example">
<template>
<p>Inline template FTW!</p>
</template>
</app-route>
Include the regex
attribute to match on a regular expression. The format is the same as a JavaScript regular expression.
<!-- matches a pattern like '/word/number' -->
<app-route path="/^\/\w+\/\d+$/i" regex import="/pages/regex-page.html"></app-route>
A route can redirect to another path.
<app-router mode="pushstate">
<app-route path="/home" import="/pages/home-page.html"></app-route>
<app-route path="*" redirect="/home"></app-route>
</app-router>
When you use redirect
you should also set mode="hash|pushstate"
on the app-router
.
One set of routes will match regular paths /
and hash paths #/
. You can force a specific mode with mode="auto|hash|pushstate"
.
<app-router mode="pushstate">
<!-- always ignore the hash and match on the path -->
</app-router>
When left in auto
, redirects and go(path, options)
will use hash paths.
By default /home
and /home/
are treated as separate routes. You can configure the router to ignore trailing slashes with trailingSlash="ignore"
.
<app-router trailingSlash="ignore">
<!-- matches '/home' and '/home/' -->
<app-route path="/home" import="/pages/home-page.html"></app-route>
</app-router>
Check out the app-router
in action at erikringsmuth.github.io/app-router.
You can download an example setup here https://github.com/erikringsmuth/app-router-examples to get running locally.
Examples showing app-router
and flatiron-director
versus no router https://github.com/erikringsmuth/polymer-router-demos.
Check the change log for breaking changes in major versions.
Source files are under the src
folder. The build process writes to the root directory. The easiest way to debug is to include the source script rather than the minified HTML import.
<script src="/bower_components/app-router/src/app-router.js"></script>
To build:
- Run
bower install
andnpm install
to install dev dependencies - Lint, test, build, and minify code with
gulp
- Manually run functional tests in the browser by starting a static content server (node
http-server
orpython -m SimpleHTTPServer
) and open https://localhost:8080/tests/functional-tests/