polymer_0.5.4/bower_components/app-router/README.md - Issue 897763002: Updated app-router to 2.4.0

Unified Diff: polymer_0.5.4/bower_components/app-router/README.md

Issue 897763002: Updated app-router to 2.4.0 (Closed) Base URL: https://chromium.googlesource.com/infra/third_party/npm_modules.git@master

Patch Set: Created 5 years, 11 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

« no previous file with comments | « polymer_0.5.4/bower_components/app-router/LICENSE.md ('k') | polymer_0.5.4/bower_components/app-router/app-router.html » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

Index: polymer_0.5.4/bower_components/app-router/README.md

diff --git a/polymer_0.5.4/bower_components/app-router/README.md b/polymer_0.5.4/bower_components/app-router/README.md

index bb020ff07e6b1fa669874ed9a134c8fb27903b6c..2c3e7575ba595237d3eb3da69d969472542a366d 100644

--- a/polymer_0.5.4/bower_components/app-router/README.md

+++ b/polymer_0.5.4/bower_components/app-router/README.md

@@ -1,14 +1,16 @@

## Router for Web Components

-> Works with [Polymer](http://www.polymer-project.org/), [X-Tag](http://www.x-tags.org/), and natively with the [platform](https://github.com/Polymer/platform) polyfill.

+> Works with [Polymer](http://www.polymer-project.org/), [X-Tag](http://www.x-tags.org/), and natively.

+> [erikringsmuth.github.io/app-router](https://erikringsmuth.github.io/app-router/)

-> [erikringsmuth.github.io/app-router](http://erikringsmuth.github.io/app-router)

-Lazy-loads content. Binds path variables and query parameters to the page element's attributes. Supports multiple layouts. Works with `hashchange` and HTML5 `pushState`. One set of routes will match regular paths `/`, hash paths `#/`, and hashbang paths `#!/`.

+Manage page state. Lazy-load content. Data-bind path variables and query parameters. Use multiple layouts. Navigate with `hashchange` and HTML5 `pushState`. Animate transitions using `core-animated-pages`.

[Download](https://github.com/erikringsmuth/app-router/archive/master.zip) or run `bower install app-router --save`.

## Configuration

+Define how URLs map to pages.

```html

<!doctype html>

<html>

@@ -37,75 +39,92 @@ Lazy-loads content. Binds path variables and query parameters to the page elemen

</html>

```

-Changing the URL will find the first `app-route` that matches, load the element or template, and replace the current view.

+## Navigation

-## Data Binding

-Path variables and query parameters automatically attach to the element's attributes.

+Click links or call `router.go()`.

-``` html

-

-http://www.example.com/order/123?sort=ascending

+```html

+

+<a href="/#/home">Home</a>

-

-<app-route path="/order/:id" import="/pages/order-page.html"></app-route>

+

+<a is="pushstate-anchor" href="/home">Home</a>

+

+<script>

+ document.querySelector('app-router').go('/home');

+</script>

+```

+The router listens to `popstate` and `hashchange` events. Changing the URL will find the first `app-route` that matches, load the element or template, and replace the current view.

+#### hashchange

+Clicking `<a href="/#/home">Home</a>` will fire a `hashchange` event and tell the router to load the first route that matches `/home`. You don't need to handle the event in your Javascript. Hash paths `/#/home` match routes without the hash `<app-route path="/home">`.

+#### pushState

+You can use the [pushstate-anchor](https://github.com/erikringsmuth/pushstate-anchor) or [html5-history-anchor](https://github.com/erikringsmuth/html5-history-anchor) to extend `<a>` tags with the HTML5 history API.

-

-<order-page id="123" sort="ascending"></order-page>

+```html

+<a is="pushstate-anchor" href="/home">Home</a>

```

-See it in action [here](http://erikringsmuth.github.io/app-router/#/databinding/1337?queryParam1=Routing%20with%20Web%20Components!).

+This will call `pushState()` and dispatch a `popstate` event.

-## Multiple Layouts

-Each page chooses which layout to use. This allows multiple layouts in the same app. Use `<content>` tag insertion points to insert the page into the layout. This is similar to nested routes but completely decouples the page layout from the router.

+#### go(path, options)

+You can call the router from Javascript to navigate imperatively.

-This is a simple example showing a page and it's layout.

+```js

+document.querySelector('app-router').go('/home');

+// or

+document.querySelector('app-router').go('/home', {replace: true});

+```

-#### home-page.html

+If you use `go(path, options)` you should also set the mode to `hash` or `pushstate` on the router.

```html

-<link rel="import" href="/layouts/simple-layout.html">

-<polymer-element name="home-page" noscript>

- <template>

- <simple-layout>

- <div class="title">Home</div>

- <p>The home page!</p>

- </simple-layout>

- </template>

-</polymer-element>

+<app-router mode="auto|pushstate|hash">

+

+</app-router>

```

-#### simple-layout.html

+## Data Binding

+Path variables and query parameters automatically attach to the element's attributes.

+``` html

+

+<a is="pushstate-anchor" href="/order/123?sort=ascending">Order 123</a>

+

+<app-route path="/order/:orderId" import="/pages/order-page.html"></app-route>

+

+<order-page orderId="123" sort="ascending"></order-page>

+```

+If you're using Polymer, you can also bind path variables and query parameters to templates.

```html

-<polymer-element name="simple-layout" noscript>

+<app-route path="/order/:orderId">

- <core-toolbar>

- <content select=".title"></content>

- </core-toolbar>

- <content></content>

+ <p>Your order number is {{orderId}}</p>

</template>

-</polymer-element>

+</app-route>

```

+See it in action [here](https://erikringsmuth.github.io/app-router/#/databinding/1337?queryParam1=Routing%20with%20Web%20Components!).

## <app-route> options

#### import a custom element

Lazy-load a custom element.

```html

-<app-route path="/customer/:customerId" import="/pages/customer-page.html"></app-route>

+<app-route path="/customer/:customerId" import="/pages/customer-page.html" [element="customer-page"]></app-route>

```

-When you navigate to `/customer/123` the router will load `/pages/customer-page.html`, replace the active view with a new `customer-page` element, and bind any attributes `element.setAttribute('customerId', 123)`.

-You can manually set the element's name with the `element` attribute if it's different from the file name. This is useful when bundling (vulcanizing) custom elements.

-```html

-<app-route path="/customer/:customerId" import="/pages/page-bundle.html" element="customer-page"></app-route>

-```

+You only need to set the `element` attribute if the element's name is different than the file name.

#### pre-loaded custom element

-You can route to a pre-loaded custom element. In this case, load the element normally in the `<head>` and include the `element="element-name"` attribute on the route. This is how you'd bundle and pre-load custom elements.

+Include the `element="element-name"` attribute on the route to use a pre-loaded custom element. This is how you use bundled (vulcanized) custom elements.

```html

<head>

@@ -117,7 +136,7 @@ You can route to a pre-loaded custom element. In this case, load the element nor

```

#### import template

-You can use a `<template>` instead of a custom element. This doesn't have data binding and is lighter-weight than a custom element. Just include the `template` attribute.

+You can import a `<template>` instead of a custom element. Just include the `template` attribute.

```html

<app-route path="/example" import="/pages/template-page.html" template></app-route>

@@ -127,7 +146,7 @@ You can use a `<template>` instead of a custom element. This doesn't have data b

Finally, you can in-line a `<template>` like this.

```html

-<app-route path="/example" template>

+<app-route path="/example">

<p>Inline template FTW!</p>

</template>

@@ -136,45 +155,56 @@ Finally, you can in-line a `<template>` like this.

#### regular expressions

Include the `regex` attribute to match on a regular expression. The format is the same as a JavaScript regular expression.

```html

<app-route path="/^\/\w+\/\d+$/i" regex import="/pages/regex-page.html"></app-route>

```

-Note: The regular expression must start with a `/` and end with a `/` optionally followed by `i`. Options global `g`, multiline `m`, and sticky `y` aren't valid when matching paths.

-## <app-router> options

+#### redirect

+A route can redirect to another path.

-#### Trailing Slashes

-By default `/home` and `/home/` are treated as separate routes. You can configure the router to ignore trailing slashes with `trailingSlash="ignore"`.

```html

-<app-router trailingSlash="ignore">

-

+<app-router mode="pushstate">

<app-route path="/home" import="/pages/home-page.html"></app-route>

+ <app-route path="*" redirect="/home"></app-route>

</app-router>

```

-## Navigation

-There are three ways change the active route. `hashchange`, `pushState()`, and a full page load.

+When you use `redirect` you should also set `mode="hash|pushstate"` on the `app-router`.

-#### hashchange

-If you're using `hashchange` you don't need to do anything. Clicking a link `<a href="/#/new/page">New Page</a>` will fire a `hashchange` event and tell the router to load the new route. You don't need to handle the event in your code.

+## <app-router> options

-#### pushState

-If you're using HTML5 `pushState` you need one extra step. The `pushState()` method was not meant to change the page, it was only meant to push state into history. This is an "undo" feature for single page applications. To use `pushState()` to navigate to another route you need to call it like this.

+#### mode

+One set of routes will match regular paths `/` and hash paths `#/`. You can force a specific mode with `mode="auto|hash|pushstate"`.

-```js

-history.pushState(stateObj, title, '/new/page'); // push a new URL into the history stack

-history.go(0); // go to the current state in the history stack, this fires a popstate event

+```html

+<app-router mode="pushstate">

+

+</app-router>

```

-#### Full page load

-Clicking a link `<a href="/new/page">New Page</a>` without a hash path will do a full page load. You need to make sure your server will return `index.html` when looking up the resource at `/new/page`. The simplest set up is to always return `index.html` and let the `app-router` handle the routing including a not found page.

+When left in `auto`, redirects and `go(path, options)` will use hash paths.

+#### trailing slashes

+By default `/home` and `/home/` are treated as separate routes. You can configure the router to ignore trailing slashes with `trailingSlash="ignore"`.

+```html

+<app-router trailingSlash="ignore">

+

+ <app-route path="/home" import="/pages/home-page.html"></app-route>

+</app-router>

+```

## Demo Site & Example Setup

-Check out the `app-router` in action at [erikringsmuth.github.io/app-router](http://erikringsmuth.github.io/app-router).

+Check out the `app-router` in action at [erikringsmuth.github.io/app-router](https://erikringsmuth.github.io/app-router/).

You can download an example setup here https://github.com/erikringsmuth/app-router-examples to get running locally.

+Examples showing `app-router` and `flatiron-director` versus no router https://github.com/erikringsmuth/polymer-router-demos.

+## Breaking Changes

+Check the [change log](https://github.com/erikringsmuth/app-router/blob/master/changelog.md) for breaking changes in major versions.

## Build, Test, and Debug [![Build Status](https://travis-ci.org/erikringsmuth/app-router.png?branch=master)](https://travis-ci.org/erikringsmuth/app-router)

Source files are under the `src` folder. The build process writes to the root directory. The easiest way to debug is to include the source script rather than the minified HTML import.

```html

@@ -183,7 +213,5 @@ Source files are under the `src` folder. The build process writes to the root di

To build:

- Run `bower install` and `npm install` to install dev dependencies

-- Lint, build, and minify code changes with `gulp` (watch with `gulp watch`)

-- Start a static content server to run tests (node `http-server` or `python -m SimpleHTTPServer`)

-- Run unit tests in the browser (PhantomJS doesn't support Web Components) [http://localhost:8080/tests/SpecRunner.html](http://localhost:8080/tests/SpecRunner.html)

-- Manually run functional tests in the browser [http://localhost:8080/tests/functional-test-site/](http://localhost:8080/tests/functional-test-site/)

+- Lint, test, build, and minify code with `gulp`

+- Manually run functional tests in the browser by starting a static content server (node `http-server` or `python -m SimpleHTTPServer`) and open [http://localhost:8080/tests/functional-tests/](http://localhost:8080/tests/functional-tests/)

« no previous file with comments | « polymer_0.5.4/bower_components/app-router/LICENSE.md ('k') | polymer_0.5.4/bower_components/app-router/app-router.html » ('j') | no next file with comments »