From 0c0c6f69f32a2bb3980f26ba7aa8327b3d71c2f5 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 17 Aug 2016 13:31:40 -0700 Subject: [PATCH] docs(toh-5): TS/Dart review, and Dart resync (#2115) * docs(toh-5): review and update/resync Dart **NOTE: run `gulp add-example-boilerplate` after pulling in the commit.** This is preparatory work for #2035. As part of the the chapter review, the Dart .jade was enhanced to use Jade extends (#2018). By the same token it contributed to a post-RC5 resync (#2077). Other key changes: Dart and TS code: - Eliminated `styles.1.css` in favor of docregions in `styles.css`. - `docregion` tags renamed in a few places. - **No other code changes**. TS prose - Fixed: misnamed variable `routing` -> `appRoutes`. - All other changes are **minor copy edits**, or changes to support Dart via Jade extends. Diff of generated HTML for TS chapter was inspected to ensure only minor copy edits prevailed (i.e., that the support for Jade extends had no impact on the generated HTML). * docs(toh-5): edits after doing tutorial - Some adjustments following actually doing the tutorial. In some cases code shown (e.g. this is what file foo should look like now) didn't match what the user would have. E.g., lingering @Input on the hero property. - Fixed some lingering deprecated-router prose elements on TS side (e.g., still referring to a route by the old string names like `HeroDetail`). - Added extra step to `app.component.ts` creation rather than having a critical-call-out later on. - Reorder some prose for better harmony between TS and Dart prose (also improves the flow). - Moved the `styleUrls` call-out to the point of first use. * post-review changes * more post-review changes * toh-6 cache update --- public/_includes/_util-fns.jade | 4 +- public/docs/_examples/styles.css | 5 +- .../toh-5/dart/lib/app_component.dart | 34 +- .../toh-5/dart/lib/app_component_1.dart | 33 +- .../toh-5/dart/lib/app_component_2.dart | 31 - .../toh-5/dart/lib/dashboard_component.dart | 8 +- .../toh-5/dart/lib/dashboard_component_2.dart | 2 +- .../toh-5/dart/lib/hero_detail_component.dart | 32 +- .../toh-5/dart/lib/hero_service.dart | 4 +- .../toh-5/dart/lib/heroes_component.dart | 21 +- .../_examples/toh-5/dart/web/styles_1.css | 24 - .../_examples/toh-5/ts/app/app.component.1.ts | 30 +- .../_examples/toh-5/ts/app/app.component.2.ts | 17 - .../_examples/toh-5/ts/app/app.component.3.ts | 24 - .../_examples/toh-5/ts/app/app.component.ts | 5 +- .../_examples/toh-5/ts/app/app.module.2.ts | 30 - .../_examples/toh-5/ts/app/app.module.3.ts | 47 -- .../docs/_examples/toh-5/ts/app/app.module.ts | 11 +- .../_examples/toh-5/ts/app/app.routing.1.ts | 7 +- .../_examples/toh-5/ts/app/app.routing.2.ts | 36 - .../_examples/toh-5/ts/app/app.routing.ts | 25 +- .../toh-5/ts/app/dashboard.component.2.ts | 2 +- .../toh-5/ts/app/dashboard.component.ts | 8 +- .../toh-5/ts/app/hero-detail.component.1.ts | 27 + .../toh-5/ts/app/hero-detail.component.ts | 24 +- .../_examples/toh-5/ts/app/hero.service.ts | 4 +- .../toh-5/ts/app/heroes.component.ts | 14 +- public/docs/_examples/toh-5/ts/styles.1.css | 24 - public/docs/dart/latest/tutorial/toh-pt5.jade | 778 +++--------------- public/docs/ts/_cache/tutorial/toh-pt5.jade | 766 ++++++++++------- public/docs/ts/_cache/tutorial/toh-pt6.jade | 2 +- public/docs/ts/latest/tutorial/toh-pt5.jade | 766 ++++++++++------- 32 files changed, 1260 insertions(+), 1585 deletions(-) delete mode 100644 public/docs/_examples/toh-5/dart/lib/app_component_2.dart delete mode 100644 public/docs/_examples/toh-5/dart/web/styles_1.css delete mode 100644 public/docs/_examples/toh-5/ts/app/app.component.2.ts delete mode 100644 public/docs/_examples/toh-5/ts/app/app.component.3.ts delete mode 100644 public/docs/_examples/toh-5/ts/app/app.module.2.ts delete mode 100644 public/docs/_examples/toh-5/ts/app/app.module.3.ts delete mode 100644 public/docs/_examples/toh-5/ts/app/app.routing.2.ts create mode 100644 public/docs/_examples/toh-5/ts/app/hero-detail.component.1.ts delete mode 100644 public/docs/_examples/toh-5/ts/styles.1.css diff --git a/public/_includes/_util-fns.jade b/public/_includes/_util-fns.jade index cf9a569346..1221883491 100644 --- a/public/_includes/_util-fns.jade +++ b/public/_includes/_util-fns.jade @@ -222,8 +222,8 @@ script. - // E.g. of a project relative path is 'app/main.ts' - if (ex.title === null || ex.title === undefined) { - // Title is not given so take it to be ex.filePath. -- // Is title like styles.1.css? Then drop the '.1' qualifier: -- var matches = ex.filePath.match(/^(.*)\.\d(\.\w+)$/); +- // Title like styles.1.css or foo_1.dart? Then drop the '.1' or '_1' qualifier: +- var matches = ex.filePath.match(/^(.*)[\._]\d(\.\w+)$/); - ex.title = matches ? matches[1] + matches[2] : ex.filePath; - } - ex.filePath = getExampleName() + '/' + _docsFor + '/' + ex.filePath; diff --git a/public/docs/_examples/styles.css b/public/docs/_examples/styles.css index 002017d4bd..d7b83f9e81 100644 --- a/public/docs/_examples/styles.css +++ b/public/docs/_examples/styles.css @@ -1,4 +1,4 @@ -/* #docregion , quickstart */ +/* #docregion , quickstart, toh */ /* Master Styles */ h1 { color: #369; @@ -18,6 +18,7 @@ body, input[text], button { color: #888; font-family: Cambria, Georgia; } +/* #enddocregion toh */ a { cursor: pointer; cursor: hand; @@ -137,7 +138,7 @@ nav a.active { margin-right: .8em; border-radius: 4px 0 0 4px; } - +/* #docregion toh */ /* everywhere else */ * { font-family: Arial, Helvetica, sans-serif; diff --git a/public/docs/_examples/toh-5/dart/lib/app_component.dart b/public/docs/_examples/toh-5/dart/lib/app_component.dart index ecf2bf4f3c..ba1ed39c88 100644 --- a/public/docs/_examples/toh-5/dart/lib/app_component.dart +++ b/public/docs/_examples/toh-5/dart/lib/app_component.dart @@ -1,18 +1,18 @@ // #docplaster // #docregion import 'package:angular2/core.dart'; +// #docregion import-router import 'package:angular2/router.dart'; +// #enddocregion import-router -import 'package:angular2_tour_of_heroes/heroes_component.dart'; -import 'package:angular2_tour_of_heroes/hero_service.dart'; -import 'package:angular2_tour_of_heroes/dashboard_component.dart'; -// #docregion hero-detail-import -import 'package:angular2_tour_of_heroes/hero_detail_component.dart'; -// #enddocregion hero-detail-import +import 'dashboard_component.dart'; +import 'hero_detail_component.dart'; +import 'hero_service.dart'; +import 'heroes_component.dart'; @Component( selector: 'my-app', - // #docregion template + // #docregion template, template-v3 template: '''

{{title}}

''', - // #enddocregion template - // #docregion style-urls + // #enddocregion template, template-v3 + // #docregion styleUrls styleUrls: const ['app_component.css'], - // #enddocregion style-urls + // #enddocregion styleUrls + // #docregion directives-and-providers directives: const [ROUTER_DIRECTIVES], providers: const [HeroService, ROUTER_PROVIDERS]) +// #enddocregion directives-and-providers +// #docregion heroes @RouteConfig(const [ - // #docregion dashboard-route + // #enddocregion heroes + // #docregion dashboard const Route( path: '/dashboard', name: 'Dashboard', component: DashboardComponent, useAsDefault: true), - // #enddocregion dashboard-route - // #docregion hero-detail-route + // #enddocregion dashboard + // #docregion hero-detail const Route( path: '/detail/:id', name: 'HeroDetail', component: HeroDetailComponent), - // #enddocregion hero-detail-route + // #enddocregion hero-detail + // #docregion heroes const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent) ]) +// #enddocregion heroes class AppComponent { String title = 'Tour of Heroes'; } diff --git a/public/docs/_examples/toh-5/dart/lib/app_component_1.dart b/public/docs/_examples/toh-5/dart/lib/app_component_1.dart index 880974b28f..8455181dbc 100644 --- a/public/docs/_examples/toh-5/dart/lib/app_component_1.dart +++ b/public/docs/_examples/toh-5/dart/lib/app_component_1.dart @@ -1,25 +1,40 @@ // #docplaster -// #docregion +// #docregion , v2 import 'package:angular2/core.dart'; -// #enddocregion -import 'package:angular2/router.dart'; // for testing only +// #enddocregion , +// #docregion v2 +import 'package:angular2/router.dart'; // #docregion import 'hero_service.dart'; import 'heroes_component.dart'; +// #enddocregion v2 @Component( selector: 'my-app', template: '''

{{title}}

''', directives: const [HeroesComponent], - providers: const [ - // #enddocregion - ROUTER_PROVIDERS, - // #docregion - HeroService - ]) + providers: const [HeroService]) +// #enddocregion , +class Bogus {} + +// #docregion v2 +@Component( + selector: 'my-app', + // #docregion template-v2 + template: ''' +

{{title}}

+ Heroes + ''', + // #enddocregion template-v2 + directives: const [ROUTER_DIRECTIVES], + providers: const [HeroService, ROUTER_PROVIDERS]) +@RouteConfig(const [ + const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent) +]) +// #docregion , class AppComponent { String title = 'Tour of Heroes'; } diff --git a/public/docs/_examples/toh-5/dart/lib/app_component_2.dart b/public/docs/_examples/toh-5/dart/lib/app_component_2.dart deleted file mode 100644 index 024c2b6ac9..0000000000 --- a/public/docs/_examples/toh-5/dart/lib/app_component_2.dart +++ /dev/null @@ -1,31 +0,0 @@ -// #docplaster -// #docregion -import 'package:angular2/core.dart'; -// #docregion import-router -import 'package:angular2/router.dart'; -// #enddocregion import-router - -import 'hero_service.dart'; -import 'heroes_component.dart'; - -@Component( - selector: 'my-app', - // #docregion template - template: ''' -

{{title}}

- Heroes - ''', - // #enddocregion template - // #docregion directives-and-providers - directives: const [ROUTER_DIRECTIVES], - providers: const [ROUTER_PROVIDERS, HeroService] - // #enddocregion directives-and-providers -) -// #docregion route-config -@RouteConfig(const [ - const Route(path: '/heroes', name: 'Heroes', component: HeroesComponent) -]) -// #enddocregion route-config -class AppComponent { - String title = 'Tour of Heroes'; -} diff --git a/public/docs/_examples/toh-5/dart/lib/dashboard_component.dart b/public/docs/_examples/toh-5/dart/lib/dashboard_component.dart index ff0fb8c0d1..8b2f6fe4af 100644 --- a/public/docs/_examples/toh-5/dart/lib/dashboard_component.dart +++ b/public/docs/_examples/toh-5/dart/lib/dashboard_component.dart @@ -12,9 +12,9 @@ import 'hero_service.dart'; @Component( selector: 'my-dashboard', - // #docregion template-url + // #docregion templateUrl templateUrl: 'dashboard_component.html', - // #enddocregion template-url + // #enddocregion templateUrl // #docregion css styleUrls: const ['dashboard_component.css'] // #enddocregion css @@ -35,7 +35,7 @@ class DashboardComponent implements OnInit { heroes = (await _heroService.getHeroes()).skip(1).take(4).toList(); } - // #docregion goto-detail + // #docregion gotoDetail void gotoDetail(Hero hero) { var link = [ 'HeroDetail', @@ -43,5 +43,5 @@ class DashboardComponent implements OnInit { ]; _router.navigate(link); } -// #enddocregion goto-detail +// #enddocregion gotoDetail } diff --git a/public/docs/_examples/toh-5/dart/lib/dashboard_component_2.dart b/public/docs/_examples/toh-5/dart/lib/dashboard_component_2.dart index aa9afb38d7..c5304f572a 100644 --- a/public/docs/_examples/toh-5/dart/lib/dashboard_component_2.dart +++ b/public/docs/_examples/toh-5/dart/lib/dashboard_component_2.dart @@ -22,5 +22,5 @@ class DashboardComponent implements OnInit { heroes = (await _heroService.getHeroes()).skip(1).take(4).toList(); } - gotoDetail() {/* not implemented yet */} + gotoDetail(Hero hero) {/* not implemented yet */} } diff --git a/public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart b/public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart index a6c506a231..a99528cbaa 100644 --- a/public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart +++ b/public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart @@ -1,30 +1,28 @@ // #docplaster // #docregion , v2 +// #docregion added-imports import 'dart:async'; -import 'dart:html'; +import 'dart:html' show window; -// #docregion import-oninit +// #enddocregion added-imports import 'package:angular2/core.dart'; -// #enddocregion import-oninit -// #docregion import-route-params +// #docregion added-imports import 'package:angular2/router.dart'; -// #enddocregion import-route-params +// #enddocregion added-imports import 'hero.dart'; -// #docregion import-hero-service +// #docregion added-imports import 'hero_service.dart'; -// #enddocregion import-hero-service +// #enddocregion added-imports -// #docregion extract-template @Component( selector: 'my-hero-detail', - // #docregion template-url + // #docregion templateUrl templateUrl: 'hero_detail_component.html', - // #enddocregion template-url, v2 + // #enddocregion templateUrl, v2 styleUrls: const ['hero_detail_component.css'] // #docregion v2 ) -// #enddocregion extract-template // #docregion implement class HeroDetailComponent implements OnInit { // #enddocregion implement @@ -36,19 +34,17 @@ class HeroDetailComponent implements OnInit { HeroDetailComponent(this._heroService, this._routeParams); // #enddocregion ctor - // #docregion ng-oninit + // #docregion ngOnInit Future ngOnInit() async { - // #docregion get-id var idString = _routeParams.get('id'); - var id = int.parse(idString, onError: (_) => null); - // #enddocregion get-id + var id = int.parse(idString ?? '', onError: (_) => null); if (id != null) hero = await (_heroService.getHero(id)); } - // #enddocregion ng-oninit + // #enddocregion ngOnInit - // #docregion go-back + // #docregion goBack void goBack() { window.history.back(); } - // #enddocregion go-back + // #enddocregion goBack } diff --git a/public/docs/_examples/toh-5/dart/lib/hero_service.dart b/public/docs/_examples/toh-5/dart/lib/hero_service.dart index e626b38200..b8e04a67c6 100644 --- a/public/docs/_examples/toh-5/dart/lib/hero_service.dart +++ b/public/docs/_examples/toh-5/dart/lib/hero_service.dart @@ -16,8 +16,8 @@ class HeroService { const Duration(seconds: 2), () => mockHeroes); } - // #docregion get-hero + // #docregion getHero Future getHero(int id) async => (await getHeroes()).firstWhere((hero) => hero.id == id); - // #enddocregion get-hero + // #enddocregion getHero } diff --git a/public/docs/_examples/toh-5/dart/lib/heroes_component.dart b/public/docs/_examples/toh-5/dart/lib/heroes_component.dart index 48e1a167bf..e19c3ab3be 100644 --- a/public/docs/_examples/toh-5/dart/lib/heroes_component.dart +++ b/public/docs/_examples/toh-5/dart/lib/heroes_component.dart @@ -6,27 +6,28 @@ import 'package:angular2/core.dart'; import 'package:angular2/router.dart'; import 'hero.dart'; -import 'hero_detail_component.dart'; import 'hero_service.dart'; -// #docregion metadata, heroes-component-renaming +// #docregion metadata, renaming @Component( selector: 'my-heroes', - // #enddocregion heroes-component-renaming + // #enddocregion renaming templateUrl: 'heroes_component.html', - styleUrls: const ['heroes_component.css'], - directives: const [HeroDetailComponent]) -// #docregion heroes-component-renaming -// #enddocregion heroes-component-renaming, metadata -// #docregion class, heroes-component-renaming + styleUrls: const ['heroes_component.css'] +// #docregion renaming +) +// #enddocregion metadata +// #docregion class class HeroesComponent implements OnInit { - // #enddocregion heroes-component-renaming + // #enddocregion renaming final Router _router; final HeroService _heroService; List heroes; Hero selectedHero; + // #docregion renaming HeroesComponent(this._heroService, this._router); + // #enddocregion renaming Future getHeroes() async { heroes = await _heroService.getHeroes(); @@ -44,5 +45,5 @@ class HeroesComponent implements OnInit { 'HeroDetail', {'id': selectedHero.id.toString()} ]); - // #docregion heroes-component-renaming + // #docregion renaming } diff --git a/public/docs/_examples/toh-5/dart/web/styles_1.css b/public/docs/_examples/toh-5/dart/web/styles_1.css deleted file mode 100644 index dee6d5b8ca..0000000000 --- a/public/docs/_examples/toh-5/dart/web/styles_1.css +++ /dev/null @@ -1,24 +0,0 @@ -/* #docregion toh-excerpt */ -/* Master Styles */ -h1 { - color: #369; - font-family: Arial, Helvetica, sans-serif; - font-size: 250%; -} -h2, h3 { - color: #444; - font-family: Arial, Helvetica, sans-serif; - font-weight: lighter; -} -body { - margin: 2em; -} -body, input[text], button { - color: #888; - font-family: Cambria, Georgia; -} -/* . . . */ -/* everywhere else */ -* { - font-family: Arial, Helvetica, sans-serif; -} diff --git a/public/docs/_examples/toh-5/ts/app/app.component.1.ts b/public/docs/_examples/toh-5/ts/app/app.component.1.ts index cbdd040437..c9f5db9712 100644 --- a/public/docs/_examples/toh-5/ts/app/app.component.1.ts +++ b/public/docs/_examples/toh-5/ts/app/app.component.1.ts @@ -1,7 +1,8 @@ // #docplaster -// #docregion +// #docregion , v2 import { Component } from '@angular/core'; +// #enddocregion v2 @Component({ selector: 'my-app', template: ` @@ -9,6 +10,33 @@ import { Component } from '@angular/core'; ` }) +// #enddocregion +// #docregion v2 +@Component({ + selector: 'my-app', + // #docregion template-v2 + template: ` +

{{title}}

+ Heroes + + ` + // #enddocregion template-v2 +}) +// #enddocregion +@Component({ + selector: 'my-app', + // #docregion template-v3 + template: ` +

{{title}}

+ + + ` + // #enddocregion template-v3 +}) +// #docregion , v2 export class AppComponent { title = 'Tour of Heroes'; } diff --git a/public/docs/_examples/toh-5/ts/app/app.component.2.ts b/public/docs/_examples/toh-5/ts/app/app.component.2.ts deleted file mode 100644 index 82e5147775..0000000000 --- a/public/docs/_examples/toh-5/ts/app/app.component.2.ts +++ /dev/null @@ -1,17 +0,0 @@ -// #docplaster -// #docregion -import { Component } from '@angular/core'; - -@Component({ - selector: 'my-app', - // #docregion template - template: ` -

{{title}}

- Heroes - - ` - // #enddocregion template -}) -export class AppComponent { - title = 'Tour of Heroes'; -} diff --git a/public/docs/_examples/toh-5/ts/app/app.component.3.ts b/public/docs/_examples/toh-5/ts/app/app.component.3.ts deleted file mode 100644 index 2d1f83853c..0000000000 --- a/public/docs/_examples/toh-5/ts/app/app.component.3.ts +++ /dev/null @@ -1,24 +0,0 @@ -// #docplaster -// #docregion -import { Component } from '@angular/core'; - -@Component({ - selector: 'my-app', - // #docregion template - template: ` -

{{title}}

- - - `, - // #enddocregion template - // #docregion style-urls - styleUrls: ['app/app.component.css'], - // #enddocregion style-urls -}) -export class AppComponent { - title = 'Tour of Heroes'; -} -// #enddocregion diff --git a/public/docs/_examples/toh-5/ts/app/app.component.ts b/public/docs/_examples/toh-5/ts/app/app.component.ts index fbf2279067..12fe3bfd52 100644 --- a/public/docs/_examples/toh-5/ts/app/app.component.ts +++ b/public/docs/_examples/toh-5/ts/app/app.component.ts @@ -1,4 +1,3 @@ -// #docplaster // #docregion import { Component } from '@angular/core'; @@ -14,9 +13,9 @@ import { Component } from '@angular/core'; `, // #enddocregion template - // #docregion style-urls + // #docregion styleUrls styleUrls: ['app/app.component.css'], - // #enddocregion style-urls + // #enddocregion styleUrls }) export class AppComponent { title = 'Tour of Heroes'; diff --git a/public/docs/_examples/toh-5/ts/app/app.module.2.ts b/public/docs/_examples/toh-5/ts/app/app.module.2.ts deleted file mode 100644 index 1a4ac0f48d..0000000000 --- a/public/docs/_examples/toh-5/ts/app/app.module.2.ts +++ /dev/null @@ -1,30 +0,0 @@ -// #docregion -import { NgModule } from '@angular/core'; -import { BrowserModule } from '@angular/platform-browser'; -import { FormsModule } from '@angular/forms'; - -import { AppComponent } from './app.component'; -import { routing } from './app.routing'; - -import { HeroesComponent } from './heroes.component'; - -import { HeroService } from './hero.service'; - -@NgModule({ - imports: [ - BrowserModule, - FormsModule, - routing - ], - declarations: [ - AppComponent, - HeroesComponent - ], - providers: [ - HeroService - ], - bootstrap: [ AppComponent ] -}) -export class AppModule { -} -// #enddocregion diff --git a/public/docs/_examples/toh-5/ts/app/app.module.3.ts b/public/docs/_examples/toh-5/ts/app/app.module.3.ts deleted file mode 100644 index 2eca272b26..0000000000 --- a/public/docs/_examples/toh-5/ts/app/app.module.3.ts +++ /dev/null @@ -1,47 +0,0 @@ -// #docplaster -// #docregion -import { NgModule } from '@angular/core'; -import { BrowserModule } from '@angular/platform-browser'; -import { FormsModule } from '@angular/forms'; - -import { AppComponent } from './app.component'; -import { routing } from './app.routing'; - -import { HeroesComponent } from './heroes.component'; -// #docregion dashboard-declaration -import { DashboardComponent } from './dashboard.component'; -// #enddocregion dashboard-declaration -// #docregion hero-detail-declaration -import { HeroDetailComponent } from './hero-detail.component'; -// #enddocregion hero-detail-declaration -import { HeroService } from './hero.service'; - -@NgModule({ - imports: [ - BrowserModule, - FormsModule, - routing - ], -// #docregion dashboard-declaration, hero-detail-declaration - - declarations: [ -// #enddocregion dashboard-declaration, hero-detail-declaration - AppComponent, - HeroesComponent, -// #docregion dashboard-declaration - DashboardComponent, -// #enddocregion dashboard-declaration -// #docregion hero-detail-declaration - HeroDetailComponent -// #enddocregion hero-detail-declaration -// #docregion dashboard-declaration, hero-detail-declaration - ], -// #enddocregion dashboard-declaration, hero-detail-declaration - providers: [ - HeroService - ], - bootstrap: [ AppComponent ] -}) -export class AppModule { -} -// #enddocregion diff --git a/public/docs/_examples/toh-5/ts/app/app.module.ts b/public/docs/_examples/toh-5/ts/app/app.module.ts index 47cc9415bb..a0ae4ecf83 100644 --- a/public/docs/_examples/toh-5/ts/app/app.module.ts +++ b/public/docs/_examples/toh-5/ts/app/app.module.ts @@ -1,16 +1,20 @@ +// #docplaster // #docregion import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { FormsModule } from '@angular/forms'; import { AppComponent } from './app.component'; +// #docregion routing import { routing } from './app.routing'; +// #enddocregion routing import { HeroesComponent } from './heroes.component'; import { DashboardComponent } from './dashboard.component'; import { HeroDetailComponent } from './hero-detail.component'; import { HeroService } from './hero.service'; +// #docregion routing @NgModule({ imports: [ @@ -18,17 +22,22 @@ import { HeroService } from './hero.service'; FormsModule, routing ], + // #enddocregion routing + // #docregion dashboard, hero-detail declarations: [ AppComponent, HeroesComponent, DashboardComponent, + // #enddocregion dashboard HeroDetailComponent + // #docregion dashboard ], + // #enddocregion dashboard, hero-detail providers: [ HeroService ], bootstrap: [ AppComponent ] + // #docregion routing }) export class AppModule { } -// #enddocregion diff --git a/public/docs/_examples/toh-5/ts/app/app.routing.1.ts b/public/docs/_examples/toh-5/ts/app/app.routing.1.ts index 055b26754e..355c7b31a2 100644 --- a/public/docs/_examples/toh-5/ts/app/app.routing.1.ts +++ b/public/docs/_examples/toh-5/ts/app/app.routing.1.ts @@ -1,5 +1,4 @@ -// #docregion -// #docregion routing-config +// #docregion , heroes import { Routes, RouterModule } from '@angular/router'; import { HeroesComponent } from './heroes.component'; @@ -10,8 +9,6 @@ const appRoutes: Routes = [ component: HeroesComponent } ]; -// #enddocregion routing-config +// #enddocregion heroes -// #docregion routing-export export const routing = RouterModule.forRoot(appRoutes); -// #enddocregion routing-export diff --git a/public/docs/_examples/toh-5/ts/app/app.routing.2.ts b/public/docs/_examples/toh-5/ts/app/app.routing.2.ts deleted file mode 100644 index a75df506e7..0000000000 --- a/public/docs/_examples/toh-5/ts/app/app.routing.2.ts +++ /dev/null @@ -1,36 +0,0 @@ -// #docregion -import { Routes, RouterModule } from '@angular/router'; - -import { DashboardComponent } from './dashboard.component'; -import { HeroesComponent } from './heroes.component'; -// #docregion hero-detail-import -import { HeroDetailComponent } from './hero-detail.component'; -// #enddocregion hero-detail-import - -const appRoutes: Routes = [ - // #docregion redirect-route - { - path: '', - redirectTo: '/dashboard', - pathMatch: 'full' - }, - // #enddocregion redirect-route - // #docregion dashboard-route - { - path: 'dashboard', - component: DashboardComponent - }, - // #enddocregion dashboard-route - // #docregion hero-detail-route - { - path: 'detail/:id', - component: HeroDetailComponent - }, - // #enddocregion hero-detail-route - { - path: 'heroes', - component: HeroesComponent - } -]; - -export const routing = RouterModule.forRoot(appRoutes); diff --git a/public/docs/_examples/toh-5/ts/app/app.routing.ts b/public/docs/_examples/toh-5/ts/app/app.routing.ts index 62071e2567..ba41888354 100644 --- a/public/docs/_examples/toh-5/ts/app/app.routing.ts +++ b/public/docs/_examples/toh-5/ts/app/app.routing.ts @@ -1,30 +1,43 @@ -// #docregion +// #docplaster +// #docregion , heroes import { Routes, RouterModule } from '@angular/router'; -import { DashboardComponent } from './dashboard.component'; -import { HeroesComponent } from './heroes.component'; -// #docregion hero-detail-import -import { HeroDetailComponent } from './hero-detail.component'; -// #enddocregion hero-detail-import +// #enddocregion heroes +import { DashboardComponent } from './dashboard.component'; +// #docregion heroes +import { HeroesComponent } from './heroes.component'; +// #enddocregion heroes +import { HeroDetailComponent } from './hero-detail.component'; +// #docregion heroes const appRoutes: Routes = [ + // #enddocregion heroes + // #docregion redirect { path: '', redirectTo: '/dashboard', pathMatch: 'full' }, + // #enddocregion redirect + // #docregion dashboard { path: 'dashboard', component: DashboardComponent }, + // #enddocregion dashboard + // #docregion hero-detail { path: 'detail/:id', component: HeroDetailComponent }, + // #enddocregion hero-detail + // #docregion heroes { path: 'heroes', component: HeroesComponent } ]; +// #enddocregion heroes +// #docregion routing export const routing = RouterModule.forRoot(appRoutes); diff --git a/public/docs/_examples/toh-5/ts/app/dashboard.component.2.ts b/public/docs/_examples/toh-5/ts/app/dashboard.component.2.ts index e6b9609ab0..eaa39fb4b8 100644 --- a/public/docs/_examples/toh-5/ts/app/dashboard.component.2.ts +++ b/public/docs/_examples/toh-5/ts/app/dashboard.component.2.ts @@ -22,5 +22,5 @@ export class DashboardComponent implements OnInit { .then(heroes => this.heroes = heroes.slice(1, 5)); } - gotoDetail() { /* not implemented yet */} + gotoDetail(hero: Hero) { /* not implemented yet */} } diff --git a/public/docs/_examples/toh-5/ts/app/dashboard.component.ts b/public/docs/_examples/toh-5/ts/app/dashboard.component.ts index 6dd4b1abc2..a56b724c95 100644 --- a/public/docs/_examples/toh-5/ts/app/dashboard.component.ts +++ b/public/docs/_examples/toh-5/ts/app/dashboard.component.ts @@ -10,9 +10,9 @@ import { HeroService } from './hero.service'; @Component({ selector: 'my-dashboard', - // #docregion template-url + // #docregion templateUrl templateUrl: 'app/dashboard.component.html', - // #enddocregion template-url + // #enddocregion templateUrl // #docregion css styleUrls: ['app/dashboard.component.css'] // #enddocregion css @@ -34,10 +34,10 @@ export class DashboardComponent implements OnInit { .then(heroes => this.heroes = heroes.slice(1, 5)); } - // #docregion goto-detail + // #docregion gotoDetail gotoDetail(hero: Hero) { let link = ['/detail', hero.id]; this.router.navigate(link); } - // #enddocregion goto-detail + // #enddocregion gotoDetail } diff --git a/public/docs/_examples/toh-5/ts/app/hero-detail.component.1.ts b/public/docs/_examples/toh-5/ts/app/hero-detail.component.1.ts new file mode 100644 index 0000000000..efbe8ee913 --- /dev/null +++ b/public/docs/_examples/toh-5/ts/app/hero-detail.component.1.ts @@ -0,0 +1,27 @@ +// Imports in comments cause problems when the app is executed +// (some error about 'traceur' missing). Hence this separate file +// is solely for containing the transitory state of the imports. + +// #docregion added-imports +// Keep the Input import for now, we'll remove it later: +import { Component, Input, OnInit } from '@angular/core'; +import { ActivatedRoute, Params } from '@angular/router'; + +import { HeroService } from './hero.service'; +// #enddocregion added-imports + +// Bogus code below this point. It is only here to make lint happy. +import { Hero } from './hero'; + +@Component({}) +export class HeroDetailComponent implements OnInit { + @Input() hero: Hero; + bogus: Params; + + constructor( + private heroService: HeroService, + private route: ActivatedRoute) { + } + + ngOnInit() {} +} diff --git a/public/docs/_examples/toh-5/ts/app/hero-detail.component.ts b/public/docs/_examples/toh-5/ts/app/hero-detail.component.ts index 713d27c9f2..940b4493aa 100644 --- a/public/docs/_examples/toh-5/ts/app/hero-detail.component.ts +++ b/public/docs/_examples/toh-5/ts/app/hero-detail.component.ts @@ -1,27 +1,19 @@ // #docplaster -// #docregion -// #docregion import-oninit, v2 +// #docregion , v2 import { Component, OnInit } from '@angular/core'; -// #enddocregion import-oninit -// #docregion import-activated-route import { ActivatedRoute, Params } from '@angular/router'; -// #enddocregion import-activated-route import { Hero } from './hero'; -// #docregion import-hero-service import { HeroService } from './hero.service'; -// #enddocregion import-hero-service -// #docregion extract-template @Component({ selector: 'my-hero-detail', - // #docregion template-url + // #docregion templateUrl templateUrl: 'app/hero-detail.component.html', - // #enddocregion template-url, v2 + // #enddocregion templateUrl, v2 styleUrls: ['app/hero-detail.component.css'] // #docregion v2 }) -// #enddocregion extract-template // #docregion implement export class HeroDetailComponent implements OnInit { // #enddocregion implement @@ -34,21 +26,19 @@ export class HeroDetailComponent implements OnInit { } // #enddocregion ctor - // #docregion ng-oninit + // #docregion ngOnInit ngOnInit() { - // #docregion get-id this.route.params.forEach((params: Params) => { let id = +params['id']; this.heroService.getHero(id) .then(hero => this.hero = hero); }); - // #enddocregion get-id } - // #enddocregion ng-oninit + // #enddocregion ngOnInit - // #docregion go-back + // #docregion goBack goBack() { window.history.back(); } -// #enddocregion go-back +// #enddocregion goBack } diff --git a/public/docs/_examples/toh-5/ts/app/hero.service.ts b/public/docs/_examples/toh-5/ts/app/hero.service.ts index 900d0da712..c0e987e7c9 100644 --- a/public/docs/_examples/toh-5/ts/app/hero.service.ts +++ b/public/docs/_examples/toh-5/ts/app/hero.service.ts @@ -17,10 +17,10 @@ export class HeroService { ); } - // #docregion get-hero + // #docregion getHero getHero(id: number) { return this.getHeroes() .then(heroes => heroes.find(hero => hero.id === id)); } - // #enddocregion get-hero + // #enddocregion getHero } diff --git a/public/docs/_examples/toh-5/ts/app/heroes.component.ts b/public/docs/_examples/toh-5/ts/app/heroes.component.ts index c0dbd9c8e7..49fcf10c17 100644 --- a/public/docs/_examples/toh-5/ts/app/heroes.component.ts +++ b/public/docs/_examples/toh-5/ts/app/heroes.component.ts @@ -6,18 +6,18 @@ import { Router } from '@angular/router'; import { Hero } from './hero'; import { HeroService } from './hero.service'; -// #docregion heroes-component-renaming, metadata +// #docregion renaming, metadata @Component({ selector: 'my-heroes', - // #enddocregion heroes-component-renaming + // #enddocregion renaming templateUrl: 'app/heroes.component.html', styleUrls: ['app/heroes.component.css'] - // #docregion heroes-component-renaming + // #docregion renaming }) -// #enddocregion heroes-component-renaming, metadata -// #docregion class, heroes-component-renaming +// #enddocregion metadata +// #docregion class export class HeroesComponent implements OnInit { - // #enddocregion heroes-component-renaming + // #enddocregion renaming heroes: Hero[]; selectedHero: Hero; @@ -38,5 +38,5 @@ export class HeroesComponent implements OnInit { gotoDetail() { this.router.navigate(['/detail', this.selectedHero.id]); } - // #docregion heroes-component-renaming + // #docregion renaming } diff --git a/public/docs/_examples/toh-5/ts/styles.1.css b/public/docs/_examples/toh-5/ts/styles.1.css deleted file mode 100644 index dee6d5b8ca..0000000000 --- a/public/docs/_examples/toh-5/ts/styles.1.css +++ /dev/null @@ -1,24 +0,0 @@ -/* #docregion toh-excerpt */ -/* Master Styles */ -h1 { - color: #369; - font-family: Arial, Helvetica, sans-serif; - font-size: 250%; -} -h2, h3 { - color: #444; - font-family: Arial, Helvetica, sans-serif; - font-weight: lighter; -} -body { - margin: 2em; -} -body, input[text], button { - color: #888; - font-family: Cambria, Georgia; -} -/* . . . */ -/* everywhere else */ -* { - font-family: Arial, Helvetica, sans-serif; -} diff --git a/public/docs/dart/latest/tutorial/toh-pt5.jade b/public/docs/dart/latest/tutorial/toh-pt5.jade index 00fe8db972..6be571c148 100644 --- a/public/docs/dart/latest/tutorial/toh-pt5.jade +++ b/public/docs/dart/latest/tutorial/toh-pt5.jade @@ -1,702 +1,168 @@ -include ../_util-fns +extends ../../../ts/_cache/tutorial/toh-pt5 -:marked - # Routing Around the App - We received new requirements for our Tour of Heroes application: - * Add a *Dashboard* view. - * Navigate between the *Heroes* and *Dashboard* views. - * Clicking on a hero in either view navigates to a detail view of the selected hero. - * Clicking a *deep link* in an email opens the detail view for a particular hero. +block includes + include ../_util-fns + - var _appRoutingTsVsAppComp = 'AppComponent' + - var _declsVsDirectives = 'directives' + - var _RoutesVsAtRouteConfig = '@RouteConfig' + - var _RouterModuleVsRouterDirectives = 'ROUTER_DIRECTIVES' + - var _redirectTo = 'useAsDefault' - When we’re done, users will be able to navigate the app like this: -figure.image-display - img(src='/resources/images/devguide/toh/nav-diagram.png' alt="View navigations") -:marked - We'll add Angular’s *Component Router* to our app to satisfy these requirements. -.l-sub-section - :marked - The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail - than we will in this tutorial. - - Run the for this part. - -.l-main-section -:marked - ## Where We Left Off - Before we continue with our Tour of Heroes, let’s verify that we have the following structure after adding our hero service - and hero detail component. If not, we’ll need to go back and follow the previous chapters. - -.filetree +block intro-file-tree + .filetree .file angular2_tour_of_heroes .children - .file lib - .children - .file app_component.dart - .file hero.dart - .file hero_detail_component.dart - .file hero_service.dart - .file mock_heroes.dart - .file web - .children - .file index.html - .file main.dart - .file styles.css - .file pubspec.yaml -:marked - ### Keep the app compiling and running - Open a terminal/console window. - Start the Dart compiler, watch for changes, and start our server by entering the command: + .file lib + .children + .file app_component.dart + .file hero.dart + .file hero_detail_component.dart + .file hero_service.dart + .file mock_heroes.dart + .file web + .children + .file index.html + .file main.dart + .file styles.css + .file pubspec.yaml -code-example(language="bash"). - pub serve - -:marked - The application runs and updates automatically as we continue to build the Tour of Heroes. - - ## Action plan - Here's our plan: - - * Turn `AppComponent` into an application shell that only handles navigation - * Relocate the *Heroes* concerns within the current `AppComponent` to a separate `HeroesComponent` - * Add routing - * Create a new `DashboardComponent` - * Tie the *Dashboard* into the navigation structure - -.l-sub-section +block keep-app-running :marked - *Routing* is another name for *navigation*. The *router* is the mechanism for navigating from view to view. + ### Keep the app compiling and running -.l-main-section -:marked - ## Splitting the *AppComponent* + Open a terminal/console window. + Start the Dart compiler, watch for changes, and start our server by entering the command: - Our current app loads `AppComponent` and immediately displays the list of heroes. + code-example(language="bash"). + pub serve - Our revised app should present a shell with a choice of views (*Dashboard* and *Heroes*) and then default to one of them. +block app-comp-v1 + +makeExcerpt('lib/app_component_1.dart (v1)', '') - The `AppComponent` should only handle navigation. - Let's move the display of *Heroes* out of `AppComponent` and into its own `HeroesComponent`. - - ### *HeroesComponent* - `AppComponent` is already dedicated to *Heroes*. - Instead of moving anything out of `AppComponent`, we'll just rename it `HeroesComponent` - and create a new `AppComponent` shell separately. - - The steps are to rename: - * `app_component.dart` file to `heroes_component.dart` - * `AppComponent` class to `HeroesComponent` - * Selector `my-app` to `my-heroes` - -:marked -+makeExample('toh-5/dart/lib/heroes_component.dart', 'heroes-component-renaming', 'lib/heroes_component.dart (showing renamings only)')(format=".") - -:marked - ## Create *AppComponent* - The new `AppComponent` will be the application shell. - It will have some navigation links at the top and a display area below for the pages we navigate to. - - The initial steps are: - - * create a new file named `app_component.dart`. - * define an `AppComponent` class. - * expose an application `title` property. - * add the `@Component` metadata annotation above the class with a `my-app` selector. - * add a template with `

` tags surrounding a binding to the `title` property. - * add the `` tags to the template so we still see the heroes. - * add the `HeroesComponent` to the `directives` list so Angular recognizes the `` tags. - * add the `HeroService` to the `providers` list because we'll need it in every other view. - * add the supporting `import` statements. - - Our first draft looks like this: -+makeExample('toh-5/dart/lib/app_component_1.dart', null, 'lib/app_component.dart (v1)') -:marked -.callout.is-critical - header Remove HeroService from the HeroesComponent providers +block angular-router :marked - Go back to the `HeroesComponent` and **remove the `HeroService`** from its `providers` list. - We are *promoting* this service from the `HeroesComponent` to the `AppComponent`. - We ***do not want two copies*** of this service at two different levels of our app. -:marked - The app still runs and still displays heroes. - Our refactoring of `AppComponent` into a new `AppComponent` and a `HeroesComponent` worked! - We have done no harm. + The Angular router is a combination of multiple services + (`ROUTER_PROVIDERS`), multiple directives (`ROUTER_DIRECTIVES`), and a + configuration annotation (`RouteConfig`). We'll get them all by importing + the router library: -:marked - ## Add Routing + +makeExcerpt('app/app.component.ts (router imports)', 'import-router') - We're ready to take the next step. - Instead of displaying heroes automatically, we'd like to show them *after* the user clicks a button. - In other words, we'd like to navigate to the list of heroes. - - We'll need the Angular *Component Router*. - - ### Add a base tag - -:marked - First, edit `index.html` and add `` at the top of the `` section. -+makeExample('toh-5/dart/web/index.html', 'base-href', 'index.html (base href)')(format=".") -.callout.is-important - header base href is essential :marked - See the *base href* section of the [Router](../guide/router.html#!#base-href) chapter to learn why this matters. -:marked - ### Make the router available + ### Make the router available - Not all apps need routing, which is why the Angular *Component Router* is in a separate, optional module library. + Not all apps need routing, which is why the Angular *Component Router* is + in a separate, optional library module. - The Angular router is a combination of multiple services (`ROUTER_PROVIDERS`), multiple directives (`ROUTER_DIRECTIVES`), - and a configuration annotation (`RouteConfig`). We'll get them all by importing `router.dart`: -+makeExample('toh-5/dart/lib/app_component_2.dart', 'import-router', 'lib/app_component.dart (router imports)')(format=".") + Like for any service, we make router services available to the application + by adding them to the `providers` list. Let's update the `directives` and + `providers` lists to include the router assets: -:marked - The *Component Router* is a service. Like any service, we have to make it - available to the application by adding it to the `providers` list. + +makeExcerpt('app/app.component.ts (excerpt)', 'directives-and-providers') - Let's update the `directives` and `providers` metadata lists to *include* the router assets. -+makeExample('toh-5/dart/lib/app_component_2.dart', 'directives-and-providers', 'lib/app_component.dart (directives and providers)')(format=".") -:marked - Notice that we also removed the `HeroesComponent` from the `directives` list. - `AppComponent` no longer shows heroes; that will be the router's job. - We'll soon remove `` from the template too. - - ### Add and configure the router - - The `AppComponent` doesn't have a router yet. We'll use the `@RouteConfig` annotation to simultaneously - (a) assign a router to the component and (b) configure that router with *routes*. - - *Routes* tell the router which views to display when a user clicks a link or - pastes a URL into the browser address bar. - - Let's define our first route, a route to the `HeroesComponent`. -+makeExample('toh-5/dart/lib/app_component_2.dart', 'route-config', 'lib/app_component.dart (RouteConfig for heroes)')(format=".") -:marked - `@RouteConfig` takes a list of *route definitions*. - We have only one route definition at the moment but rest assured, we'll add more. - - This *route definition* has three parts: - * **path**: the router matches this route's path to the URL in the browser address bar (`/heroes`). - - * **name**: the official name of the route; it *must* begin with a capital letter to avoid confusion with the *path* (`Heroes`). - - * **component**: the component that the router should create when navigating to this route (`HeroesComponent`). - -.l-sub-section :marked - Learn more about defining routes with @RouteConfig in the [Routing](../guide/router.html) chapter. -:marked - ### Router Outlet + Notice that we also removed the `HeroesComponent` from the `directives` list. + `AppComponent` no longer shows heroes; that will be the router's job. + We'll soon remove `` from the template too. - If we paste the path, `/heroes`, into the browser address bar, - the router should match it to the `'Heroes'` route and display the `HeroesComponent`. - But where? - - We have to ***tell it where*** by adding `` marker tags to the bottom of the template. - `RouterOutlet` is one of the `ROUTER_DIRECTIVES`. - The router displays each component immediately below the `` as we navigate through the application. - - ### Router Links - We don't really expect users to paste a route URL into the address bar. - We add an anchor tag to the template which, when clicked, triggers navigation to the `HeroesComponent`. - - The revised template looks like this: -+makeExample('toh-5/dart/lib/app_component_2.dart', 'template', 'lib/app_component.dart (template v1)')(format=".") -:marked - Notice the `[routerLink]` binding in the anchor tag. - We bind the `RouterLink` directive (another of the `ROUTER_DIRECTIVES`) to a list - that tells the router where to navigate when the user clicks the link. - - We define a *routing instruction* with a *link parameters list*. - The list only has one element in our little sample, the quoted ***name* of the route** to follow. - Looking back at the route configuration, we confirm that `'Heroes'` is the name of the route to the `HeroesComponent`. -.l-sub-section +block router-config-intro :marked - Learn about the *link parameters list* in the [Routing](../guide/router.html#link-parameters-array) chapter. -:marked - Refresh the browser. We see only the app title. We don't see the heroes list. -.l-sub-section + ### Configure routes and add the router + + The `AppComponent` doesn't have a router yet. We'll use the `@RouteConfig` + annotation to simultaneously: + + - Assign a router to the component + - Configure that router with *routes* + +block routerLink :marked - The browser's address bar shows `/`. - The route path to `HeroesComponent` is `/heroes`, not `/`. - We don't have a route that matches the path `/`, so there is nothing to show. - That's something we'll want to fix. -:marked - We click the "Heroes" navigation link, the browser bar updates to `/heroes`, - and now we see the list of heroes. We are navigating at last! + Notice the `[routerLink]` binding in the anchor tag. + We bind the `RouterLink` directive (another of the `ROUTER_DIRECTIVES`) to a list + that tells the router where to navigate when the user clicks the link. - At this stage, our `AppComponent` looks like this. -+makeExample('toh-5/dart/lib/app_component_2.dart',null, 'lib/app_component.dart (v2)') -:marked - The *AppComponent* is now attached to a router and displaying routed views. - For this reason and to distinguish it from other kinds of components, - we call this type of component a *Router Component*. + We define a *routing instruction* with a *link parameters list*. + The list only has one element in our little sample, the quoted ***name* of the route** to follow. + Looking back at the route configuration, we confirm that `'Heroes'` is the name of the route to the `HeroesComponent`. + .l-sub-section + :marked + Learn about the *link parameters list* + in the [Routing](../guide/router.html#link-parameters-array) chapter. - -:marked - ## Add a *Dashboard* - Routing only makes sense when we have multiple views. We need another view. - - Create a placeholder `DashboardComponent` that gives us something to navigate to and from. -+makeExample('toh-5/dart/lib/dashboard_component_1.dart',null, 'lib/dashboard_component.dart (v1)')(format=".") -:marked - We’ll come back and make it more useful later. - - ### Configure the dashboard route - Go back to `app_component.dart` and teach it to navigate to the dashboard. - - Import the `DashboardComponent` so we can reference it in the dashboard route definition. - - Add the following `'Dashboard'` route definition to the `@RouteConfig` list of definitions. -+makeExample('toh-5/dart/lib/app_component.dart','dashboard-route', 'lib/app_component.dart (Dashboard route)')(format=".") -.l-sub-section +block redirect-vs-use-as-default :marked - **useAsDefault** - - We want the app to show the dashboard when it starts and - we want to see a nice URL in the browser address bar that says `/dashboard`. - Remember that the browser launches with `/` in the address bar. - We don't have a route for that path and we'd rather not create one. - - Fortunately we can add the `useAsDefault: true` property to the *route definition* and the + We don't need a route definition for that. Instead, + we add `useAsDefault: true` to the dashboard *route definition* and the router will display the dashboard when the browser URL doesn't match an existing route. -:marked - Finally, add a dashboard navigation link to the template, just above the *Heroes* link. -+makeExample('toh-5/dart/lib/app_component.dart','template', 'lib/app_component.dart (template)')(format=".") -.l-sub-section +block templateUrl-path-resolution :marked - We nestled the two links within `