docs(add observables to TOH http)

e2e

prose

tweaks

Author: thelgevold

public/docs/_examples/toh-6/e2e-spec.js

@@ -21,10 +21,31 @@ describe('TOH Http Chapter', function () {
 
       addButton: element.all(by.buttonText('Add New Hero')).get(0),
 
-      heroDetail: element(by.css('my-app my-hero-detail'))
+      heroDetail: element(by.css('my-app my-hero-detail')),
+      
+      searchBox: element(by.css('#search-box')),
+      searchResults: element.all(by.css('.search-result'))
     }
   }
 
+  it('should search for hero and navigate to details view', function() {
+    var page = getPageStruct();
+    
+    return sendKeys(page.searchBox, 'Magneta').then(function () {
+      expect(page.searchResults.count()).toBe(1);
+      var hero = page.searchResults.get(0); 
+      return hero.click();
+    })
+    .then(function() {
+      browser.waitForAngular();
+      var inputEle = page.heroDetail.element(by.css('input'));
+      return inputEle.getAttribute('value');
+    })
+    .then(function(value) {
+      expect(value).toBe('Magneta');      
+    });
+  });
+
   it('should be able to add a hero from the "Heroes" view', function(){
     var page = getPageStruct();
     var heroCount;

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

@@ -2,10 +2,13 @@
 // #docregion
 import { Component } from '@angular/core';
 import { RouteConfig, ROUTER_DIRECTIVES, ROUTER_PROVIDERS } from '@angular/router-deprecated';
-
+// #docregion rxjs-operators
+import './rxjs-operators';
+// #enddocregion rxjs-operators
 import { DashboardComponent }  from './dashboard.component';
 import { HeroesComponent }     from './heroes.component';
 import { HeroDetailComponent } from './hero-detail.component';
+import { HeroSearchComponent } from './hero-search.component';
 import { HeroService }         from './hero.service';
 
 @Component({
@@ -20,7 +23,7 @@ import { HeroService }         from './hero.service';
     <router-outlet></router-outlet>
   `,
   styleUrls: ['app/app.component.css'],
-  directives: [ROUTER_DIRECTIVES],
+  directives: [ROUTER_DIRECTIVES, HeroSearchComponent],
   providers: [
     ROUTER_PROVIDERS,
     HeroService,

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

@@ -9,3 +9,5 @@ <h4>{{hero.name}}</h4>
     </div>
   </div>
 </div>
+<hero-search></hero-search>
+

public/docs/_examples/toh-6/ts/app/dashboard.component.ts

@@ -1,15 +1,18 @@
 // #docplaster
 // #docregion
 import { Component, OnInit } from '@angular/core';
-import { Router }           from '@angular/router-deprecated';
+import { Router }            from '@angular/router-deprecated';
 
 import { Hero }        from './hero';
 import { HeroService } from './hero.service';
+import { HeroSearchComponent } from './hero-search.component';
+
 
 @Component({
   selector: 'my-dashboard',
   templateUrl: 'app/dashboard.component.html',
-  styleUrls: ['app/dashboard.component.css']
+  styleUrls: ['app/dashboard.component.css'],
+  directives: [HeroSearchComponent]
 })
 export class DashboardComponent implements OnInit {
 

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

@@ -0,0 +1,10 @@
+<!-- #docregion -->
+<div id="search-component">
+  <h4>Hero Search</h4>  
+  <input id="search-box" [ngFormControl]="search" />    
+  <div *ngIf="showResult">
+    <div class="search-result" (click)="gotoDetail(hero)" *ngFor="let hero of heroes">
+      {{hero.name}}
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,37 @@
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Control }           from '@angular/common';
+import { Router }            from '@angular/router-deprecated';
+
+import { HeroSearchService } from './hero-search.service';
+import { Hero } from './hero';
+
+@Component({
+  selector: 'hero-search',
+  templateUrl: 'app/hero-search.component.html',
+  providers: [HeroSearchService]    
+})
+export class HeroSearchComponent implements OnInit {
+  search = new Control('');   
+  heroes: Hero[] = [];
+  showResult = true;
+  
+  constructor(private _heroSearchService:HeroSearchService, private _router:Router) {}
+  
+  gotoDetail(hero: Hero) {
+    let link = ['HeroDetail', { id: hero.id }];
+    this._router.navigate(link);
+  }
+  
+  // #docregion search
+  ngOnInit() {
+    this.search.valueChanges
+               .debounceTime(300)
+               .distinctUntilChanged()
+               .do(value => this.showResult = value.length > 0)
+               .filter(value => value.length > 0)  
+               .switchMap(term => this._heroSearchService.search(term))
+               .subscribe(result => this.heroes = result, error => console.log(error));  
+  }
+  // #enddocregion search
+}

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

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

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

@@ -0,0 +1,7 @@
+// #docregion
+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';

public/docs/_examples/toh-6/ts/sample.css

@@ -4,5 +4,19 @@ button.delete-button{
   color:white;
 }
 
+.search-result{
+  border-bottom: 1px solid gray;
+  border-left: 1px solid gray;
+  border-right: 1px solid gray;
+  width:195px;
+  height: 20px;
+  padding: 5px;
+  background-color: white;
+  cursor: pointer;
+}
 
+#search-box{
+  width: 200px;
+  height: 20px;
+}
 

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

@@ -110,7 +110,7 @@ code-example(format="." language="bash").
 
   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` in the next 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=".")
@@ -302,6 +302,103 @@ figure.image-display
 figure.image-display
   img(src='/resources/images/devguide/toh/toh-http.anim.gif' alt="Heroes List Editting w/ HTTP")  
 
+.l-main-section  
+:marked
+ ## Observables
+ 
+ In this section we discuss `Observables` as an alternative to promises when processing http calls.
+
+ `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`.
+ 
+ Observables and promises are both great for processing http calls, but observables differ in that the api for processing events is much richer. 
+ 
+ `RxJs` offers a wide variety of operators that we can use to manage event flows.     
+ 
+ In this chapter 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. 
+ 
+ We start by creating `HeroSearchService`, a simple service for sending search queries to our 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.
+ 
+  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`
+)   
+
+:marked
+  The `HeroSearchComponent` UI is simple - just a textbox and a list of matching search results. 
+  
+  We have bound the `search` property to the textbox as an `ngFormControl` in order to track changes. 
+  
+  Observables are great for managing event streams. In our example we will actually be dealing with two different types of event streams:
+  
+  1) Key events from typing into the search textbox
+  
+  2) Results from http calls based on values entered in the search textbox
+  
+  Although we are dealing with two different streams, we can use `RxJs` operators to combine them into a single stream. 
+  
+  Converging on a single stream is the end game, but let's start by going through the different parts of the observable chain.
+  
++makeExample('toh-6/ts/app/hero-search.component.ts', 'search', 'app/hero-search.component.ts')(format=".")
+
+:marked
+  ### valueChanges
+  `ValueChanges` is an observable that represents text changes triggered by typing into the search textbox. 
+  
+  ### debounceTime(300)
+  By specifying a debounce time of 300 ms we are telling `RxJs` that we only want to be notified of key events after intervals of 300 ms. This is a performance measure meant to prevent us from hitting the api too often with partial search queries.
+  
+  ### distinctUntilChanged
+  `distinctUntilChanged` tells `RxJs` to only react if the value of the textbox actually changed.
+  
+  ### do
+  `do` is an operator for triggering side effects outside the observable chain. In our case we are using it to set a flag to hide the search results if the search textbox is empty.
+  
+  ### filter
+  By specifying a `filter` we are telling `RxJs` to only process search values that meet our filter condition.
+  
+  ### switchMap
+  `switchMap` is where observables from key events and observables from http calls converge on a single observable. 
+  
+  Every qualifying key event will trigger an http call, so we may get into a situation where we have multiple http calls in flight. 
+  
+  Normally this could lead to results being returned out of order, but `switchMap` has built in support for ensuring that only the most recent http call will be processed. Results from prior calls will be discarded.  
+  
+  ### subscribe
+  `subscribe` is similar to `then` in the promise world. 
+  
+  The first callback is the success callback where we grab the result of the search and assign it to our `heroes` array.
+  
+  The second callback is the error callback. This callback will execute if there is an error - either from the http call or in our processing of key events. 
+  
+  In our current implementation we are just logging the error to the console, but a real life application should do better.
+  
+  None of these operators are not included by default, so we have to load each one using `import` statements before using them. 
+  
+  We have combined all the operator imports in a single file.
+
++makeExample('toh-6/ts/app/rxjs-operators.ts', null, 'app/rxjs-operators.ts')(format=".")
+
+:marked
+  We can then load all the operators in a single operation by importing `rxjs-operators` is `AppComponent`
+
++makeExample('toh-6/ts/app/app.component.ts', 'rxjs-operators', 'app/app/app.component.ts')(format=".")  
+  
+:marked
+  Here is the final search component.
+
+figure.image-display
+  img(src='/resources/images/devguide/toh/toh-hero-search.png' alt="Hero Search Component")
+  
 :marked
   ### Review the App Structure
   Let’s verify that we have the following structure after all of our good refactoring in this chapter:
@@ -320,11 +417,15 @@ figure.image-display
     .file hero-detail.component.css
     .file hero-detail.component.html
     .file hero-detail.component.ts
+    .file hero-search.component.html
+    .file hero-search.component.ts
+    .file hero-search.service.ts
     .file hero.service.ts
     .file heroes.component.css
     .file heroes.component.html
     .file heroes.component.ts
     .file main.ts
+    .file rxjs-operators.ts
     .file hero-data.service.ts
   .file node_modules ...
   .file typings ...
@@ -346,6 +447,7 @@ figure.image-display
     - We extended HeroService to support post, put and delete calls.
     - We updated our components to allow adding, editing and deleting of heroes.
     - We configured an in-memory web api.
+    - We learned how to use Observables.
 
     Below is a summary of the files we changed.
 
@@ -365,3 +467,14 @@ figure.image-display
    hero.service.ts`
 ) 
 
++makeTabs(
+  `toh-6/ts/app/hero-search.service.ts,
+   toh-6/ts/app/hero-search.component.ts,
+   toh-6/ts/app/hero-search.component.html,
+   toh-6/ts/app/rxjs-operators.ts`,
+  null,
+  `hero-search.service.ts,
+   hero-search.component.ts,
+   hero-search.service.html,
+   rxjs-operators.ts`
+)