From 8960b6729f1c4bdcebc42fd2cd8ffaab118c61fe Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Tue, 2 Feb 2016 11:22:48 -0800 Subject: [PATCH] docs(http): refine observables story closes #799 --- public/docs/_examples/package.json | 2 +- .../ts/app/wiki/wiki-smart.component.ts | 41 ++++++++++--------- .../ts/app/wiki/wiki.component.ts | 1 + public/docs/ts/latest/guide/_data.json | 4 +- .../ts/latest/guide/server-communication.jade | 40 ++++++++++++------ 5 files changed, 54 insertions(+), 34 deletions(-) diff --git a/public/docs/_examples/package.json b/public/docs/_examples/package.json index b722283176..63080c11b9 100644 --- a/public/docs/_examples/package.json +++ b/public/docs/_examples/package.json @@ -25,7 +25,7 @@ "rxjs": "5.0.0-beta.0", "zone.js": "0.5.10", - "a2-in-memory-web-api": "^0.1.0", + "a2-in-memory-web-api": "^0.1.1", "bootstrap": "^3.3.6" }, diff --git a/public/docs/_examples/server-communication/ts/app/wiki/wiki-smart.component.ts b/public/docs/_examples/server-communication/ts/app/wiki/wiki-smart.component.ts index 6062e5d861..711830166f 100644 --- a/public/docs/_examples/server-communication/ts/app/wiki/wiki-smart.component.ts +++ b/public/docs/_examples/server-communication/ts/app/wiki/wiki-smart.component.ts @@ -1,10 +1,11 @@ // #docregion -import {Component} from 'angular2/core'; -import {JSONP_PROVIDERS} from 'angular2/http'; -import {Observable} from 'rxjs/Observable'; -// #docregion import-subject -import {Subject} from 'rxjs/Subject'; -// #enddocregion import-subject +import {Component} from 'angular2/core'; +import {JSONP_PROVIDERS} from 'angular2/http'; +import {Observable} from 'rxjs/Observable'; +// #docregion import-observer +import {Observer} from 'rxjs/Observer'; +// #enddocregion import-observer + import {WikipediaService} from './wikipedia.service'; @Component({ @@ -25,19 +26,21 @@ export class WikiSmartComponent { constructor (private _wikipediaService: WikipediaService) { } -// #docregion subject - private _searchTermStream = new Subject(); + search: (value: string) => void; - search(value: string){ - this._searchTermStream.next(value); - } -// #enddocregion subject + // #docregion observable-create + private _searchTermStream: Observable = + Observable.create( + // #docregion subscribe-fn + (observer:Observer) => this.search = (term) => observer.next(term) + // #enddocregion subscribe-fn + ); + // #enddocregion observable-create -// #docregion observable - items = this._searchTermStream - .debounceTime(300) - .distinctUntilChanged() - .switchMap((term:string) => this._wikipediaService.search(term)); - -// #enddocregion observable + // #docregion observable-operators + items:Observable = this._searchTermStream + .debounceTime(300) + .distinctUntilChanged() + .switchMap((term:string) => this._wikipediaService.search(term)); +// #enddocregion observable-operators } diff --git a/public/docs/_examples/server-communication/ts/app/wiki/wiki.component.ts b/public/docs/_examples/server-communication/ts/app/wiki/wiki.component.ts index a7e0fe9f01..c6b6e9888a 100644 --- a/public/docs/_examples/server-communication/ts/app/wiki/wiki.component.ts +++ b/public/docs/_examples/server-communication/ts/app/wiki/wiki.component.ts @@ -2,6 +2,7 @@ import {Component} from 'angular2/core'; import {JSONP_PROVIDERS} from 'angular2/http'; import {Observable} from 'rxjs/Observable'; + import {WikipediaService} from './wikipedia.service'; @Component({ diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 16f8ecc933..b7f759488e 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -49,8 +49,8 @@ }, "server-communication": { - "title": "Server Communication", - "intro": "Learn to build applications that talk to a server." + "title": "Http Client", + "intro": "Talk to a remote server with the Angular Http Client." }, "lifecycle-hooks": { diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index 387d4fee54..ce7dd27bd5 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -491,17 +491,32 @@ figure.image-display +makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', null, 'app/wiki/wiki-smart.component.ts') :marked We made no changes to the template or metadata, confining them all to the component class. + Let's review those changes. - The first step turns the user's search box entries into the *subject* of an observable. - We import the `Subject` class from the RxJS observable library: -+makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'import-subject') + ### Create the search term Observable + + We import the `Observer` symbol from the RxJS observable library to get the type information: ++makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'import-observer') :marked - After every keystroke we pump the search box value into the private `_searchTermStream` subject, creating a stream of search term strings. -+makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'subject')(format='.') + The first real step turns the user's search box entries into an observable stream of search terms. + We create a private `Observable` called `_searchTermStream`, driven by a *subscribe* function that + feeds user search terms to the observable. + ++makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'observable-create')(format='.') :marked + The *subscribe* function sets the component's `search` method to a function that updates + the observable's `observer` with search terms. ++makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'subscribe-fn')(format='.') +:marked + The search box `keyup` events are still bound to this `search` method in the template. + After every keystroke the binding pumps the search box value into the `_searchTermStream` observable, + creating a stream of search term strings. + + ### Listen for search terms + Earlier, we passed each search term directly to the service and bound the template to the service results. Now we listen to the *stream of terms*, manipulating the stream before it reaches the `WikipediaService`. -+makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'observable')(format='.') ++makeExample('server-communication/ts/app/wiki/wiki-smart.component.ts', 'observable-operators')(format='.') :marked We wait for the user to stop typing for at least 300 milliseconds ([debounce](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/debounce.md)). @@ -509,14 +524,15 @@ figure.image-display ([distinctUntilChanged](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/distinctuntilchanged.md)). The `WikipediaService` returns a separate observable of strings (`Observable`) for each request. - We could have multiple requests "in flight", all awaiting the server's reply, + We could have multiple requests *in flight*, all awaiting the server's reply, which means multiple *observables-of-strings* could arrive at any moment in any order. - We rely on [switchMap](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/flatmaplatest.md) - (formerly known as `flatMapLatest`) to re-arrange these observables in their original-request order. - - The `switchmap` operator ensures that the component's `items` property is always set to the truly latest `WikipediaService` observable. - Consequently, the displayed list of search results stays in sync with the user's sequence of search terms. + The [switchMap](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/operators/flatmaplatest.md) + (formerly known as `flatMapLatest`) returns a new observable that combines these `WikipediaService` observables, + re-arranges them in their original request order, + and delivers to subscribers only the most recent search results. + + The displayed list of search results stays in sync with the user's sequence of search terms. .l-main-section