1 2<!--- 3 4This README is automatically generated from the comments in these files: 5app-location.html app-route-converter-behavior.html app-route-converter.html app-route.html 6 7Edit those files, and our readme bot will duplicate them over here! 8Edit this file, and the bot will squash your changes :) 9 10The bot does some handling of markdown. Please file a bug if it does the wrong 11thing! https://github.com/PolymerLabs/tedium/issues 12 13--> 14 15[](https://travis-ci.org/PolymerElements/app-route) 16 17 18## <app-route> 19 20`app-route` is an element that enables declarative, self-describing routing 21for a web app. 22 23> *n.b. app-route is still in beta. We expect it will need some changes. We're counting on your feedback!* 24 25In its typical usage, a `app-route` element consumes an object that describes 26some state about the current route, via the `route` property. It then parses 27that state using the `pattern` property, and produces two artifacts: some `data` 28related to the `route`, and a `tail` that contains the rest of the `route` that 29did not match. 30 31Here is a basic example, when used with `app-location`: 32 33```html 34<app-location route="{{route}}"></app-location> 35<app-route 36 route="{{route}}" 37 pattern="/:page" 38 data="{{data}}" 39 tail="{{tail}}"> 40</app-route> 41``` 42 43In the above example, the `app-location` produces a `route` value. Then, the 44`route.path` property is matched by comparing it to the `pattern` property. If 45the `pattern` property matches `route.path`, the `app-route` will set or update 46its `data` property with an object whose properties correspond to the parameters 47in `pattern`. So, in the above example, if `route.path` was `'/about'`, the value 48of `data` would be `{"page": "about"}`. 49 50The `tail` property represents the remaining part of the route state after the 51`pattern` has been applied to a matching `route`. 52 53Here is another example, where `tail` is used: 54 55```html 56<app-location route="{{route}}"></app-location> 57<app-route 58 route="{{route}}" 59 pattern="/:page" 60 data="{{routeData}}" 61 tail="{{subroute}}"> 62</app-route> 63<app-route 64 route="{{subroute}}" 65 pattern="/:id" 66 data="{{subrouteData}}"> 67</app-route> 68``` 69 70In the above example, there are two `app-route` elements. The first 71`app-route` consumes a `route`. When the `route` is matched, the first 72`app-route` also produces `routeData` from its `data`, and `subroute` from 73its `tail`. The second `app-route` consumes the `subroute`, and when it 74matches, it produces an object called `subrouteData` from its `data`. 75 76So, when `route.path` is `'/about'`, the `routeData` object will look like 77this: `{ page: 'about' }` 78 79And `subrouteData` will be null. However, if `route.path` changes to 80`'/article/123'`, the `routeData` object will look like this: 81`{ page: 'article' }` 82 83And the `subrouteData` will look like this: `{ id: '123' }` 84 85`app-route` is responsive to bi-directional changes to the `data` objects 86they produce. So, if `routeData.page` changed from `'article'` to `'about'`, 87the `app-route` will update `route.path`. This in-turn will update the 88`app-location`, and cause the global location bar to change its value. 89 90 91 92## <app-location> 93 94`app-location` is an element that provides synchronization between the 95browser location bar and the state of an app. When created, `app-location` 96elements will automatically watch the global location for changes. As changes 97occur, `app-location` produces and updates an object called `route`. This 98`route` object is suitable for passing into a `app-route`, and other similar 99elements. 100 101An example of the public API of a route object that describes the URL 102`https://elements.polymer-project.org/elements/app-location`: 103 104```css 105{ 106 prefix: '', 107 path: '/elements/app-location' 108} 109``` 110 111Example Usage: 112 113```html 114<app-location route="{{route}}"></app-location> 115<app-route route="{{route}}" pattern="/:page" data="{{data}}"></app-route> 116``` 117 118As you can see above, the `app-location` element produces a `route` and that 119property is then bound into the `app-route` element. The bindings are two- 120directional, so when changes to the `route` object occur within `app-route`, 121they automatically reflect back to the global location. 122 123### Hashes vs Paths 124 125By default `app-location` routes using the pathname portion of the URL. This has 126broad browser support but it does require cooperation of the backend server. An 127`app-location` can be configured to use the hash part of a URL instead using 128the `use-hash-as-path` attribute, like so: 129 130```html 131<app-location route="{{route}}" use-hash-as-path></app-location> 132``` 133 134### Integrating with other routing code 135 136There is no standard event that is fired when window.location is modified. 137`app-location` fires a `location-changed` event on `window` when it updates the 138location. It also listens for that same event, and re-reads the URL when it's 139fired. This makes it very easy to interop with other routing code. 140 141So for example if you want to navigate to `/new_path` imperatively you could 142call `window.location.pushState` or `window.location.replaceState` followed by 143firing a `location-changed` event on `window`. i.e. 144 145```javascript 146window.history.pushState({}, null, '/new_path'); 147window.dispatchEvent(new CustomEvent('location-changed')); 148``` 149 150 151 152## <app-route-converter> 153 154`app-route-converter` provides a means to convert a path and query 155parameters into a route object and vice versa. This produced route object 156is to be fed into route-consuming elements such as `app-route`. 157 158> n.b. This element is intended to be a primitive of the routing system and for 159creating bespoke routing solutions from scratch. To simply include routing in 160an app, please refer to [app-location](https://github.com/PolymerElements/app-route/blob/master/app-location.html) 161and [app-route](https://github.com/PolymerElements/app-route/blob/master/app-route.html). 162 163An example of a route object that describes 164`https://elements.polymer-project.org/elements/app-route-converter?foo=bar&baz=qux` 165and should be passed to other `app-route` elements: 166 167```css 168{ 169 prefix: '', 170 path: '/elements/app-route-converter', 171 __queryParams: { 172 foo: 'bar', 173 baz: 'qux' 174 } 175} 176``` 177 178`__queryParams` is private to discourage directly data-binding to it. This is so 179that routing elements like `app-route` can intermediate changes to the query 180params and choose whether to propagate them upstream or not. `app-route` for 181example will not propagate changes to its `queryParams` property if it is not 182currently active. A public queryParams object will also be produced in which you 183should perform data-binding operations. 184 185Example Usage: 186 187```html 188<iron-location path="{{path}}" query="{{query}}"></iron-location> 189<iron-query-params 190 params-string="{{query}}" 191 params-object="{{queryParams}}"> 192</iron-query-params> 193<app-route-converter 194 path="{{path}}" 195 query-params="{{queryParams}}" 196 route="{{route}}"> 197</app-route-converter> 198<app-route route='{{route}}' pattern='/:page' data='{{data}}'> 199</app-route> 200``` 201 202This is a simplified implementation of the `app-location` element. Here the 203`iron-location` produces a path and a query, the `iron-query-params` consumes 204the query and produces a queryParams object, and the `app-route-converter` 205consumes the path and the query params and converts it into a route which is in 206turn is consumed by the `app-route`. 207 208 209 210## Polymer.AppRouteConverterBehavior 211 212Provides bidirectional mapping between `path` and `queryParams` and a 213app-route compatible `route` object. 214 215For more information, see the docs for `app-route-converter`. 216 217 218
){kind=link}