docs:(TOH-Http-Chapter) - made updated based on feedback

Author: thelgevold

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

@@ -17,7 +17,7 @@ import { HTTP_PROVIDERS } from 'angular2/http';
 //These imports are only required for the in-memory web api 
 import { InMemoryBackendService, SEED_DATA } from 'a2-in-memory-web-api/core';
 import { XHRBackend } from 'angular2/http';
-import { HeroData } from './hero-data';
+import { InMemoryDataService } from './in-memory-data.service';
 
 @Component({
   selector: 'my-app',
@@ -40,7 +40,7 @@ import { HeroData } from './hero-data';
 
     // Only required for the in-memory web api 
     provide(XHRBackend, { useClass: InMemoryBackendService }), // in-mem server
-    provide(SEED_DATA,  { useClass: HeroData }) // in-mem server data
+    provide(SEED_DATA,  { useClass: InMemoryDataService }) // in-mem server data
   ]
 })
 //#enddocregion http

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

@@ -13,6 +13,7 @@ import { HeroService } from './hero.service';
 export class HeroDetailComponent implements OnInit {
   @Input() hero: Hero;
   @Output() updateHeroes = new EventEmitter();
+  error:any; 
 
   constructor(
     private _heroService: HeroService,
@@ -33,10 +34,12 @@ export class HeroDetailComponent implements OnInit {
   // #enddocregion ngOnInit
   // #docregion save
   save(){
-    this._heroService.save(this.hero)
-        .then(r => {
-          this.updateHeroes.emit(r);
-        });
+    this._heroService
+        .save(this.hero)
+        .then(response => {
+          this.updateHeroes.emit(response);
+        })
+        .catch(error => this.error = error);//TODO: Display error message
   }
   // #enddocregion save
   goBack() {

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

@@ -14,27 +14,24 @@ export class HeroService {
 
   //#docregion get-heroes
   getHeroes() {
-    return this._http.get(this._heroesUrl).toPromise()
-                     .then((res:Response) => res.json())
-                     .then(res => res.data)
-                     .catch(this._handleError);
+    return this._http
+               .get(this._heroesUrl).toPromise()
+               .then((res:Response) => res.json().data)
+               .catch(this._handleError);
   }
   //#enddocregion get-heroes
 
   getHero(id: number) {
-    return this.getHeroes().then(
-      heroes => heroes.filter((hero:Hero) => hero.id === id)[0]
-    );
+    return this.getHeroes()
+               .then(heroes => heroes.filter((hero:Hero) => hero.id === id)[0]);
   }
 
   //#docregion save
   save(hero:Hero){
     if(hero.id){
       return this._put(hero);
     }
-    else{
-      return this._post(hero);
-    }
+    return this._post(hero);
   }
   //#enddocregion save
 
@@ -45,7 +42,9 @@ export class HeroService {
 
     let url = `${this._heroesUrl}/${hero.id}`;
 
-    return this._http.delete(url,headers).toPromise()
+    return this._http
+               .delete(url,headers)
+               .toPromise()
                .catch(this._handleError);
   }
   //#enddocregion delete-hero
@@ -55,9 +54,10 @@ export class HeroService {
     let headers = new Headers();
     headers.append('Content-Type', 'application/json');
 
-    return this._http.post(this._heroesUrl, JSON.stringify(hero), {headers:headers}).toPromise()
+    return this._http
+               .post(this._heroesUrl, JSON.stringify(hero), {headers:headers})
+               .toPromise()
                .catch(this._handleError);
-              
   }
   //#enddocregion post-hero 
 
@@ -68,14 +68,17 @@ export class HeroService {
 
     let url = `${this._heroesUrl}/${hero.id}`;
 
-    return this._http.put(url, JSON.stringify(hero), {headers:headers}).toPromise()
+    return this._http
+               .put(url, JSON.stringify(hero), {headers:headers})
+               .toPromise()
                .catch(this._handleError);
   }
   //#enddocregion put-hero
 
   //#docregion error-handler
   private _handleError(error:any){
     console.log('An error occurred:' + error);
+    return Promise.reject(error);
   }
   //#enddocregion error-handler 
 }

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

@@ -1,4 +1,3 @@
-<!-- #docplaster -->
 <!-- #docregion -->
 <h2>My Heroes</h2>
 <ul class="heroes">

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

@@ -1,4 +1,3 @@
-// #docplaster
 // #docregion
 import { Component, OnInit } from 'angular2/core';
 import { Router } from 'angular2/router';
@@ -17,14 +16,17 @@ export class HeroesComponent implements OnInit {
   heroes: Hero[];
   selectedHero: Hero;
   addingHero = false;
+  error:any; 
 
   constructor(
     private _router: Router,
     private _heroService: HeroService) { }
 
   getHeroes() {
-    this._heroService.getHeroes()
-        .then(heroes => this.heroes = heroes);
+    this._heroService
+        .getHeroes()
+        .then(heroes => this.heroes = heroes)
+        .catch(error => this.error = error);//TODO: Display error message
   }
 
   addHero(){
@@ -35,11 +37,12 @@ export class HeroesComponent implements OnInit {
   // #docregion delete
   delete(hero:Hero, event:any){
     event.stopPropagation(); 
-    this._heroService.delete(hero)
-        .then(r => {
+    this._heroService
+        .delete(hero)
+        .then(res => {
           this.heroes = this.heroes.filter(h => h.id !== hero.id);
-        }
-    );
+        })
+        .catch(error => this.error = error);//TODO: Display error message
   }
   // #enddocregion delete
 

public/docs/_examples/toh-6/ts/app/hero-data.ts renamed to public/docs/_examples/toh-6/ts/app/in-memory-data.service.ts

@@ -1,5 +1,5 @@
 // #docregion
-export class HeroData {
+export class InMemoryDataService {
   createDb() {
     let heroes = [
       { "id": 1, "name": "Windstorm" },

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

@@ -3,11 +3,11 @@ include ../_util-fns
 :marked
   # Http
 
-  Our application has become a huge success and our stakeholders have already expanded the vision to include integration with a hero api. 
+  Our application has become a huge success and our stakeholders have expanded the vision to include integration with a hero api. 
 
-  The current solution limits us to a fixed set of heroes, but integration with the api will allow us to load heroes dynamically from a database. We will also be able to add, edit and delete heroes. 
+  The current solution limits us to a fixed set of heroes, but integration with a web server api will make our application much more flexible. We will also be able to add, edit and delete heroes. 
 
-  In this chapter we will show how to integrate the http based api with our existing application.
+  In this chapter we will connect our Angular 2 services to make http calls to our new api.
 :marked
   [Run the live example](/resources/live-examples/toh-6/ts/plnkr.html).   
 
@@ -72,14 +72,14 @@ code-example(format="." language="bash").
 
   In our previous implementation we created a promise ourselves and resolved it immediately. When using `Http` we no longer have to create the promise manually. Instead `Http` will create it for us, but we have to call `toPromise()` to get it.
 
-  In the first `then` we convert the response to a json object by calling `res.json()`.
+  In the `then` we convert the response to a json object by calling `res.json()`.
 
-  Our api follows the convention of returning the result wrapped in a `data` property, but we don't want to expose this to the caller, so we flatten the response in the second `then` by returning `res.data`.   
+  Our api follows the convention of returning the result wrapped in a `data` property, but we don't want to expose this to the caller, so we flatten the response by returning `res.data`.   
 
 :marked
   ### Error Handling
 
-  At the end we are calling `catch` and passing in an error handler. This is an important step since it allows us to catch any error returned by the api. 
+  At the end we are calling `catch` and passing in an error handler. This is an important step since it allows us to catch any error returned by the api. In the service we log the error and return the rejected promise. It's important that the service returns the rejected promise to the component, so that we can display an error message to the user.   
 +makeExample('toh-6/ts/app/hero.service.ts', 'error-handler', 'app/hero.service.ts (Error handler)')(format=".")
 
 :marked
@@ -88,25 +88,25 @@ code-example(format="." language="bash").
 
 .l-sub-section
   :marked
-    We want to point out that a promise is not the only way to process http calls. We will encounter other approaches such as Observables in subsequent chapters, but for the purposes of this article we are sticking to promises. 
+    We realize there are alternatives to promises for processing http calls. We will encounter other approaches such as Observables in subsequent chapters, but for the purposes of this article we are sticking to promises. 
 
 .l-main-section   
 :marked
   ## Add, Edit, Delete
 
   Our stakeholders are incredibly pleased with the added flexibility from the api integration, but it doesn't stop there. Next we want to add the capability to add, edit and delete heroes.   
 
-  In this section we will show how to implement http `post`, `put` and `delete` calls in `HeroService` to meet our new requirements. 
+  We'll complete `HeroService` by creating `post`, `put` and `delete` http calls to meet our new requirements. 
 
 :marked
   ### Post
 
-  We are using `post` to add new `Hero` objects to our database. Post requests require a little bit more setup than Get requests, but the format is as follows:
+  We are using `post` to add new heroes. Post requests require a little bit more setup than Get requests, but the format is as follows:
 
 +makeExample('toh-6/ts/app/hero.service.ts', 'post-hero', 'app/hero.service.ts (post hero)')(format=".")
 
 :marked
-  First we create a header and set the content type to `application/json`. Before posting we have to call `JSON.stringify` to convert the hero object to a string.  
+  Now we create a header and set the content type to `application/json`. We'll call `JSON.stringify` before we post to convert the hero object to a string.  
 
   ### Put
 
@@ -121,12 +121,12 @@ code-example(format="." language="bash").
 +makeExample('toh-6/ts/app/hero.service.ts', 'delete-hero', 'app/hero.service.ts (delete hero)')(format=".")
 
 :marked
-  In all three cases we add a `catch` for error handling.
+  We add a `catch` to handle our errors for all three cases.
 
 :marked
   ### Save
 
-  I am combining the call to the private `_post` and `_put` methods in a single `save` method. This simplifies the public api and makes the integration with `HeroDetailComponent` easier. `HeroService` determines which method to call based on the state of the `hero` object. If the hero already has an id we know it's an edit. Otherwise we know it's an add.
+  We combine the call to the private `_post` and `_put` methods in a single `save` method. This simplifies the public api and makes the integration with `HeroDetailComponent` easier. `HeroService` determines which method to call based on the state of the `hero` object. If the hero already has an id we know it's an edit. Otherwise we know it's an add.
 
 +makeExample('toh-6/ts/app/hero.service.ts', 'save', 'app/hero.service.ts (save hero)')(format=".")
 
@@ -154,9 +154,9 @@ code-example(format="." language="bash").
 +makeExample('toh-6/ts/app/hero-detail.component.ts', 'save', 'app/hero-detail.component.ts (save)')(format=".")  
 
 :marked
-  The same save method is used for both add end edit since `HeroService` will know when to call `post` vs `put` based on the state of the `Hero` object.
+  The same save method is used for both add and edit since `HeroService` will know when to call `post` vs `put` based on the state of the `Hero` object.
 
-  We mentioned earlier that `save()` returns a promise, so when the promise resolves, we call `emit` to notify `HeroesComponent` that we just added or modified a hero. `HeroesComponent` is listening for this notification and will automatically refresh the list of heroes to include our recent updates.     
+  Earlier we used the `save()` method to return a promise, so when the promise resolves, we call `emit` to notify `HeroesComponent` that we just added or modified a hero. `HeroesComponent` is listening for this notification and will automatically refresh the list of heroes to include our recent updates.     
 
 .l-sub-section
   :marked
@@ -185,7 +185,7 @@ figure.image-display
 :marked
  ## Integration with Http
 
-  `Http` is not part of Angular core, but exists as a separate add-on module called `angular2/http`. It ships as a separate bundle, so we have to include the bundle in `index.html`.
+  `Http` is not part of the Angular core module, but exists as a separate add-on module called `angular2/http`. It ships as a separate bundle, so we have to include the bundle in `index.html`.
 
 +makeExample('toh-6/ts/index.html', 'http', 'index.html (http)')(format=".")  
 
@@ -196,13 +196,13 @@ figure.image-display
 
 :marked
   ### Simulating the api
-  Our hero api is not deployed to production yet, but for the purposes of this chapter we have decided to integrate with an in-memory web api simulator.
+  Our hero api is not deployed to production yet, but for the purposes of this chapter we have decided to integrate with an in-memory web api.
 
-  If you look at `AppComponent` you will notice that we have also imported `InMemoryBackendService`, `HeroData` and `SEED_DATA`. These imports are only there to configure the api simulator and will not be needed when integrating with a real api.
+  Looking at the `AppComponent` we notice that we have also imported `InMemoryBackendService`, `InMemoryDataService` and `SEED_DATA`. These imports are only there to configure the in-memory web api and will not be needed when integrating with a real api.
 
-  We have included some more information about configuring the simulator <a href='/docs/ts/latest/guide/server-communication.html#!#in-mem-web-api'>here</a>.
+  We have included some more information about configuring the in-memory web api <a href='/docs/ts/latest/guide/server-communication.html#!#in-mem-web-api'>here</a>.
 
-  Since we are integrating with the simulator we no longer need `mock-heroes.ts`, so it's safe to delete it.
+  Since we are integrating with the in-memory web api we no longer need `mock-heroes.ts`, so it's safe to delete it.
 
 :marked
   ### Review the App Structure
@@ -227,7 +227,7 @@ figure.image-display
     .file heroes.component.html
     .file heroes.component.ts
     .file main.ts
-    .file hero-data.ts
+    .file hero-data.service.ts
   .file node_modules ...
   .file typings ...      
   .file index.html
@@ -236,17 +236,33 @@ figure.image-display
   .file sample.css
   .file tsconfig.json
   .file typings.json
-    
-:marked
-
-.l-main-section
+ 
+.l-main-section    
 :marked
-  ## Recap
+    ## Home Stretch
+    
+    We are at the end of our journey for now, but we have accomplished a lot.
+    - We added the necessary dependencies to use Http in our application.
+    - We refactored HeroService to load heroes from an api.
+    - 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.
+    
+    Below is a summary of the files we changed.
+    
++makeTabs(
+  `toh-6/ts/app/app.component.ts,
+   toh-6/ts/app/heroes.component.ts,
+   toh-6/ts/app/heroes.component.html,
+   toh-6/ts/app/hero-detail.component.ts,
+   toh-6/ts/app/hero-detail.component.html,
+   toh-6/ts/app/hero.service.ts`,
+  null,
+  `app.comp...ts,
+   heroes.comp...ts,
+   heroes.comp...html,
+   hero-detail.comp...ts,
+   hero-detail.comp...html,
+   hero.service.ts`
+) 
 
-  ### The Road Behind
-  We travelled a great distance in this chapter.
-  - We add the necessary dependencies to use Http in our application.
-  - We refactored HeroService to load heroes from a database.
-  - 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 api simulator.