docs(add observables to TOH http)

e2e

prose

tweaks

d

d

d

section

lint

jade

space

update

remove

r

test

tweak

tweak

Author: thelgevold

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

@@ -23,10 +23,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() {
+    let page = getPageStruct();
+
+    return sendKeys(page.searchBox, 'Magneta').then(function () {
+      expect(page.searchResults.count()).toBe(1);
+      let hero = page.searchResults.get(0);
+      return hero.click();
+    })
+    .then(function() {
+      browser.waitForAngular();
+      let 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(){
     let page = getPageStruct();
     let heroCount: webdriver.promise.Promise<number>;

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

@@ -4,6 +4,9 @@ import { Component }          from '@angular/core';
 import { ROUTER_DIRECTIVES }  from '@angular/router';
 
 import { HeroService }        from './hero.service';
+// #docregion rxjs-operators
+import './rxjs-operators';
+// #enddocregion rxjs-operators
 
 @Component({
   selector: 'my-app',

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

@@ -5,11 +5,13 @@ import { Router }           from '@angular/router';
 
 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 #searchBox id="search-box" (keyup)="search.next(searchBox.value)" />    
+  <div>
+    <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 { Router }            from '@angular/router';
+import { Observable }        from 'rxjs/Observable';
+import { Subject }           from 'rxjs/Subject';
+
+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 Subject<string>();
+  heroes: 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));
+  }
+  // #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,8 @@
+// #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';
+import 'rxjs/add/observable/of';

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

@@ -5,3 +5,20 @@ button.delete-button{
   background-color: gray !important;
   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

@@ -358,6 +358,99 @@ block review
   figure.image-display
     img(src='/resources/images/devguide/toh/toh-http.anim.gif' alt="Heroes List Editting w/ HTTP")
 
+: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 as we will see, the observables api is much richer. 
+
+  `RxJs` offers a wide variety of operators that we can use to manage event flows.     
+
+  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. 
+
+  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. 
+  
+  To keep track of text changes in the search box we are using an RxJs `Subject`.
+  
+  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
+  ### asObservable
+  We start the observable chain by calling `asObservable` on our `Subject` to return an observable that represents text changes as we are typing into the search box.
+  
+  ### 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.
+  
+  ### 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.  
+  
+  We short circuit the http call and return an observable containing an empty array if the search box is empty.
+
+  ### 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.
+  
+  ### Import operators
+  The `RxJs` operators are not included by default, so we have to include them using `import` statements. 
+  
+  We have combined all 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` in `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")
+
 .l-main-section
 :marked
   ## Application structure and code
@@ -381,6 +474,10 @@ block filetree
         .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 rxjs-operators.ts
         .file hero.service.ts
         .file heroes.component.css
         .file heroes.component.html
@@ -407,7 +504,8 @@ block filetree
   - 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 and added.
 
 block file-summary
@@ -430,3 +528,15 @@ block file-summary
      in-memory-data.service.ts,
      sample.css`
   )
+
+  +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`
+)