From 4127c8c8d1f14cf80591ee8cfb1034d2d3772aee Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Sun, 17 Jan 2016 15:02:15 -0800 Subject: [PATCH 1/2] docs(router): update for IE and incorporate Brian's comments --- 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', From ec69c72174fe5c3799de199e34e11be97a478048 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Sun, 17 Jan 2016 19:59:34 -0800 Subject: [PATCH 2/2] docs: add IE polyfills to all samples; update QS and Router to explain --- .../ts/app/sales-tax.component.ts | 2 +- .../docs/_examples/architecture/ts/index.html | 4 ++ .../attribute-directives/ts/index.html | 4 ++ .../_examples/displaying-data/ts/index.1.html | 16 ++++++- .../_examples/displaying-data/ts/index.html | 4 ++ public/docs/_examples/forms/ts/index.html | 4 ++ .../ts/index.html | 4 ++ .../homepage-hello-world/ts/src/index.html | 4 ++ .../_examples/homepage-tabs/ts/src/index.html | 4 ++ .../_examples/homepage-todo/ts/src/index.html | 4 ++ .../_examples/lifecycle-hooks/ts/index.html | 4 ++ public/docs/_examples/pipes/ts/index.html | 4 ++ .../docs/_examples/quickstart/ts/index.html | 8 +++- public/docs/_examples/router/ts/index.1.html | 6 +++ public/docs/_examples/router/ts/index.html | 4 +- .../structural-directives/ts/index.html | 4 ++ .../docs/_examples/styleguide/ts/index.html | 4 ++ .../_examples/template-syntax/ts/index.html | 5 ++ public/docs/_examples/toh-1/ts/index.html | 4 ++ public/docs/_examples/toh-2/ts/index.html | 4 ++ public/docs/_examples/toh-3/ts/index.html | 4 ++ public/docs/_examples/toh-4/ts/index.html | 4 ++ public/docs/_examples/tutorial/ts/index.html | 4 ++ .../docs/_examples/user-input/ts/index.html | 5 ++ public/docs/ts/latest/guide/router.jade | 19 +++++++- public/docs/ts/latest/quickstart.jade | 47 ++++++++++++------- tools/plunker-builder/indexHtmlTranslator.js | 2 +- 27 files changed, 158 insertions(+), 24 deletions(-) diff --git a/public/docs/_examples/architecture/ts/app/sales-tax.component.ts b/public/docs/_examples/architecture/ts/app/sales-tax.component.ts index 9e31100f57..475725a0e4 100644 --- a/public/docs/_examples/architecture/ts/app/sales-tax.component.ts +++ b/public/docs/_examples/architecture/ts/app/sales-tax.component.ts @@ -13,7 +13,7 @@ import {TaxRateService} from './tax-rate.service';

Sales Tax Calculator

