app-route
is an element that enables declarative, self-describing routing for a web app.
n.b. app-route is still in beta. We expect it will need some changes. We're counting on your feedback!
In its typical usage, a app-route
element consumes an object that describes some state about the current route, via the route
property. It then parses that state using the pattern
property, and produces two artifacts: some data
related to the route
, and a tail
that contains the rest of the route
that did not match.
Here is a basic example, when used with app-location
:
<app-location route="{{route}}"></app-location> <app-route route="{{route}}" pattern="/:page" data="{{data}}" tail="{{tail}}"> </app-route>
In the above example, the app-location
produces a route
value. Then, the route.path
property is matched by comparing it to the pattern
property. If the pattern
property matches route.path
, the app-route
will set or update its data
property with an object whose properties correspond to the parameters in pattern
. So, in the above example, if route.path
was '/about'
, the value of data
would be {"page": "about"}
.
The tail
property represents the remaining part of the route state after the pattern
has been applied to a matching route
.
Here is another example, where tail
is used:
<app-location route="{{route}}"></app-location> <app-route route="{{route}}" pattern="/:page" data="{{routeData}}" tail="{{subroute}}"> </app-route> <app-route route="{{subroute}}" pattern="/:id" data="{{subrouteData}}"> </app-route>
In the above example, there are two app-route
elements. The first app-route
consumes a route
. When the route
is matched, the first app-route
also produces routeData
from its data
, and subroute
from its tail
. The second app-route
consumes the subroute
, and when it matches, it produces an object called subrouteData
from its data
.
So, when route.path
is '/about'
, the routeData
object will look like this: { page: 'about' }
And subrouteData
will be null. However, if route.path
changes to '/article/123'
, the routeData
object will look like this: { page: 'article' }
And the subrouteData
will look like this: { id: '123' }
app-route
is responsive to bi-directional changes to the data
objects they produce. So, if routeData.page
changed from 'article'
to 'about'
, the app-route
will update route.path
. This in-turn will update the app-location
, and cause the global location bar to change its value.
app-location
is an element that provides synchronization between the browser location bar and the state of an app. When created, app-location
elements will automatically watch the global location for changes. As changes occur, app-location
produces and updates an object called route
. This route
object is suitable for passing into a app-route
, and other similar elements.
An example of the public API of a route object that describes the URL https://elements.polymer-project.org/elements/app-location
:
{ prefix: '', path: '/elements/app-location' }
Example Usage:
<app-location route="{{route}}"></app-location> <app-route route="{{route}}" pattern="/:page" data="{{data}}"></app-route>
As you can see above, the app-location
element produces a route
and that property is then bound into the app-route
element. The bindings are two- directional, so when changes to the route
object occur within app-route
, they automatically reflect back to the global location.
By default app-location
routes using the pathname portion of the URL. This has broad browser support but it does require cooperation of the backend server. An app-location
can be configured to use the hash part of a URL instead using the use-hash-as-path
attribute, like so:
<app-location route="{{route}}" use-hash-as-path></app-location>
There is no standard event that is fired when window.location is modified. app-location
fires a location-changed
event on window
when it updates the location. It also listens for that same event, and re-reads the URL when it's fired. This makes it very easy to interop with other routing code.
So for example if you want to navigate to /new_path
imperatively you could call window.location.pushState
or window.location.replaceState
followed by firing a location-changed
event on window
. i.e.
window.history.pushState({}, null, '/new_path'); window.dispatchEvent(new CustomEvent('location-changed'));
app-route-converter
provides a means to convert a path and query parameters into a route object and vice versa. This produced route object is to be fed into route-consuming elements such as app-route
.
n.b. This element is intended to be a primitive of the routing system and for creating bespoke routing solutions from scratch. To simply include routing in an app, please refer to app-location and app-route.
An example of a route object that describes https://elements.polymer-project.org/elements/app-route-converter?foo=bar&baz=qux
and should be passed to other app-route
elements:
{ prefix: '', path: '/elements/app-route-converter', __queryParams: { foo: 'bar', baz: 'qux' } }
__queryParams
is private to discourage directly data-binding to it. This is so that routing elements like app-route
can intermediate changes to the query params and choose whether to propagate them upstream or not. app-route
for example will not propagate changes to its queryParams
property if it is not currently active. A public queryParams object will also be produced in which you should perform data-binding operations.
Example Usage:
<iron-location path="{{path}}" query="{{query}}"></iron-location> <iron-query-params params-string="{{query}}" params-object="{{queryParams}}"> </iron-query-params> <app-route-converter path="{{path}}" query-params="{{queryParams}}" route="{{route}}"> </app-route-converter> <app-route route='{{route}}' pattern='/:page' data='{{data}}'> </app-route>
This is a simplified implementation of the app-location
element. Here the iron-location
produces a path and a query, the iron-query-params
consumes the query and produces a queryParams object, and the app-route-converter
consumes the path and the query params and converts it into a route which is in turn is consumed by the app-route
.
Provides bidirectional mapping between path
and queryParams
and a app-route compatible route
object.
For more information, see the docs for app-route-converter
.