docs(toh-6/ts): refactoring of 'add, edit, delete heroes'

Refactoring of "add, edit, delete heroes" section of toh-6 from one big
bottom-up step into small independent feature slices, where the user
achieves a "milesone" (i.e., can run the full app) after each feature
section. The section rewrite is shorter and offers a better UX.

Other simplifications:
- Error handling is consistent: in the hero service we log to the
console, everwhere else we just let errors bubble up.
- Hero service methods renamed based on function (create, update)
rather then lower-level implementation (post, put).
- @output properties have been eliminated (since they weren't
explained).

E2E tests now pass on both the TS and Dart sides.

Post-Dart-review updates included.

Author: chalin

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

@@ -1,4 +1,3 @@
-<!-- #docplaster -->
 <!-- #docregion -->
 <div *ngIf="hero">
   <h2>{{hero.name}} details!</h2>

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

@@ -1,8 +1,5 @@
-// #docplaster
-// #docregion, variables-imports
-import { Component, EventEmitter, Input, OnInit, Output } from '@angular/core';
-
-// #enddocregion variables-imports
+// #docregion
+import { Component, OnInit } from '@angular/core';
 import { ActivatedRoute, Params } from '@angular/router';
 
 import { Hero }        from './hero';
@@ -13,50 +10,30 @@ import { HeroService } from './hero.service';
   templateUrl: 'app/hero-detail.component.html',
   styleUrls: ['app/hero-detail.component.css']
 })