Amount: -
+
The sales tax is {{ getTax(amountBox.value) | currency:'USD':true:'1.2-2' }}
diff --git a/public/docs/_examples/architecture/ts/index.html b/public/docs/_examples/architecture/ts/index.html index 9d2b59a69b..a562ab4c8a 100644 --- a/public/docs/_examples/architecture/ts/index.html +++ b/public/docs/_examples/architecture/ts/index.html @@ -2,6 +2,10 @@ Intro to Angular 2 + + + + diff --git a/public/docs/_examples/attribute-directives/ts/index.html b/public/docs/_examples/attribute-directives/ts/index.html index fc4454c853..ab1f9adcb4 100644 --- a/public/docs/_examples/attribute-directives/ts/index.html +++ b/public/docs/_examples/attribute-directives/ts/index.html @@ -4,6 +4,10 @@ Attribute Directives + + + + diff --git a/public/docs/_examples/displaying-data/ts/index.1.html b/public/docs/_examples/displaying-data/ts/index.1.html index b76c23e201..4db780010b 100644 --- a/public/docs/_examples/displaying-data/ts/index.1.html +++ b/public/docs/_examples/displaying-data/ts/index.1.html @@ -3,13 +3,25 @@ Displaying Data + + + + + + diff --git a/public/docs/_examples/displaying-data/ts/index.html b/public/docs/_examples/displaying-data/ts/index.html index 8e285be135..5cad659faa 100644 --- a/public/docs/_examples/displaying-data/ts/index.html +++ b/public/docs/_examples/displaying-data/ts/index.html @@ -3,6 +3,10 @@ Displaying Data + + + + diff --git a/public/docs/_examples/forms/ts/index.html b/public/docs/_examples/forms/ts/index.html index 397642c822..2556433619 100644 --- a/public/docs/_examples/forms/ts/index.html +++ b/public/docs/_examples/forms/ts/index.html @@ -10,6 +10,10 @@ + + + + diff --git a/public/docs/_examples/hierarchical-dependency-injection/ts/index.html b/public/docs/_examples/hierarchical-dependency-injection/ts/index.html index da5633055c..f4b7bad028 100644 --- a/public/docs/_examples/hierarchical-dependency-injection/ts/index.html +++ b/public/docs/_examples/hierarchical-dependency-injection/ts/index.html @@ -3,6 +3,10 @@ Hierarchical Injectors + + + + diff --git a/public/docs/_examples/homepage-hello-world/ts/src/index.html b/public/docs/_examples/homepage-hello-world/ts/src/index.html index 4cc1046bce..7a3e40fa88 100644 --- a/public/docs/_examples/homepage-hello-world/ts/src/index.html +++ b/public/docs/_examples/homepage-hello-world/ts/src/index.html @@ -6,6 +6,10 @@ Angular 2 QuickStart + + + + diff --git a/public/docs/_examples/homepage-tabs/ts/src/index.html b/public/docs/_examples/homepage-tabs/ts/src/index.html index 9a6dc3fd0d..43cae53996 100644 --- a/public/docs/_examples/homepage-tabs/ts/src/index.html +++ b/public/docs/_examples/homepage-tabs/ts/src/index.html @@ -7,6 +7,10 @@ + + + + diff --git a/public/docs/_examples/homepage-todo/ts/src/index.html b/public/docs/_examples/homepage-todo/ts/src/index.html index ec489a4c02..f3aada93dc 100644 --- a/public/docs/_examples/homepage-todo/ts/src/index.html +++ b/public/docs/_examples/homepage-todo/ts/src/index.html @@ -7,6 +7,10 @@ + + + + diff --git a/public/docs/_examples/lifecycle-hooks/ts/index.html b/public/docs/_examples/lifecycle-hooks/ts/index.html index b706287879..10aeaaabdd 100644 --- a/public/docs/_examples/lifecycle-hooks/ts/index.html +++ b/public/docs/_examples/lifecycle-hooks/ts/index.html @@ -4,6 +4,10 @@ Angular 2 Lifecycle Hooks + + + + diff --git a/public/docs/_examples/pipes/ts/index.html b/public/docs/_examples/pipes/ts/index.html index 487e90020f..0bb0cebe87 100644 --- a/public/docs/_examples/pipes/ts/index.html +++ b/public/docs/_examples/pipes/ts/index.html @@ -3,6 +3,10 @@ Pipes + + + + diff --git a/public/docs/_examples/quickstart/ts/index.html b/public/docs/_examples/quickstart/ts/index.html index 2a41a9128e..d535593c7f 100644 --- a/public/docs/_examples/quickstart/ts/index.html +++ b/public/docs/_examples/quickstart/ts/index.html @@ -6,7 +6,13 @@ Angular 2 QuickStart - + + + + + + + diff --git a/public/docs/_examples/router/ts/index.1.html b/public/docs/_examples/router/ts/index.1.html index d3deed5504..9799df9f55 100644 --- a/public/docs/_examples/router/ts/index.1.html +++ b/public/docs/_examples/router/ts/index.1.html @@ -7,6 +7,12 @@ Router Sample + + + + + + diff --git a/public/docs/_examples/router/ts/index.html b/public/docs/_examples/router/ts/index.html index ea2d3a7224..c74d257763 100644 --- a/public/docs/_examples/router/ts/index.html +++ b/public/docs/_examples/router/ts/index.html @@ -13,8 +13,8 @@ - - + + diff --git a/public/docs/_examples/structural-directives/ts/index.html b/public/docs/_examples/structural-directives/ts/index.html index b1e827f803..31c7206e34 100644 --- a/public/docs/_examples/structural-directives/ts/index.html +++ b/public/docs/_examples/structural-directives/ts/index.html @@ -4,6 +4,10 @@ Angular 2 Structural Directives + + + + diff --git a/public/docs/_examples/styleguide/ts/index.html b/public/docs/_examples/styleguide/ts/index.html index 7a5acc493d..c1e3f87ef8 100644 --- a/public/docs/_examples/styleguide/ts/index.html +++ b/public/docs/_examples/styleguide/ts/index.html @@ -2,6 +2,10 @@ + + + + diff --git a/public/docs/_examples/template-syntax/ts/index.html b/public/docs/_examples/template-syntax/ts/index.html index f34a129144..f6c1a72c8d 100644 --- a/public/docs/_examples/template-syntax/ts/index.html +++ b/public/docs/_examples/template-syntax/ts/index.html @@ -3,6 +3,11 @@ Template Syntax + + + + + diff --git a/public/docs/_examples/toh-1/ts/index.html b/public/docs/_examples/toh-1/ts/index.html index a90a31489d..8709602759 100644 --- a/public/docs/_examples/toh-1/ts/index.html +++ b/public/docs/_examples/toh-1/ts/index.html @@ -2,6 +2,10 @@ Angular 2 QuickStart + + + + diff --git a/public/docs/_examples/toh-2/ts/index.html b/public/docs/_examples/toh-2/ts/index.html index a90a31489d..8709602759 100644 --- a/public/docs/_examples/toh-2/ts/index.html +++ b/public/docs/_examples/toh-2/ts/index.html @@ -2,6 +2,10 @@ Angular 2 QuickStart + + + + diff --git a/public/docs/_examples/toh-3/ts/index.html b/public/docs/_examples/toh-3/ts/index.html index a90a31489d..8709602759 100644 --- a/public/docs/_examples/toh-3/ts/index.html +++ b/public/docs/_examples/toh-3/ts/index.html @@ -2,6 +2,10 @@ Angular 2 QuickStart + + + + diff --git a/public/docs/_examples/toh-4/ts/index.html b/public/docs/_examples/toh-4/ts/index.html index a90a31489d..8709602759 100644 --- a/public/docs/_examples/toh-4/ts/index.html +++ b/public/docs/_examples/toh-4/ts/index.html @@ -2,6 +2,10 @@ Angular 2 QuickStart + + + + diff --git a/public/docs/_examples/tutorial/ts/index.html b/public/docs/_examples/tutorial/ts/index.html index 53c8f62c99..b30caa1ea1 100644 --- a/public/docs/_examples/tutorial/ts/index.html +++ b/public/docs/_examples/tutorial/ts/index.html @@ -4,6 +4,10 @@ + + + + diff --git a/public/docs/_examples/user-input/ts/index.html b/public/docs/_examples/user-input/ts/index.html index 646e53503f..7120a99752 100644 --- a/public/docs/_examples/user-input/ts/index.html +++ b/public/docs/_examples/user-input/ts/index.html @@ -3,6 +3,11 @@ User Input + + + + + diff --git a/public/docs/ts/latest/guide/router.jade b/public/docs/ts/latest/guide/router.jade index 95727f46bb..39a3337ac2 100644 --- a/public/docs/ts/latest/guide/router.jade +++ b/public/docs/ts/latest/guide/router.jade @@ -277,6 +277,9 @@ figure.image-display the Angular core script. +makeExample('router/ts/index.html','router-lib')(format=".") +.l-sub-section + :marked + Internet Explorer requires additional polyfill libraries as described [below](#ie-polyfills) :marked ### Set the *<base href>* @@ -291,7 +294,7 @@ figure.image-display 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 `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. + css files, scripts, and images. Add the base element just after the `` tag. If the `app` folder is the application root, as it is for our application, @@ -1435,3 +1438,17 @@ code-example(format=".", language="bash"). Then *override* the default strategy defined in `ROUTE_PROVIDERS` by providing the `HashLocationStrategy` later in the `bootstrap` providers array argument: +makeExample('router/ts/app/boot.2.ts','', 'boot.ts (hash URL strategy)') + + +.l-main-section +:marked + ## Appendix: Internet Explorer polyfills + A routed application relies on ES6 promises and dynamic module loading. + IE needs help with that. + Make sure the following polyfill libraries are loaded in the `index.html` + ***above*** the Angular polyfill: ++makeExample('router/ts/index.html','ie-polyfills')(format=".") +:marked + We could substitute the following libraries from a CDN: ++makeExample('router/ts/index.1.html','ie-cdn-polyfills')(format=".") +:marked diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 163505fb42..e3d0f043c9 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -235,7 +235,7 @@ code-example(format=""). :marked There are three noteworthy sections of HTML: - 1. We load the JavaScript libraries we need. `angular2-polyfills.js` and `Rx.js` are needed by Angular 2.
+ 1. We load the JavaScript libraries we need; learn about them [below](#libraries). 2. We configure something called `System` and ask it to import the boot file we just wrote. @@ -273,11 +273,6 @@ figure.image-display :marked Congratulations! We are in business. -.alert.is-helpful - :marked - If you see `Loading...` displayed instead, see the - [Browser ES6 support appendix](#es6support). -:marked ### Make some changes Try changing the message to "My SECOND Angular 2 app". @@ -345,20 +340,40 @@ figure.image-display elaborate on some of the points we covered quickly above. There is no essential material here. Continued reading is for the curious. - + + + .l-main-section :marked - - ### Appendix: Browser ES6 support - Angular 2 relies on some ES2015 features, most of them found in modern - browsers. Some browsers (including IE 11) require a shim to support the - needed functionality. - Try loading the following shim *above* the other scripts in the `index.html`: - -code-example(language="html" format="."). - <script src="node_modules/es6-shim/es6-shim.js"></script> + ### Appendix: Libraries + We loaded the following scripts ++makeExample('quickstart/ts/index.html', 'libraries', 'index.html')(format=".") +:marked + We began with Internet Explorer polyfills. + IE requires polyfills to run + an application that relies on ES6 promises and dynamic module loading. + Most applications need those capabilities and most applications + should run in Internet Explorer. +.l-sub-section + :marked + We can substitute the following libraries from a CDN: + +makeExample('router/ts/index.1.html','ie-cdn-polyfills')(format=".") +:marked + Next are the polyfills for Angular2, `angular2-polyfills.js`. + Then the [SystemJS library](#systemjs) for module loading, + followed by the Reactive Extensions RxJS library. +.l-sub-section + :marked + Our QuickStart doesn't use the Reactive Extensions + but any substantial application will want them + when working with observables. + We added the library here in QuickStart so we don't forget later. :marked + Finally, we loaded the web development version of Angular 2 itself. + We'll make different choices as we gain experience and + become more concerned about production qualities such as + load times and memory footprint. .l-main-section :marked diff --git a/tools/plunker-builder/indexHtmlTranslator.js b/tools/plunker-builder/indexHtmlTranslator.js index 688e7d0589..c13464e492 100644 --- a/tools/plunker-builder/indexHtmlTranslator.js +++ b/tools/plunker-builder/indexHtmlTranslator.js @@ -85,7 +85,7 @@ var _rxData = [ }, { pattern: 'script', - from: 'node_modules/systemjs/distsystem-polyfills.js', + from: 'node_modules/systemjs/dist/system-polyfills.js', to: 'https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.16/system-polyfills.js' }, {