| OLD | NEW |
|---|
| (Empty) |
| 1 Routing | |
| 2 ======= | |
| 3 | |
| 4 A composable suite of objects and elements to make routing with web components | |
| 5 a breeze. | |
| 6 | |
| 7 * [Hash-](#MoreRouting.HashDriver) and [path-](#MoreRouting.PathDriver)based | |
| 8 routing. | |
| 9 * [Named routes](#more-routing). | |
| 10 * [Nested (mounted) routes](#more-route--nesting). | |
| 11 * [Declarative route switching](#more-route-switch). | |
| 12 * [Polymer helpers](#polymer-helpers--filters) for easy integration into existin
g elements. | |
| 13 | |
| 14 [Rob Dodson](https://github.com/robdodson) has whipped up a great video | |
| 15 that can get you started with more-routing: | |
| 16 | |
| 17 <p align="center"> | |
| 18 <a href="https://www.youtube.com/watch?v=-67kb7poIT8"> | |
| 19 <img src="http://img.youtube.com/vi/-67kb7poIT8/0.jpg" alt="Moar routing wit
h... more-routing"> | |
| 20 </a> | |
| 21 </p> | |
| 22 | |
| 23 Or, TL;DR: | |
| 24 | |
| 25 ```html | |
| 26 <link rel="import" href="../more-routing/more-routing.html"> | |
| 27 | |
| 28 <more-routing-config driver="path"></more-routing-config> | |
| 29 <more-route name="user" path="/users/:userId"> | |
| 30 <more-route name="user-bio" path="/bio"></more-route> | |
| 31 </more-route> | |
| 32 | |
| 33 <more-route-selector selectedParams="{{params}}"> | |
| 34 <core-pages> | |
| 35 <section route="/"> | |
| 36 This is the index. | |
| 37 </section> | |
| 38 | |
| 39 <section route="/about"> | |
| 40 It's a routing demo! | |
| 41 <a href="{{ urlFor('user-bio', {userId: 1}) }}">Read about user 1</a>. | |
| 42 </section> | |
| 43 | |
| 44 <section route="user"> | |
| 45 <header>Heyo user {{params.userId}}!</header> | |
| 46 <template if="{{ route('user-bio').active }}"> | |
| 47 All the details about {{params.userId}} that you didn't want to know... | |
| 48 </template> | |
| 49 </section> | |
| 50 </core-pages> | |
| 51 </more-route-selector> | |
| 52 ``` | |
| 53 | |
| 54 And finally, check out [the demo](demo/) for a project that makes comprehensive | |
| 55 use of the various features in more-routing. | |
| 56 | |
| 57 | |
| 58 Element API | |
| 59 =========== | |
| 60 | |
| 61 <a name="more-routing-config"></a> | |
| 62 `<more-routing-config>` | |
| 63 ---------------- | |
| 64 | |
| 65 _Defined in [`more-routing-config.html`](more-routing-config.html)._ | |
| 66 | |
| 67 The declarative interface for configuring [`MoreRouting`](#MoreRouting). | |
| 68 Currently, this lets you declare which [driver](#MoreRouting.Driver) you wish | |
| 69 to use (`hash` or `path`): | |
| 70 | |
| 71 ```html | |
| 72 <more-routing-config driver="hash"></more-routing-config> | |
| 73 ``` | |
| 74 | |
| 75 You should place this as early in the load process for your app as you can. Any | |
| 76 routes defined prior to the driver being set will trigger an error. | |
| 77 | |
| 78 | |
| 79 <a name="more-route"></a> | |
| 80 `<more-route>` | |
| 81 -------------- | |
| 82 | |
| 83 _Defined in [`more-route.html`](more-route.html)._ | |
| 84 | |
| 85 Reference routes by path, and extract their params: | |
| 86 | |
| 87 ```html | |
| 88 <more-route path="/users/:userId" params="{{user}}"></more-route> | |
| 89 ``` | |
| 90 | |
| 91 Declare a named route: | |
| 92 | |
| 93 ```html | |
| 94 <more-route path="/users/:userId" name="user"></more-route> | |
| 95 ``` | |
| 96 | |
| 97 Reference a named route: | |
| 98 | |
| 99 ```html | |
| 100 <more-route name="user" params="{{user}}"></more-route> | |
| 101 ``` | |
| 102 | |
| 103 | |
| 104 <a name="more-route--nesting"></a> | |
| 105 ### Route Nesting | |
| 106 | |
| 107 Routes can also be nested: | |
| 108 | |
| 109 ```html | |
| 110 <more-route path="/users/:userId" name="user"> | |
| 111 <more-route path="/bio" name="user-bio"></more-route> | |
| 112 </more-route> | |
| 113 ``` | |
| 114 | |
| 115 In this example, the route named `user-bio` will match `/users/:userId/bio`. | |
| 116 | |
| 117 Finally, `<more-route>` elements can declare a routing context for the element | |
| 118 that contains them by setting the `context` attribute. See the | |
| 119 [routed elements](#more-route-selector--routed-elements) section for more info. | |
| 120 | |
| 121 | |
| 122 <a name="more-route-selector"></a> | |
| 123 `<more-route-selector>` | |
| 124 ----------------------- | |
| 125 | |
| 126 _Defined in [`more-route-selector.html`](more-route-selector.html)._ | |
| 127 | |
| 128 Manages a [`<core-selector>`](https://www.polymer-project.org/docs/elements/core
-elements.html#core-selector) | |
| 129 (or anything that extends it/looks like one), where each item in the selector | |
| 130 have an associated route. The most specific route that is active will be | |
| 131 selected. | |
| 132 | |
| 133 ```html | |
| 134 <more-route-selector> | |
| 135 <core-pages> | |
| 136 <section route="/">The index!</section> | |
| 137 <section route="user">A user (named route)</section> | |
| 138 <section route="/about">Another route</section> | |
| 139 </core-pages> | |
| 140 </more-route-selector> | |
| 141 ``` | |
| 142 | |
| 143 By default, `more-route-selector` will look for the `route` attribute on any | |
| 144 children of the `core-selector` (change this via `routeAttribute`). | |
| 145 | |
| 146 It exposes information about the selected route via a few properties: | |
| 147 | |
| 148 `selectedParams`: The params of the selected route. | |
| 149 | |
| 150 `selectedRoute`: The [`MoreRouting.Route`](#MoreRouting.Route) representing the | |
| 151 selected route. | |
| 152 | |
| 153 `selectedPath`: The path expression of the selected route. | |
| 154 | |
| 155 `selectedIndex`: The index of the selected route (relative to `routes`). | |
| 156 | |
| 157 | |
| 158 <a name="more-route-selector--routed-elements"></a> | |
| 159 ### Routed Elements | |
| 160 | |
| 161 Elements can declare a route to be associated with, which allows | |
| 162 `<more-route-selector>` to be smart and use that as the route it checks against | |
| 163 for your element. For example: | |
| 164 | |
| 165 ```html | |
| 166 <polymer-element name="routed-element"> | |
| 167 <template> | |
| 168 <more-route path="/my/route" context></more-route> | |
| 169 I'm a routed element! | |
| 170 </template> | |
| 171 </polymer-element> | |
| 172 ``` | |
| 173 | |
| 174 ```html | |
| 175 <more-route-selector> | |
| 176 <core-pages> | |
| 177 <section route="/">The index!</section> | |
| 178 <routed-element></routed-element> | |
| 179 </core-pages> | |
| 180 </more-route-selector> | |
| 181 ``` | |
| 182 | |
| 183 In this example, The `<more-route-selector>` will choose `<routed-element>` | |
| 184 whenever the path begins with `/my/route`. Keep it DRY! | |
| 185 | |
| 186 | |
| 187 <a name="more-route-selector--nesting-contexts"></a> | |
| 188 ### Nesting Contexts | |
| 189 | |
| 190 Similar to [`more-route`'s nesting behavior](#more-route--nesting), any items in | |
| 191 the core-selector also behave as nesting contexts. Any route declared within a | |
| 192 routing context is effectively _mounted_ on the context route. | |
| 193 | |
| 194 Taking the example element, `<routed-element>` above; if we were to add the | |
| 195 following to its template: | |
| 196 | |
| 197 ```html | |
| 198 <more-route path="/:tab" params="{{params}}"></more-route> | |
| 199 ``` | |
| 200 | |
| 201 That route's full path would be `/my/route/:tab`, because `/my/route` is the | |
| 202 context in which it is nested. This allows you to create custom elements that | |
| 203 make use of routes, _while not requiring knowledge of the app's route | |
| 204 hierarchy_. Very handy for composable components! | |
| 205 | |
| 206 **Note:** All items in a `<more-route-selector>` are treated as routing | |
| 207 contexts! | |
| 208 | |
| 209 | |
| 210 <a name="polymer-helpers"></a> | |
| 211 Polymer Helpers | |
| 212 --------------- | |
| 213 | |
| 214 <a name="polymer-helpers--filters"></a> | |
| 215 ### Filters | |
| 216 | |
| 217 _Defined in [`polymer-expressions.html`](polymer-expressions.html)._ | |
| 218 | |
| 219 Several filters (functions) are exposed to templates for your convenience: | |
| 220 | |
| 221 #### `route` | |
| 222 | |
| 223 You can fetch a `MoreRouting.Route` object via the `route` filter. Handy for | |
| 224 reading params, etc on the fly. | |
| 225 | |
| 226 ```html | |
| 227 <x-user model="{{ route('user').params }}"></x-user> | |
| 228 ``` | |
| 229 | |
| 230 **Note:** The `route()` helper is unfortunately _not_ aware of the current | |
| 231 routing context. Consider using only named routes to avoid confusion! | |
| 232 | |
| 233 #### `urlFor` | |
| 234 | |
| 235 Generates a URL for the specified route and params: | |
| 236 | |
| 237 ```html | |
| 238 <a href="{{ urlFor('user', {userId: 1}) }}">User 1</a> | |
| 239 ``` | |
| 240 | |
| 241 | |
| 242 JavaScript API | |
| 243 ============== | |
| 244 | |
| 245 <a name="MoreRouting"></a> | |
| 246 `MoreRouting` | |
| 247 ------------- | |
| 248 | |
| 249 _Defined in [`routing.html`](routing.html)._ | |
| 250 | |
| 251 The main entry point into `more-routing`, exposed as a global JavaScript | |
| 252 namespace of `MoreRouting`. For the most part, all elements and helpers are | |
| 253 built on top of it. | |
| 254 | |
| 255 `MoreRouting` manages the current [driver](#MoreRouting.Driver), and maintains | |
| 256 an identity map of all routes. | |
| 257 | |
| 258 | |
| 259 <a name="MoreRouting.driver"></a> | |
| 260 ### `MoreRouting.driver` | |
| 261 | |
| 262 Before you can make use of navigation and URL parsing, a driver must be | |
| 263 registered. Simply assign an instance of `MoreRouting.Driver` to this property. | |
| 264 | |
| 265 This is exposed as a declarative element via | |
| 266 [`<more-routing-config driver="...">`](#more-routing). | |
| 267 | |
| 268 | |
| 269 <a name="MoreRouting.getRoute"></a> | |
| 270 ### `MoreRouting.getRoute` | |
| 271 | |
| 272 Returns a [`MoreRouting.Route`](#MoreRouting.Route), by path... | |
| 273 | |
| 274 MoreRouting.getRoute('/users/:userId') | |
| 275 | |
| 276 ...or by name: | |
| 277 | |
| 278 MoreRouting.getRoute('user') | |
| 279 | |
| 280 Because routes are identity mapped, `getRoute` guarantees that it will return | |
| 281 the same `Route` object for the same path. | |
| 282 | |
| 283 | |
| 284 <a name="MoreRouting.Route"></a> | |
| 285 `MoreRouting.Route` | |
| 286 ------------------- | |
| 287 | |
| 288 _Defined in [`route.html`](route.html)._ | |
| 289 | |
| 290 The embodiment for an individual route. It has various handy properties. | |
| 291 Highlights: | |
| 292 | |
| 293 ``active``: Whether the route is active (the current URL matches). | |
| 294 | |
| 295 ``params``: A map of param keys to their values (matching the `:named` tokens) | |
| 296 within the path. | |
| 297 | |
| 298 ``path``: The path expression that this route matches. | |
| 299 | |
| 300 ### Paths | |
| 301 | |
| 302 Path expressions begin with a `/` (to disambiguate them from route names), and | |
| 303 are a series of tokens separated by `/`. | |
| 304 | |
| 305 Tokens can be of the form `:named`, where they named a parameter. Or they can | |
| 306 be regular strings, at which point they are static path parts. | |
| 307 | |
| 308 Should be familiar from many other routing systems. | |
| 309 | |
| 310 | |
| 311 <a href="MoreRouting.Driver"></a> | |
| 312 `MoreRouting.Driver` | |
| 313 -------------------- | |
| 314 | |
| 315 _Defined in [`driver.html`](driver.html)._ | |
| 316 | |
| 317 Drivers manage how the URL is read, and how to navigate to URLs. There are two | |
| 318 built in drivers: | |
| 319 | |
| 320 | |
| 321 <a href="MoreRouting.HashDriver"></a> | |
| 322 ### `MoreRouting.HashDriver` | |
| 323 | |
| 324 _Defined in [`hash-driver.html`](hash-driver.html)._ | |
| 325 | |
| 326 Provides hash-based routing, generating URLs like `#!/users/1/bio`. It has a | |
| 327 configurable prefix (after the `#`). By default, it uses a prefix of `!/` | |
| 328 (to fit the [AJAX-crawling spec](https://developers.google.com/webmasters/ajax-c
rawling/docs/specification)). | |
| 329 | |
| 330 | |
| 331 <a href="MoreRouting.PathDriver"></a> | |
| 332 ### `MoreRouting.PathDriver` | |
| 333 | |
| 334 _Defined in [`path-driver.html`](path-driver.html)._ | |
| 335 | |
| 336 Provides true path-based routing (via `pushState`), generating URLs like | |
| 337 `/users/1/bio`. If your web app is mounted on a path other than `/`, you can | |
| 338 specify that mount point via the `prefix`. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1269803005:
Remove third_party/polymer from .gitignore (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master