From 2fbca288c24773c5f7fc5e46d5d4ff502f844c20 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 14 Mar 2017 10:48:21 -0700 Subject: [PATCH] docs(server-comm): copyedits (#3373) - Minor prose copyedits. - Renamed `HeroService.addHero()` to `create()`, so as to match the ToH sample. --- .../ts/src/app/toh/hero-list.component.ts | 4 +- .../ts/src/app/toh/hero.service.ts | 12 ++--- .../ts/latest/guide/server-communication.jade | 47 ++++++++++--------- 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/public/docs/_examples/server-communication/ts/src/app/toh/hero-list.component.ts b/public/docs/_examples/server-communication/ts/src/app/toh/hero-list.component.ts index 50b724a3df..8cca504762 100644 --- a/public/docs/_examples/server-communication/ts/src/app/toh/hero-list.component.ts +++ b/public/docs/_examples/server-communication/ts/src/app/toh/hero-list.component.ts @@ -31,9 +31,9 @@ export class HeroListComponent implements OnInit { // #enddocregion getHeroes // #docregion addHero - addHero (name: string) { + addHero(name: string) { if (!name) { return; } - this.heroService.addHero(name) + this.heroService.create(name) .subscribe( hero => this.heroes.push(hero), error => this.errorMessage = error); diff --git a/public/docs/_examples/server-communication/ts/src/app/toh/hero.service.ts b/public/docs/_examples/server-communication/ts/src/app/toh/hero.service.ts index 5af142ace3..4f0da49021 100644 --- a/public/docs/_examples/server-communication/ts/src/app/toh/hero.service.ts +++ b/public/docs/_examples/server-communication/ts/src/app/toh/hero.service.ts @@ -21,7 +21,7 @@ import { Hero } from './hero'; @Injectable() export class HeroService { // #docregion endpoint - private heroesUrl = 'app/heroes'; // URL to web API + private heroesUrl = 'api/heroes'; // URL to web API // #enddocregion endpoint // #docregion ctor @@ -29,16 +29,16 @@ export class HeroService { // #enddocregion ctor // #docregion methods, error-handling, http-get - getHeroes (): Observable { + getHeroes(): Observable { return this.http.get(this.heroesUrl) .map(this.extractData) .catch(this.handleError); } // #enddocregion error-handling, http-get, v1 - // #docregion addhero, addhero-sig - addHero (name: string): Observable { - // #enddocregion addhero-sig + // #docregion create, create-sig + create(name: string): Observable { + // #enddocregion create-sig let headers = new Headers({ 'Content-Type': 'application/json' }); let options = new RequestOptions({ headers: headers }); @@ -46,7 +46,7 @@ export class HeroService { .map(this.extractData) .catch(this.handleError); } - // #enddocregion addhero + // #enddocregion create // #docregion v1, extract-data private extractData(res: Response) { diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index 76a8c02aa1..90835930ae 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -110,33 +110,33 @@ block http-providers The newcomers are the `HttpModule` and the `JsonpModule` from the !{_Angular_http_library}. For more information about imports and related terminology, see the [MDN reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) on the `import` statement. To add these modules to the application, pass them to the `imports` array in the root `@NgModule`. -.l-sub-section - :marked - The `HttpModule` is necessary for making HTTP calls. - Though the `JsonpModule` isn't necessary for plain HTTP, - there is a JSONP demo later in this page. - Loading its module now saves time. -.l-main-section#http-client + .l-sub-section + :marked + The `HttpModule` is necessary for making HTTP calls. + Though the `JsonpModule` isn't necessary for plain HTTP, + there is a JSONP demo later in this page. + Loading its module now saves time. + .l-main-section#http-client :marked ## The Tour of Heroes HTTP client demo The first demo is a mini-version of the [tutorial](../tutorial)'s "Tour of Heroes" (ToH) application. This version gets some heroes from the server, displays them in a list, lets the user add new heroes, and saves them to the server. - The app uses the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`. + The app uses the !{_Angular_Http} client to communicate via **XMLHttpRequest (XHR)**. It works like this: figure.image-display img(src='/resources/images/devguide/server-communication/http-toh.gif' alt="ToH mini app" width="250") :marked This demo has a single component, the `HeroListComponent`. Here's its template: -+makeExample('server-communication/ts/src/app/toh/hero-list.component.html', null, 'src/app/toh/hero-list.component.html (template)') ++makeExample('server-communication/ts/src/app/toh/hero-list.component.html', null, 'src/app/toh/hero-list.component.html') :marked It presents the list of heroes with an `ngFor`. Below the list is an input box and an *Add Hero* button where you can enter the names of new heroes and add them to the database. A [template reference variable](template-syntax.html#ref-vars), `newHeroName`, accesses the value of the input box in the `(click)` event binding. - When the user clicks the button, that value passes to the component's `addHero` method and then + When the user clicks the button, that value is passed to the component's `addHero` method and then the event binding clears it to make it ready for a new hero name. Below the button is an area for an error message. @@ -166,9 +166,9 @@ a#HeroListComponent This is a *best practice*. Components are easier to test and debug when their constructors are simple, and all real work (especially calling a remote server) is handled in a separate method. -block getheroes-and-addhero +block getheroes-and-create :marked - The service's `getHeroes()` and `addHero()` methods return an `Observable` of hero data that the !{_Angular_Http} client fetched from the server. + The service's `getHeroes()` and `create()` methods return an `Observable` of hero data that the !{_Angular_Http} client fetched from the server. Think of an `Observable` as a stream of events published by some source. To listen for events in this stream, ***subscribe*** to the `Observable`. @@ -285,7 +285,7 @@ a#no-return-response-object :marked ### Do not return the response object The `getHeroes()` method _could_ have returned the HTTP response but this wouldn't - be a best practice. + follow best practices. The point of a data service is to hide the server interaction details from consumers. The component that calls the `HeroService` only wants heroes and is kept separate from getting them, the code dealing with where they come from, and the response object. @@ -334,6 +334,7 @@ block hlc-error-handling Want to see it fail? In the `HeroService`, reset the api endpoint to a bad value. Afterward, remember to restore it. + .l-main-section @@ -343,10 +344,10 @@ block hlc-error-handling So far you've seen how to retrieve data from a remote location using an HTTP service. Now you'll add the ability to create new heroes and save them in the backend. - You'll write a method for the `HeroListComponent` to call, an `addHero()` method, that takes + You'll write a method for the `HeroListComponent` to call, a `create()` method, that takes just the name of a new hero and returns an `Observable` of `Hero`. It begins like this: -+makeExample('server-communication/ts/src/app/toh/hero.service.ts', 'addhero-sig')(format=".") ++makeExample('server-communication/ts/src/app/toh/hero.service.ts', 'create-sig')(format=".") :marked To implement it, you must know the server's API for creating heroes. @@ -365,11 +366,11 @@ code-example(format="." language="javascript"). of the new hero including its generated id. The hero arrives tucked inside a response object with its own `data` property. - Now that you know how the API works, implement `addHero()` as follows: + Now that you know how the API works, implement `create()` as follows: +ifDocsFor('ts') +makeExample('server-communication/ts/src/app/toh/hero.service.ts', 'import-request-options', 'src/app/toh/hero.service.ts (additional imports)')(format=".") -+makeExample('server-communication/ts/src/app/toh/hero.service.ts', 'addhero', 'src/app/toh/hero.service.ts (addHero)')(format=".") ++makeExcerpt('src/app/toh/hero.service.ts', 'create') a#headers :marked @@ -394,7 +395,7 @@ a#json-results block hero-list-comp-add-hero :marked - Back in the `HeroListComponent`, *its* `addHero()` method subscribes to the Observable returned by the *service's* `addHero()` method. + Back in the `HeroListComponent`, its `addHero()` method subscribes to the Observable returned by the service's `create()` method. When the data arrive it pushes the new hero object into its `heroes` array for presentation to the user. +makeExample('server-communication/ts/src/app/toh/hero-list.component.ts', 'addHero', 'src/app/toh/hero-list.component.ts (addHero)')(format=".") @@ -455,7 +456,7 @@ block hero-list-comp-add-hero h2#cors Cross-Origin Requests: Wikipedia example :marked You just learned how to make `XMLHttpRequests` using the !{_Angular_Http} service. - This is the most common approach for server communication, but it doesn't work in all scenarios. + This is the most common approach to server communication, but it doesn't work in all scenarios. For security reasons, web browsers block `XHR` calls to a remote server whose origin is different from the origin of the web page. The *origin* is the combination of URI scheme, hostname, and port number. @@ -685,18 +686,18 @@ a#override-default-request-options :marked Remember to include this provider during setup when unit testing the app's HTTP services. :marked - After this change, the `header` option setting in `HeroService.addHero()` is no longer necessary, + After this change, the `header` option setting in `HeroService.create()` is no longer necessary, -+makeExample('server-communication/ts/src/app/toh/hero.service.ts', 'addhero', 'src/app/toh/hero.service.ts (addHero)')(format=".") ++makeExcerpt('src/app/toh/hero.service.ts', 'create') :marked You can confirm that `DefaultRequestOptions` is working by examing HTTP requests in the browser developer tools' network tab. If you're short-circuiting the server call with something like the [_in-memory web api_](#in-mem-web-api), - try commenting-out the `addHero` header option, + try commenting-out the `create` header option, set a breakpoint on the POST call, and step through the request processing to verify the header is there. Individual requests options, like this one, take precedence over the default `RequestOptions`. - It might be wise to keep the `addHero` request header setting for extra safety. + It might be wise to keep the `create` request header setting for extra safety. a#in-mem-web-api .l-main-section