docs(toh-pt6): add observables - ward's changes

Author: wardbell

public/docs/_examples/toh-6/ts/app/hero-search.component.html

@@ -1,10 +1,11 @@
 <!-- #docregion -->
 <div id="search-component">
-  <h4>Hero Search</h4>  
-  <input #searchBox id="search-box" (keyup)="search.next(searchBox.value)" />    
+  <h4>Hero Search</h4>
+  <input #searchBox id="search-box" (keyup)="search.next(searchBox.value)" />
   <div>
-    <div class="search-result" (click)="gotoDetail(hero)" *ngFor="let hero of heroes">
+    <div *ngFor="let hero of heroes | async"
+         (click)="gotoDetail(hero)" class="search-result" >
       {{hero.name}}
     </div>
   </div>
-</div>
+</div>

public/docs/_examples/toh-6/ts/app/hero-search.component.ts

@@ -13,25 +13,37 @@ import { Hero } from './hero';
   providers: [HeroSearchService]
 })
 export class HeroSearchComponent implements OnInit {
+  // #docregion subject
   search = new Subject<string>();
-  heroes: Hero[] = [];
+  // #enddocregion subject
 
-  constructor(private _heroSearchService: HeroSearchService, private _router: Router) {}
+  heroes: Observable<Hero>;
+
+  constructor(
+    private heroSearchService: HeroSearchService,
+    private router: Router) {}
 
-  gotoDetail(hero: Hero) {
-    let link = ['/detail', hero.id];
-    this._router.navigate(link);
-  }
 
   // #docregion search
   ngOnInit() {
-    this.search.asObservable()
-               .debounceTime(300)
-               .distinctUntilChanged()
-               .switchMap(term => term ? this._heroSearchService.search(term)
-                                       : Observable.of([]))
-               .subscribe(result => this.heroes = result,
-                                    error => console.log(error));
+    this.heroes = this.search
+      .asObservable()
+      .debounceTime(300)
+      .distinctUntilChanged()
+
+      .switchMap(term => term
+        ? this.heroSearchService.search(term)
+        : Observable.of<Hero[]>([]))
+
+      .catch(error => {
+        console.log(error);
+        return Observable.throw(error);
+      });
   }
   // #enddocregion search
+
+  gotoDetail(hero: Hero) {
+    let link = ['/detail', hero.id];
+    this.router.navigate(link);
+  }
 }

public/docs/_examples/toh-6/ts/app/hero-search.service.ts

@@ -2,16 +2,18 @@
 import { Injectable }     from '@angular/core';
 import { Http, Response } from '@angular/http';
 
+import { Hero }           from './hero';
+
 @Injectable()
 export class HeroSearchService {
 
-  constructor(private _http: Http) {}
+  constructor(private http: Http) {}
 
   // #docregion observable-search
   search(term: string) {
-    return this._http
+    return this.http
                .get(`app/heroes/?name=${term}+`)
-               .map((r: Response) => r.json().data);
+               .map((r: Response) => r.json().data as Hero[]);
   }
   // #enddocregion observable-search
 }

public/docs/_examples/toh-6/ts/app/rxjs-operators.ts

@@ -1,8 +1,10 @@
 // #docregion
+import 'rxjs/add/observable/of';
+
+import 'rxjs/add/operator/catch';
+import 'rxjs/add/operator/debounceTime';
+import 'rxjs/add/operator/distinctUntilChanged';
+import 'rxjs/add/operator/do';
+import 'rxjs/add/operator/filter';
 import 'rxjs/add/operator/map';
 import 'rxjs/add/operator/switchMap';
-import 'rxjs/add/operator/filter';
-import 'rxjs/add/operator/do';
-import 'rxjs/add/operator/distinctUntilChanged';
-import 'rxjs/add/operator/debounceTime';
-import 'rxjs/add/observable/of';

public/docs/ts/latest/tutorial/toh-pt6.jade

@@ -131,7 +131,7 @@ block get-heroes-details
   :marked
     The Angular `http.get` returns an RxJS `Observable`.
     *Observables* are a powerful way to manage asynchronous data flows.
-    We'll learn about `Observables` *later*.
+    We'll learn about [Observables](#observables) later in this chapter.
 
     For *now* we get back on familiar ground by immediately converting that `Observable` to a `Promise` using the `toPromise` operator.
   +makeExample('toh-6/ts/app/hero.service.ts', 'to-promise')(format=".")
@@ -361,41 +361,69 @@ block review
 :marked
   ## Observables
 
