app-router
app-router copied to clipboard
erikringsmuth
Router for Web Components
Router for Web Components
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.
Configuration
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>
Navigation
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.
hashchange
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">.
pushState
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.
go(path, options)
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>
Data Binding
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.
<app-route> options
import a custom element
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.
pre-loaded custom element
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>
import template
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>
inline template
Finally, you can in-line a <template> like this.
<app-route path="/example">
<template>
<p>Inline template FTW!</p>
</template>
</app-route>
regular expressions
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>
redirect
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.
<app-router> options
mode
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.
trailing slashes
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>
Demo Site & Example Setup
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.
Breaking Changes
Check the change log for breaking changes in major versions.
Build, Test, and Debug 
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 installandnpm installto 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-serverorpython -m SimpleHTTPServer) and open http://localhost:8080/tests/functional-tests/
erikringsmuth