From c7f58ee459fb24fcc859347fe308c571bd9c9ce3 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Sun, 17 Jan 2016 15:02:15 -0800 Subject: [PATCH] docs(router): incorporate Brian's comments; other fixes closes #712 --- public/docs/_examples/router/ts/index.html | 7 +++++++ public/docs/ts/latest/guide/router.jade | 22 +++++++++++--------- tools/plunker-builder/indexHtmlTranslator.js | 10 +++++++++ 3 files changed, 29 insertions(+), 10 deletions(-) diff --git a/public/docs/_examples/router/ts/index.html b/public/docs/_examples/router/ts/index.html index 95b99057c0..ea2d3a7224 100644 --- a/public/docs/_examples/router/ts/index.html +++ b/public/docs/_examples/router/ts/index.html @@ -9,6 +9,13 @@ Router Sample + + + + + + + diff --git a/public/docs/ts/latest/guide/router.jade b/public/docs/ts/latest/guide/router.jade index 10a8bf85ac..95727f46bb 100644 --- a/public/docs/ts/latest/guide/router.jade +++ b/public/docs/ts/latest/guide/router.jade @@ -10,7 +10,7 @@ include ../../../../_includes/_util-fns We click the browser's back and forward buttons and the browser navigates backward and forward through the history of pages we've seen. - The Angular "**Component Router**" (AKA "the router") borrows from this model. + The Angular "**Component Router**" ("the router") borrows from this model. It can interpret a browser URL as an instruction to navigate to a client-generated view and pass optional parameters along to the supporting view component to help it decide what specific content to present. @@ -70,9 +70,9 @@ include ../../../../_includes/_util-fns When the browser's URL changes, the router looks for a corresponding **`RouteDefinition`** from which it can determine the component to display. - A new router has no route definitions. We have to configure it. - The preferred way to configure the router is with a **`@RouteConfig`** [decorator](glossary.html#decorator) - applied to a host component. + A router has no route definitions until we configure it. + The preferred way to simultaneously create a router and add its routes is with a **`@RouteConfig`** [decorator](glossary.html#decorator) + applied to the router's host component. In this example, we configure the top-level `AppComponent` with three route definitions +makeExample('router/ts/app/app.component.2.ts', 'route-config', 'app.component.ts (excerpt)')(format=".") @@ -83,7 +83,8 @@ include ../../../../_includes/_util-fns There are several flavors of `RouteDefinition`. The most common by far is the named **`Route`** which maps a URL path to a component - The `name` field is the name of the `Route`. The name **must** be spelled in **PascalCase**. + The `name` field is the route name which **must** be spelled in **PascalCase** + to avoid potential confusion with the route `path`. The `:id` in the third route is a token for a route parameter. In a URL such as `/hero/42`, "42" is the value of the `id` parameter. The corresponding `HeroDetailComponent` @@ -268,7 +269,8 @@ figure.image-display ### Load the Component Router library The Component Router is not part of the Angular 2 core. It is in its own library. - The router is an optional service and you might prefer a different router someday. + The router is an optional service because not all applications need routing and, + depending on your requirements, you may need a different routing library. The Component Router library is part of the Angular npm bundle. We make it available by loading its script in our `index.html`, right after @@ -287,9 +289,9 @@ figure.image-display "HTML 5 style" URLs. We must **add a [<base href> element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag** - to the `index.html` to make this work. - The `href` value specifies the base URL to use for all *relative* URLs within a document including - links to css files, scripts, and images. + to the `index.html` to make `pushState` routing work. + The browser also needs the base `href` value to prefix *relative* URLs when downloading and linking to + css files, scripts, and image. Add the base element just after the `` tag. If the `app` folder is the application root, as it is for our application, @@ -817,7 +819,7 @@ code-example(format=""). :marked Notice that the **path ends with a slash and three trailing periods (`/...`)**. - That means this is an incomplete route (AKA a ***non-terminal route***). The finished route will be some combination of + That means this is an incomplete route (a ***non-terminal route***). The finished route will be some combination of the parent `/crisis-center/` route and a route from the **child router** that belongs to the designated component. All is well. diff --git a/tools/plunker-builder/indexHtmlTranslator.js b/tools/plunker-builder/indexHtmlTranslator.js index c7c0d94a61..688e7d0589 100644 --- a/tools/plunker-builder/indexHtmlTranslator.js +++ b/tools/plunker-builder/indexHtmlTranslator.js @@ -78,6 +78,16 @@ var _rxData = [ from: 'node_modules/angular2/bundles/testing.dev.js', to: 'https://code.angularjs.org/2.0.0-beta.0/testing.dev.js' }, + { + pattern: 'script', + from: 'node_modules/es6-shim/es6-shim.min.js', + to: 'https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.33.3/es6-shim.min.js' + }, + { + pattern: 'script', + from: 'node_modules/systemjs/distsystem-polyfills.js', + to: 'https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.16/system-polyfills.js' + }, { pattern: 'link', from: 'node_modules/bootstrap/dist/css/bootstrap.min.css',