-  In this section we discuss `Observables` as an alternative to promises when processing http calls.
+  Each `Http` method  returns an `Observable` of HTTP `Response` objects.
 
-  `Http` calls return RxJS observables by default, but so far we've been hiding that by converting the observable to a promise by calling `toPromise`.
+  Our `HeroService` converts that `Observable` into a `Promise` and returns the promise to the caller.
+  In this section we learn to return the `Observable` directly and discuss when and why that might be 
+  a good thing to do.
 
-  Observables and promises are both great for processing http calls, but as we will see, the observables api is much richer. 
+  ### Background
+  An *observable* is a stream of events that we can process with array-like operators.
 
-  `RxJs` offers a wide variety of operators that we can use to manage event flows.     
+  Angular core has basic support for observables. We developers augment that support with
+  operators and extensions from the [RxJS Observables](http://reactivex.io/rxjs/) library.
+  We'll see how shortly.
 
-  In this section we will discuss how to use some of these operators to build a type-to-search filter where we can search for heroes by name. 
+  Recall that our `HeroService` quickly chained the `toPromise` operator to the `Observable` result of `http.get`.
+  That operator converted the `Observable` into a `Promise` and we passed that promise back to the caller.
+  
+  Converting to a promise is often a good choice. We typically ask `http` to fetch a single chunk of data. 
+  When we receive the data, we're done.
+  A single result in the form of a promise is easy for the calling component to consume 
+  and it helps that promises are widely understood by JavaScript programmers.
+
+  But requests aren't always "one and done". We may start one request, 
+  then cancel it, and make a different request ... before the server has responded to the first request.
+  Such a _request-cancel-new-request_ sequence is difficult to implement with *promises*. 
+  It's easy with *observables* as we'll see.
+  
+  ### Search-by-name example
+  We're going to add a *hero search* feature to the Tour of Heroes.
+  As the user types a name into a search box, we'll make repeated http requests for heroes filtered by that name.
 
-  We start by creating `HeroSearchService`, a simple service for sending search queries to our api.
+  We start by creating `HeroSearchService` that sends search queries to our server's web api.
 
 +makeExample('toh-6/ts/app/hero-search.service.ts', null, 'app/hero-search.service.ts')(format=".")
 
 :marked
-  The http call in `HeroSearchService` is not that different from our previous http calls, but we no longer call `toPromise`. This means we will return an observable instead of a promise.
+  The `http.get` call in `HeroSearchService` is similar to the `http.get` call in the `HeroService`.
+  The notable difference: we no longer call `toPromise`. 
+  We simply return the *observable* instead.
 
-  Now, let's implement our search component `HeroSearchComponent`.  
-
-+makeTabs(
-  `toh-6/ts/app/hero-search.component.ts,
-   toh-6/ts/app/hero-search.component.html`,
-  null,
-  `hero-search.component.ts,
-   hero-search.component.html`
-)   
+  ### HeroSearchComponent
+  Let's create a new `HeroSearchComponent` that calls this new `HeroSearchService`. 
 
+  The component template is simple - just a textbox and a list of matching search results.
++makeExample('toh-6/ts/app/hero-search.component.html', null,'hero-search.component.html')
 :marked
-  The `HeroSearchComponent` UI is simple - just a textbox and a list of matching search results. 
-  
-  To keep track of text changes in the search box we are using an RxJs `Subject`.
+  As the user types in the search box, a *keyup* event binding calls `search.next` with the new search box value.
 
-  Observables are great for managing event streams. In our example we will actually be dealing with two different types of event streams:
+  The componen'ts data bound `search` property returns a `Subject`. 
+  A `Subject` is a producer of an _observable_ event stream.
+  Each call to `search.next` puts a new string into this subject's _observable_ stream.
+
+  Create a `HeroSearchComponent` as follows.
++makeExample('toh-6/ts/app/hero-search.component.ts', null,'hero-search.component.ts')
+:marked
+  Scroll down to where we create the `search` subject.
++makeExample('toh-6/ts/app/hero-search.component.ts', 'subject')
+:marked
+  We're binding to that `search` subject in our template.
+  The user is sending it a stream of strings, the filter criteria for the name search.
 
-  1) Key events from typing into the search textbox
+  A `Subject` is also an `Observable`. 
+  We're going to access that `Observable` and add operators to that turn the stream
+  of filter strings into a stream of http search results.
 
   2) Results from http calls based on values entered in the search textbox
 
@@ -539,4 +567,4 @@ block file-summary
     hero-search.component.ts,
     hero-search.service.html,
     rxjs-operators.ts`
-) 
+)