-// #docregion variables-imports
 export class HeroDetailComponent implements OnInit {
-  @Input() hero: Hero;
-  @Output() close = new EventEmitter();
-  error: any;
-  navigated = false; // true if navigated here
-  // #enddocregion variables-imports
+  hero: Hero;
 
   constructor(
     private heroService: HeroService,
     private route: ActivatedRoute) {
   }
 
-  // #docregion ngOnInit
   ngOnInit(): void {
     this.route.params.forEach((params: Params) => {
-      if (params['id'] !== undefined) {
-        let id = +params['id'];
-        this.navigated = true;
-        this.heroService.getHero(id)
-            .then(hero => this.hero = hero);
-      } else {
-        this.navigated = false;
-        this.hero = new Hero();
-      }
+      let id = +params['id'];
+      this.heroService.getHero(id)
+        .then(hero => this.hero = hero);
     });
   }
-  // #enddocregion ngOnInit
 
   // #docregion save
   save(): void {
-    this.heroService
-        .save(this.hero)
-        .then(hero => {
-          this.hero = hero; // saved hero, w/ id if new
-          this.goBack(hero);
-        })
-        .catch(error => this.error = error); // TODO: Display error message
+    this.heroService.update(this.hero)
+      .then(this.goBack);
   }
   // #enddocregion save
-  // #docregion goBack
-  goBack(savedHero: Hero = null): void {
-    this.close.emit(savedHero);
-    if (this.navigated) { window.history.back(); }
+
+  goBack(): void {
+    window.history.back();
   }
-  // #enddocregion goBack
 }

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

@@ -1,17 +1,21 @@
 // #docplaster
-// #docregion
+// #docregion , imports
 import { Injectable }    from '@angular/core';
-import { Headers, Http, Response } from '@angular/http';
+import { Headers, Http } from '@angular/http';
 
 // #docregion rxjs
 import 'rxjs/add/operator/toPromise';
 // #enddocregion rxjs
 
 import { Hero } from './hero';
+// #enddocregion imports
 
 @Injectable()
 export class HeroService {
 
+  // #docregion update
+  private headers = new Headers({'Content-Type': 'application/json'});
+  // #enddocregion update
   // #docregion getHeroes
   private heroesUrl = 'app/heroes';  // URL to web api
 
@@ -36,62 +40,40 @@ export class HeroService {
                .then(heroes => heroes.find(hero => hero.id === id));
   }
 
-  // #docregion save
-  save(hero: Hero): Promise<Hero>  {
-    if (hero.id) {
-      return this.put(hero);
-    }
-    return this.post(hero);
-  }
-  // #enddocregion save
-
   // #docregion delete
-  delete(hero: Hero): Promise<Response> {
-    let headers = new Headers();
-    headers.append('Content-Type', 'application/json');
-
-    let url = `${this.heroesUrl}/${hero.id}`;
-
-    return this.http
-               .delete(url, {headers: headers})
-               .toPromise()
-               .catch(this.handleError);
+  delete(id: number): Promise<void> {
+    let url = `${this.heroesUrl}/${id}`;
+    return this.http.delete(url, {headers: this.headers})
+      .toPromise()
+      .then(() => null)
+      .catch(this.handleError);
   }
   // #enddocregion delete
 
-  // #docregion post
-  // Add new Hero
-  private post(hero: Hero): Promise<Hero> {
-    let headers = new Headers({
-      'Content-Type': 'application/json'});
-
+  // #docregion create
+  create(name: string): Promise<Hero> {
     return this.http
-               .post(this.heroesUrl, JSON.stringify(hero), {headers: headers})
-               .toPromise()
-               .then(res => res.json().data)
-               .catch(this.handleError);
+      .post(this.heroesUrl, JSON.stringify({name: name}), {headers: this.headers})
+      .toPromise()
+      .then(res => res.json().data)
+      .catch(this.handleError);
   }
-  // #enddocregion post
-
-  // #docregion put
-  // Update existing Hero
-  private put(hero: Hero): Promise<Hero> {
-    let headers = new Headers();
-    headers.append('Content-Type', 'application/json');
-
-    let url = `${this.heroesUrl}/${hero.id}`;
+  // #enddocregion create
+  // #docregion update
 
+  update(hero: Hero): Promise<Hero> {
+    const url = `${this.heroesUrl}/${hero.id}`;
     return this.http
-               .put(url, JSON.stringify(hero), {headers: headers})
-               .toPromise()
-               .then(() => hero)
-               .catch(this.handleError);
+      .put(url, JSON.stringify(hero), {headers: this.headers})
+      .toPromise()
+      .then(() => hero)
+      .catch(this.handleError);
   }
-  // #enddocregion put
+  // #enddocregion put, update
 
   // #docregion handleError
   private handleError(error: any): Promise<any> {
-    console.error('An error occurred', error);
+    console.error('An error occurred', error); // for demo purposes only
     return Promise.reject(error.message || error);
   }
   // #enddocregion handleError

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

@@ -59,9 +59,10 @@ button:hover {
   background-color: #cfd8dc;
 }
 /* #docregion additions */
-.error {color:red;}
-button.delete-button{
+button.delete {
   float:right;
+  margin-top: 2px;
+  margin-right: .8em;
   background-color: gray !important;
   color:white;
 }

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

@@ -4,65 +4,55 @@ import { Router }            from '@angular/router';
 
 import { Hero }                from './hero';
 import { HeroService }         from './hero.service';
-// #docregion hero-detail-component
 
 @Component({
   selector: 'my-heroes',
   templateUrl: 'app/heroes.component.html',
   styleUrls:  ['app/heroes.component.css']
 })
-// #enddocregion hero-detail-component
 export class HeroesComponent implements OnInit {
   heroes: Hero[];
   selectedHero: Hero;
-  addingHero = false;
-  // #docregion error
-  error: any;
-  // #enddocregion error
 
   constructor(
-    private router: Router,
-    private heroService: HeroService) { }
+    private heroService: HeroService,
+    private router: Router) { }
 
   getHeroes(): void {
     this.heroService
         .getHeroes()
-        .then(heroes => this.heroes = heroes)
-        .catch(error => this.error = error);
+        .then(heroes => this.heroes = heroes);
   }
 
-  // #docregion addHero
-  addHero(): void {
-    this.addingHero = true;
-    this.selectedHero = null;
+  // #docregion add
+  add(name: string): void {
+    name = name.trim();
+    if (!name) { return; }
+    this.heroService.create(name)
+      .then(hero => {
+        this.heroes.push(hero);
+        this.selectedHero = null;
+      });
   }
+  // #enddocregion add
 
-  close(savedHero: Hero): void {
-    this.addingHero = false;
-    if (savedHero) { this.getHeroes(); }
-  }
-  // #enddocregion addHero
-
-  // #docregion deleteHero
-  deleteHero(hero: Hero, event: any): void {
-    event.stopPropagation();
+  // #docregion delete
+  delete(hero: Hero): void {
     this.heroService
-        .delete(hero)
-        .then(res => {
+        .delete(hero.id)
+        .then(() => {
           this.heroes = this.heroes.filter(h => h !== hero);
           if (this.selectedHero === hero) { this.selectedHero = null; }
-        })
-        .catch(error => this.error = error);
+        });
   }
-  // #enddocregion deleteHero
+  // #enddocregion delete
 
   ngOnInit(): void {
     this.getHeroes();
   }
 
   onSelect(hero: Hero): void {
     this.selectedHero = hero;
-    this.addingHero = false;
   }
 
   gotoDetail(): void {

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

@@ -97,10 +97,12 @@ block backend
     The  `InMemoryWebApiModule` replaces the default `Http` client backend —
     the supporting service that talks to the remote server —
     with an  _in-memory web API alternative service_.
+
   +makeExcerpt(_appModuleTsVsMainTs, 'in-mem-web-api', '')
+
   :marked
     The `forRoot` configuration method takes an `InMemoryDataService` class
-    that will prime the in-memory database as follows:
+    that primes the in-memory database as follows:
 
 +makeExample('app/in-memory-data.service.ts', 'init')(format='.')
 
@@ -126,7 +128,7 @@ block dont-be-distracted-by-backend-subst
 
 :marked
   We returned a !{_Promise} resolved with mock heroes.
-  It may have seemed like an overkill at the time, but we were anticipating the
+  It may have seemed like overkill at the time, but we were anticipating the
   day when we fetched heroes with an HTTP client and we knew that would have to be an asynchronous operation.
 
   That day has arrived! Let's convert `getHeroes()` to use HTTP.
@@ -140,7 +142,7 @@ block dont-be-distracted-by-backend-subst
 
 - var _h3id = `http-${_promise}`
 :marked
-  Refresh the browser and the hero data should be successfully loaded from the
+  Refresh the browser, and the hero data should be successfully loaded from the
   mock server.
 
   <h3 id="!{_h3id}">HTTP !{_Promise}</h3>
@@ -217,23 +219,21 @@ block get-heroes-details
   Although we made significant *internal* changes to `getHeroes()`, the public signature did not change.
   We still return a !{_Promise}. We won't have to update any of the components that call `getHeroes()`.
 
-  ### Add, edit, delete heroes
+  Our stakeholders are incredibly pleased with the added flexibility from the API integration, but it doesn't stop there. Next, we want the ability to create new heroes and delete heroes.
 
-  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.
+  But first, let's see what happens now when we try to update a hero's details.
 
-  We'll start with the edit feature since we have most of the capabilities already.
-
-.l-main-section#edit
+.l-main-section
 :marked
-  ## Persist name changes to the server
+  ## Update hero details
 
   The hero detail view already allows us to edit a hero's name. Go ahead, try
   it now. As we type, the hero name is updated in the view heading, but
-  notice what happens when we hit the `Back` button: the edits are lost!
+  notice what happens when we hit the `Back` button: the changes are lost!
 
 .l-sub-section
   :marked
-    Changes weren't lost before, what's happening?
+    Updates weren't lost before, what's happening?
     When the app used a list of mock heroes, changes were made directly to the
     hero objects in the single, app-wide shared list. Now that we are fetching data
     from a server, if we want changes to persist, we'll need to write them back to
@@ -336,7 +336,7 @@ block get-heroes-details
 :marked
   ### Hero service `delete` method
 
-  The delete HTTP method will be used to delete heroes and its invocation is like to `put` except for the method name:
+  The hero service's `delete` method uses the _delete_ HTTP method to remove the hero from the server:
 
 +makeExcerpt('app/hero.service.ts', 'delete')
 
@@ -509,7 +509,8 @@ block observable-transformers
 - var _declarations = _docsFor == 'dart' ? 'directives' : 'declarations'
 - var declFile = _docsFor == 'dart' ? 'app/dashboard.component.ts' : 'app/app.module.ts'
 :marked
-  And finally, we import the `HeroSearchComponent` from `'./hero-search.component.ts'`
+  And finally, we import `HeroSearchComponent` from 
+  <span ngio-ex>hero-search.component.ts</span>
   and add it to the `!{_declarations}` !{_array}:
 
 +makeExcerpt(declFile, 'search')

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

@@ -31,8 +31,8 @@
     "nextable": true
   },
   "toh-pt6": {
-    "title": "Http",
-    "intro": "We convert our service and components to use Http",
+    "title": "HTTP",
+    "intro": "We convert our service and components to use HTTP",
     "nextable": true
   }
-}
+}