From 25dc59daac88255989b1f7b6ddc0e3e5db9150ca Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 15 Jun 2016 14:58:05 -0700 Subject: [PATCH] docs(toh-3/dart): copyedits (#1637) --- .../toh-4/dart/lib/app_component.dart | 11 +-- .../toh-4/dart/lib/app_component_1.dart | 20 ++-- .../toh-4/dart/lib/hero_detail_component.dart | 4 +- .../toh-4/dart/lib/hero_service.dart | 8 +- .../toh-4/dart/lib/hero_service_1.dart | 18 ++-- .../_examples/toh-4/dart/lib/mock_heroes.dart | 1 - .../docs/_examples/toh-4/dart/web/main.dart | 4 +- .../docs/_examples/toh-4/dart/web/main_1.dart | 4 +- public/docs/dart/latest/tutorial/toh-pt4.jade | 91 ++++++++++--------- 9 files changed, 74 insertions(+), 87 deletions(-) diff --git a/public/docs/_examples/toh-4/dart/lib/app_component.dart b/public/docs/_examples/toh-4/dart/lib/app_component.dart index 6a3555e3ae..26e3e9fa50 100644 --- a/public/docs/_examples/toh-4/dart/lib/app_component.dart +++ b/public/docs/_examples/toh-4/dart/lib/app_component.dart @@ -8,7 +8,6 @@ import 'hero.dart'; import 'hero_detail_component.dart'; // #docregion hero-service-import import 'hero_service.dart'; - // #enddocregion hero-service-import @Component( @@ -92,17 +91,17 @@ class AppComponent implements OnInit { AppComponent(this._heroService); -// #docregion get-heroes - getHeroes() async { + // #docregion get-heroes + Future getHeroes() async { heroes = await _heroService.getHeroes(); } -// #enddocregion get-heroes + // #enddocregion get-heroes - ngOnInit() { + void ngOnInit() { getHeroes(); } - onSelect(Hero hero) { + void onSelect(Hero hero) { selectedHero = hero; } } diff --git a/public/docs/_examples/toh-4/dart/lib/app_component_1.dart b/public/docs/_examples/toh-4/dart/lib/app_component_1.dart index 7f23cf89fd..99953d1470 100644 --- a/public/docs/_examples/toh-4/dart/lib/app_component_1.dart +++ b/public/docs/_examples/toh-4/dart/lib/app_component_1.dart @@ -5,9 +5,7 @@ import 'package:angular2/core.dart'; // #enddocregion on-init import 'hero.dart'; import 'hero_detail_component.dart'; -// #docregion hero-service-import import 'hero_service_1.dart'; -// #enddocregion hero-service-import // Testable but never shown @Component( @@ -21,7 +19,7 @@ import 'hero_service_1.dart'; directives: const [HeroDetailComponent], // #docregion providers providers: const [HeroService]) -// #enddocregion providers + // #enddocregion providers // #docregion on-init class AppComponent implements OnInit { // #enddocregion on-init @@ -38,27 +36,25 @@ class AppComponent implements OnInit { final HeroService _heroService; AppComponent(this._heroService); // #enddocregion ctor + // #docregion getHeroes - getHeroes() { - //#docregion get-heroes + void getHeroes() { + // #docregion get-heroes heroes = _heroService.getHeroes(); // #enddocregion get-heroes } // #enddocregion getHeroes - // #docregion ng-on-init - // #docregion on-init - ngOnInit() { + // #docregion ng-on-init, on-init + void ngOnInit() { // #enddocregion on-init getHeroes(); // #docregion on-init } - // #enddocregion on-init - // #enddocregion ng-on-init + // #enddocregion ng-on-init, on-init - onSelect(Hero hero) { + void onSelect(Hero hero) { selectedHero = hero; } // #docregion on-init } -// #enddocregion on-init diff --git a/public/docs/_examples/toh-4/dart/lib/hero_detail_component.dart b/public/docs/_examples/toh-4/dart/lib/hero_detail_component.dart index 8a6144ddfb..9b9ede32fe 100644 --- a/public/docs/_examples/toh-4/dart/lib/hero_detail_component.dart +++ b/public/docs/_examples/toh-4/dart/lib/hero_detail_component.dart @@ -14,8 +14,8 @@ import 'hero.dart'; - ''', - inputs: const ['hero']) + ''') class HeroDetailComponent { + @Input() Hero hero; } diff --git a/public/docs/_examples/toh-4/dart/lib/hero_service.dart b/public/docs/_examples/toh-4/dart/lib/hero_service.dart index f3f4f85233..30f25f5931 100644 --- a/public/docs/_examples/toh-4/dart/lib/hero_service.dart +++ b/public/docs/_examples/toh-4/dart/lib/hero_service.dart @@ -12,15 +12,15 @@ import 'mock_heroes.dart'; class HeroService { // #docregion get-heroes Future> getHeroes() async => mockHeroes; - // #enddocregion get-heroes - // #enddocregion just-get-heroes + // #enddocregion get-heroes, just-get-heroes + // #enddocregion // See the "Take it slow" appendix // #docregion get-heroes-slowly Future> getHeroesSlowly() { return new Future.delayed(const Duration(seconds: 2), () => mockHeroes); } // #enddocregion get-heroes-slowly + // #docregion // #docregion just-get-heroes } -// #enddocregion just-get-heroes -// #enddocregion + diff --git a/public/docs/_examples/toh-4/dart/lib/hero_service_1.dart b/public/docs/_examples/toh-4/dart/lib/hero_service_1.dart index c95aeea7f8..87e11177d8 100644 --- a/public/docs/_examples/toh-4/dart/lib/hero_service_1.dart +++ b/public/docs/_examples/toh-4/dart/lib/hero_service_1.dart @@ -10,19 +10,13 @@ import 'mock_heroes.dart'; // #docregion getHeroes-stub @Injectable() class HeroService { -// #enddocregion getHeroes-stub -// #enddocregion empty-class -// #enddocregion final + // #enddocregion getHeroes-stub, empty-class, final /* -// #docregion getHeroes-stub + // #docregion getHeroes-stub List getHeroes() {} -// #enddocregion getHeroes-stub - */ -// #docregion final + // #enddocregion getHeroes-stub + */ + // #docregion final List getHeroes() => mockHeroes; -// #docregion empty-class -// #docregion getHeroes-stub + // #docregion empty-class, getHeroes-stub } -// #enddocregion getHeroes-stub -// #enddocregion empty-class -// #enddocregion final diff --git a/public/docs/_examples/toh-4/dart/lib/mock_heroes.dart b/public/docs/_examples/toh-4/dart/lib/mock_heroes.dart index 645aa56c25..b67fe9be21 100644 --- a/public/docs/_examples/toh-4/dart/lib/mock_heroes.dart +++ b/public/docs/_examples/toh-4/dart/lib/mock_heroes.dart @@ -13,4 +13,3 @@ final List mockHeroes = [ new Hero(19, 'Magma'), new Hero(20, 'Tornado') ]; -// #enddocregion diff --git a/public/docs/_examples/toh-4/dart/web/main.dart b/public/docs/_examples/toh-4/dart/web/main.dart index 81c22cd91d..ed2bb7156f 100644 --- a/public/docs/_examples/toh-4/dart/web/main.dart +++ b/public/docs/_examples/toh-4/dart/web/main.dart @@ -1,9 +1,7 @@ -// #docregion pt1 import 'package:angular2/platform/browser.dart'; import 'package:angular2_tour_of_heroes/app_component.dart'; -main() { +void main() { bootstrap(AppComponent); } -// #enddocregion pt1 diff --git a/public/docs/_examples/toh-4/dart/web/main_1.dart b/public/docs/_examples/toh-4/dart/web/main_1.dart index 7d3d59c77d..76e71e02a2 100644 --- a/public/docs/_examples/toh-4/dart/web/main_1.dart +++ b/public/docs/_examples/toh-4/dart/web/main_1.dart @@ -1,9 +1,7 @@ -// #docregion pt1 import 'package:angular2/platform/browser.dart'; import 'package:angular2_tour_of_heroes/app_component_1.dart'; -main() { +void main() { bootstrap(AppComponent); } -// #enddocregion pt1 diff --git a/public/docs/dart/latest/tutorial/toh-pt4.jade b/public/docs/dart/latest/tutorial/toh-pt4.jade index e84d25db18..b6d090ba8e 100644 --- a/public/docs/dart/latest/tutorial/toh-pt4.jade +++ b/public/docs/dart/latest/tutorial/toh-pt4.jade @@ -13,7 +13,7 @@ include ../_util-fns It also makes it easier to unit test the component with a mock service. Because data services are invariably asynchronous, - we'll finish the chapter with a promise-based version of the data service. + we'll finish the chapter with a **!{_Promise}**-based version of the data service. p Run the #[+liveExampleLink2('', 'toh-4')] for this part. @@ -35,6 +35,7 @@ p Run the #[+liveExampleLink2('', 'toh-4')] for this part. .children .file index.html .file main.dart + .file styles.css .file pubspec.yaml :marked ### Keep the app compiling and running @@ -59,7 +60,7 @@ code-example(language="bash"). First, defining heroes is not the component's job. Second, we can't easily share that list of heroes with other components and views. - We can refactor this hero data acquisition business to a single service that provides heroes and + We can refactor this hero data acquisition business to a single service that provides heroes, and share that service with all components that need heroes. ### Create the HeroService @@ -67,12 +68,12 @@ code-example(language="bash"). .l-sub-section :marked We've adopted a convention in which we spell the name of a service in lowercase followed by `_service`. - If the service name were multi-word, we'd spell the base filename with lower underscore case (AKA "snake_case"). + If the service name were multi-word, we'd spell the base filename in lower underscore case (also called [snake_case](../guide/glossary.html#!#snake_case)). The `SpecialSuperHeroService` would be defined in the `special_super_hero_service.dart` file. :marked We name the class `HeroService`. -+makeExample('toh-4/dart/lib/hero_service_1.dart', 'empty-class', 'hero_service.dart (class)')(format=".") ++makeExample('toh-4/dart/lib/hero_service_1.dart', 'empty-class', 'lib/hero_service.dart (starting point)')(format=".") :marked ### Injectable Services @@ -91,7 +92,7 @@ code-example(language="bash"). :marked ### Getting Heroes Add a `getHeroes` method stub. -+makeExample('toh-4/dart/lib/hero_service_1.dart', 'getHeroes-stub', 'hero_service.dart (getHeroes stub)')(format=".") ++makeExample('toh-4/dart/lib/hero_service_1.dart', 'getHeroes-stub', 'lib/hero_service.dart (getHeroes stub)')(format=".") :marked We're holding back on the implementation for a moment to make an important point. @@ -109,31 +110,31 @@ code-example(language="bash"). We already have mock `Hero` data sitting in the `AppComponent`. It doesn't belong there. It doesn't belong *here* either. We'll move the mock data to its own file. - Cut the the `mockHeroes` list from `app_component.dart` and paste it to a new file in the `lib` folder named `mock_heroes.dart`. + Cut the `mockHeroes` list from `app_component.dart` and paste it to a new file in the `lib` folder named `mock_heroes.dart`. We copy the `import 'hero.dart'` statement as well because the heroes list uses the `Hero` class. -+makeExample('toh-4/dart/lib/mock_heroes.dart', null, 'mock_heroes.dart (Heroes list)') ++makeExample('toh-4/dart/lib/mock_heroes.dart', null, 'lib/mock_heroes.dart') :marked Meanwhile, back in `app_component.dart` where we cut away the `mockHeroes` list, we leave behind an uninitialized `heroes` property: -+makeExample('toh-4/dart/lib/app_component_1.dart', 'heroes-prop', 'app_component.dart (heroes property)')(format=".") ++makeExample('toh-4/dart/lib/app_component_1.dart', 'heroes-prop', 'lib/app_component.dart (heroes property)')(format=".") :marked ### Return Mocked Heroes Back in the `HeroService` we import the mock `mockHeroes` and return it from the `getHeroes` method. Our `HeroService` looks like this: -+makeExample('toh-4/dart/lib/hero_service_1.dart', 'final', 'hero_service.dart')(format=".") ++makeExample('toh-4/dart/lib/hero_service_1.dart', 'final', 'lib/hero_service.dart')(format=".") :marked ### Use the Hero Service We're ready to use the `HeroService` in other components starting with our `AppComponent`. We begin, as usual, by importing the thing we want to use, the `HeroService`. -+makeExample('toh-4/dart/lib/app_component.dart', 'hero-service-import', 'app_component.dart (import HeroService)')(format=".") ++makeExcerpt('toh-4/dart/lib/app_component.dart', 'hero-service-import') :marked Importing the service allows us to *reference* it in our code. How should the `AppComponent` acquire a runtime concrete `HeroService` instance? ### Do we *new* the *HeroService*? No way! - We could create a new instance of the `HeroService` with "new" like this: + We could create a new instance of the `HeroService` with `new` like this: +makeExample('toh-4/dart/lib/app_component_1.dart', 'new-service')(format=".") :marked That's a bad idea for several reasons including @@ -143,7 +144,7 @@ code-example(language="bash"). we'll have to find every place we create the service and fix it. Running around patching code is error prone and adds to the test burden. - * We create a new service each time we use "new". + * We create a new service each time we use `new`. What if the service should cache heroes and share that cache with others? We couldn't do that. @@ -166,7 +167,7 @@ code-example(language="bash"). 1. We add to the component's `providers` metadata. Here are the property and the constructor: -+makeExample('toh-4/dart/lib/app_component_1.dart', 'ctor', 'app_component.dart (constructor)')(format='.') ++makeExample('toh-4/dart/lib/app_component_1.dart', 'ctor', 'lib/app_component.dart (constructor)')(format='.') :marked The constructor does nothing except set the `_heroService` property. The `HeroService` type of `_heroService` @@ -186,14 +187,14 @@ code-example(language="bash"). :marked The *injector* does not know yet how to create a `HeroService`. If we ran our code now, Angular would fail with an error: -code-example(format="." language="html"). +code-example(format="nocode"). EXCEPTION: No provider for HeroService! (AppComponent -> HeroService) :marked We have to teach the *injector* how to make a `HeroService` by registering a `HeroService` **provider**. Do that by adding the following `providers` parameter to the bottom of the component metadata in the `@Component` annotation. -+makeExample('toh-4/dart/lib/app_component_1.dart', 'providers', 'app_component.dart (providing HeroService)')(format=".") ++makeExcerpt('toh-4/dart/lib/app_component_1.dart', 'providers') :marked The `providers` parameter tells Angular to create a fresh instance of the `HeroService` when it creates a new `AppComponent`. The `AppComponent` can use that service to get heroes and so can every child component of its component tree. @@ -207,7 +208,7 @@ code-example(format="." language="html"). If the `HeroDetailComponent` needed its parent component's `HeroService`, it would ask Angular to inject the service into its constructor which would look just like the one for `AppComponent`: - +makeExample('toh-4/dart/lib/app_component_1.dart', 'ctor', 'hero_detail_component.dart (constructor)')(format=".") + +makeExample('toh-4/dart/lib/app_component_1.dart', 'ctor', 'lib/hero_detail_component.dart (constructor)')(format=".") :marked The `HeroDetailComponent` must *not* repeat its parent's `providers` list! Guess [why](#shadow-provider). @@ -221,7 +222,7 @@ code-example(format="." language="html"). +makeExample('toh-4/dart/lib/app_component_1.dart', 'get-heroes')(format=".") :marked We don't really need a dedicated method to wrap one line. We write it anyway: -+makeExample('toh-4/dart/lib/app_component_1.dart', 'getHeroes', 'app_component.dart (getHeroes)')(format=".") ++makeExcerpt('toh-4/dart/lib/app_component_1.dart', 'getHeroes') :marked @@ -248,18 +249,19 @@ code-example(format="." language="html"). Learn more about lifecycle hooks in the [Lifecycle Hooks](../guide/lifecycle-hooks.html) chapter. :marked Here's the essential outline for the `OnInit` interface: -+makeExample('toh-4/dart/lib/app_component_1.dart', 'on-init', 'app_component.dart (OnInit protocol)')(format=".") ++makeExample('toh-4/dart/lib/app_component_1.dart', 'on-init', 'lib/app_component.dart (ngOnInit stub)')(format=".") :marked We write an `ngOnInit` method with our initialization logic inside and leave it to Angular to call it at the right time. In our case, we initialize by calling `getHeroes`. -+makeExample('toh-4/dart/lib/app_component_1.dart', 'ng-on-init', 'app_component.dart (OnInit protocol)')(format=".") ++makeExcerpt('toh-4/dart/lib/app_component_1.dart', 'ng-on-init') :marked Our application should be running as expected, showing a list of heroes and a hero detail view when we click on a hero name. We're getting closer. But something isn't quite right. - ## Async Services and Futures + + ## Async Services and !{_Promise} Our `HeroService` returns a list of mock heroes immediately. Its `getHeroes` signature is synchronous +makeExample('toh-4/dart/lib/app_component_1.dart', 'get-heroes')(format=".") @@ -273,42 +275,42 @@ code-example(format="." language="html"). We'll have to use some kind of asynchronous technique and that will change the signature of our `getHeroes` method. - We'll use *futures*. + We'll use *!{_Promise}s*. - ### The Hero Service returns a future + ### The Hero Service returns a !{_Promise} - We ask an asynchronous service to do some work and give us the result in the future. - The service does that work (somewhere) and eventually it updates the future with the results of the work or an error. + We ask an asynchronous service to do some work and give us the result in the !{_Promise}. + The service does that work (somewhere) and eventually it updates the !{_Promise} with the results of the work or an error. .l-sub-section :marked - We are simplifying. Learn about Futures in the tutorial + We are simplifying. Learn about !{_Promise}s in the tutorial [Asynchronous Programming: Futures](https://www.dartlang.org/docs/tutorials/futures/). :marked - Update the `HeroService` with this future-returning `getHeroes` method: -+makeExample('toh-4/dart/lib/hero_service.dart', 'get-heroes', 'hero_service.dart (getHeroes)')(format=".") + Update the `HeroService` with this !{_Promise}-returning `getHeroes` method: ++makeExample('toh-4/dart/lib/hero_service.dart', 'get-heroes', 'lib/hero_service.dart (excerpt)')(format=".") :marked We're still mocking the data. We're simulating the behavior of an ultra-fast, zero-latency server, - by returning a future that will quickly resolve with our mock heroes as the result. + by returning a !{_Promise} that will quickly resolve with our mock heroes as the result. .l-sub-section :marked Marking the method's body with `async` makes the method immediately return a `Future` object. - That future later completes with the method's return value. + That !{_Promise} later completes with the method's return value. For more information on async functions, see [Declaring async functions](https://www.dartlang.org/docs/dart-up-and-running/ch02.html#async) in the Dart language tour. :marked - ### Act on the Futures + ### Act on the !{_Promise} Returning to the `AppComponent` and its `getHeroes` method, we see that it still looks like this: -+makeExample('toh-4/dart/lib/app_component_1.dart', 'getHeroes', 'app_component.dart (getHeroes - old)')(format=".") ++makeExample('toh-4/dart/lib/app_component_1.dart', 'getHeroes', 'lib/app_component.dart (getHeroes - old)')(format=".") :marked - As a result of our change to `HeroService`, we're now setting `heroes` to a future rather than a list of heroes. + As a result of our change to `HeroService`, we're now setting `heroes` to a !{_Promise} rather than a list of heroes. - We have to change our implementation to *act on the future when it resolves*. - We can *await* the future to resolve, and then display the heroes: -+makeExample('toh-4/dart/lib/app_component.dart', 'get-heroes', 'app_component.dart (getHeroes - revised)')(format=".") + We have to change our implementation to *act on the !{_Promise} when it resolves*. + We can *await* for the !{_Promise} to resolve, and then display the heroes: ++makeExample('toh-4/dart/lib/app_component.dart', 'get-heroes', 'lib/app_component.dart (getHeroes - revised)')(format=".") :marked - Our code waits until the future completes, and then + Our code waits until the !{_Promise} completes, and then sets the component's `heroes` property to the list of heroes returned by the service. That's all there is to it! Our app should still be running, still showing a list of heroes, and still @@ -334,6 +336,7 @@ code-example(format="." language="html"). .children .file index.html .file main.dart + .file styles.css .file pubspec.yaml :marked Here are the code files we discussed in this chapter. @@ -351,11 +354,11 @@ code-example(format="." language="html"). ## The Road We’ve Travelled Let’s take stock of what we’ve built. - * We created a service class that can be shared by many components - * We used the `ngOnInit` Lifecycle Hook to get our heroes when our `AppComponent` activates - * We defined our `HeroService` as a provider for our `AppComponent` - * We created mock hero data and imported them into our service - * We designed our service to return a future and our component to get our data from the future + * We created a service class that can be shared by many components. + * We used the `ngOnInit` Lifecycle Hook to get our heroes when our `AppComponent` activates. + * We defined our `HeroService` as a provider for our `AppComponent`. + * We created mock hero data and imported them into our service. + * We designed our service to return a !{_Promise} and our component to get our data from the !{_Promise}. ### The Road Ahead @@ -373,10 +376,10 @@ code-example(format="." language="html"). We can simulate a slow connection. Add the following `getHeroesSlowly` method to the `HeroService`: -+makeExample('toh-4/dart/lib/hero_service.dart', 'get-heroes-slowly', 'hero_service.dart (getHeroesSlowly)')(format=".") ++makeExample('toh-4/dart/lib/hero_service.dart', 'get-heroes-slowly', 'lib/hero_service.dart (getHeroesSlowly)')(format=".") :marked - Like `getHeroes`, it also returns a future. - But this future waits 2 seconds before resolving the future with mock heroes. + Like `getHeroes`, it also returns a !{_Promise}. + But this !{_Promise} waits 2 seconds before resolving the !{_Promise} with mock heroes. Back in the `AppComponent`, replace `_heroService.getHeroes` with `_heroService.getHeroesSlowly`