third_party/polymer/v1_0/components/more-routing/README.md

   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 existing 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 with... 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-crawling/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`.