1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<!---
This README is automatically generated from the comments in these files:
app-location.html app-route-converter-behavior.html app-route-converter.html app-route.html
Edit those files, and our readme bot will duplicate them over here!
Edit this file, and the bot will squash your changes :)
The bot does some handling of markdown. Please file a bug if it does the wrong
thing! https://github.com/PolymerLabs/tedium/issues
-->
[](https://travis-ci.org/PolymerElements/app-route)
## <app-route>
`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`:
```html
<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:
```html
<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>
`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`:
```css
{
prefix: '',
path: '/elements/app-location'
}
```
Example Usage:
```html
<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.
### Hashes vs Paths
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:
```html
<app-location route="{{route}}" use-hash-as-path></app-location>
```
### Integrating with other routing code
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.
```javascript
window.history.pushState({}, null, '/new_path');
window.dispatchEvent(new CustomEvent('location-changed'));
```
## <app-route-converter>
`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](https://github.com/PolymerElements/app-route/blob/master/app-location.html)
and [app-route](https://github.com/PolymerElements/app-route/blob/master/app-route.html).
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:
```css
{
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:
```html
<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`.
## Polymer.AppRouteConverterBehavior
Provides bidirectional mapping between `path` and `queryParams` and a
app-route compatible `route` object.
For more information, see the docs for `app-route-converter`.
|
