docs(toh-6): refactoring of 'add, edit, delete heroes' (#2170)

* docs(toh-6/dart): 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.

* 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.

* docs(toh-6): ward tweaks

Author: chalin

public/docs/_examples/toh-6/dart/example-config.json

@@ -3,59 +3,38 @@
 import 'dart:async';
 import 'dart:html';
 
-// #docregion import-oninit
 import 'package:angular2/core.dart';
-// #enddocregion import-oninit
-// #docregion import-route-params
 import 'package:angular2/router.dart';
-// #enddocregion import-route-params
 
 import 'hero.dart';
-// #docregion import-hero-service
 import 'hero_service.dart';
-// #enddocregion import-hero-service
 
-// #docregion extract-template
 @Component(
     selector: 'my-hero-detail',
-    // #docregion template-url
     templateUrl: 'hero_detail_component.html',
-    // #enddocregion template-url, v2
     styleUrls: const ['hero_detail_component.css']
-    // #docregion v2
     )
-// #enddocregion extract-template
-// #docregion implement
 class HeroDetailComponent implements OnInit {
-  // #enddocregion implement
   Hero hero;
-  // #docregion ctor
   final HeroService _heroService;
   final RouteParams _routeParams;
 
   HeroDetailComponent(this._heroService, this._routeParams);
-  // #enddocregion ctor
 
-  // #docregion ng-oninit
   Future<Null> ngOnInit() async {
-    // #docregion get-id
     var idString = _routeParams.get('id');
     var id = int.parse(idString, onError: (_) => null);
-    // #enddocregion get-id
     if (id != null) hero = await (_heroService.getHero(id));
   }
-  // #enddocregion ng-oninit
 
   // #docregion save
   Future<Null> save() async {
-    await _heroService.save(hero);
+    await _heroService.update(hero);
     goBack();
   }
   // #enddocregion save
 
-  // #docregion go-back
   void goBack() {
     window.history.back();
   }
-  // #enddocregion go-back
 }

public/docs/_examples/toh-6/dart/lib/hero_detail_component.dart

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

public/docs/_examples/toh-6/dart/lib/hero_detail_component.html

@@ -1,17 +1,19 @@
-// #docregion
+// #docplaster
+// #docregion , imports
 import 'dart:async';
 import 'dart:convert';
 
 import 'package:angular2/core.dart';
 import 'package:http/http.dart';
 
 import 'hero.dart';
+// #enddocregion imports
 
 @Injectable()
 class HeroService {
-  // #docregion post
+  // #docregion update
   static final _headers = {'Content-Type': 'application/json'};
-  // #enddocregion post
+  // #enddocregion update
   // #docregion getHeroes
   static const _heroesUrl = 'app/heroes'; // URL to web API
 
@@ -35,25 +37,20 @@ class HeroService {
 
   // #docregion extract-data
   dynamic _extractData(Response resp) => JSON.decode(resp.body)['data'];
-  // #enddocregion extract-data, getHeroes
-
-  Future<Hero> getHero(int id) async =>
-      (await getHeroes()).firstWhere((hero) => hero.id == id);
-
-  // #docregion save
-  Future<Hero> save(dynamic heroOrName) =>
-      heroOrName is Hero ? _put(heroOrName) : _post(heroOrName);
-  // #enddocregion save
+  // #enddocregion extract-data
 
   // #docregion handleError
   Exception _handleError(dynamic e) {
     print(e); // for demo purposes only
     return new Exception('Server error; cause: $e');
   }
-  // #enddocregion handleError
+  // #enddocregion handleError, getHeroes
+
+  Future<Hero> getHero(int id) async =>
+      (await getHeroes()).firstWhere((hero) => hero.id == id);
 
-  // #docregion post
-  Future<Hero> _post(String name) async {
+  // #docregion create
+  Future<Hero> create(String name) async {
     try {
       final response = await _http.post(_heroesUrl,
           headers: _headers, body: JSON.encode({'name': name}));
@@ -62,10 +59,10 @@ class HeroService {
       throw _handleError(e);
     }
   }
-  // #enddocregion post
+  // #enddocregion create
+  // #docregion update
 
-  // #docregion put
-  Future<Hero> _put(Hero hero) async {
+  Future<Hero> update(Hero hero) async {
     try {
       var url = '$_heroesUrl/${hero.id}';
       final response =
@@ -75,7 +72,7 @@ class HeroService {
       throw _handleError(e);
     }
   }
-  // #enddocregion put
+  // #enddocregion update
 
   // #docregion delete
   Future<Null> delete(int id) async {

public/docs/_examples/toh-6/dart/lib/hero_service.dart

@@ -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/dart/lib/heroes_component.css

@@ -1,4 +1,3 @@
-// #docplaster
 // #docregion
 import 'dart:async';
 
@@ -15,44 +14,34 @@ import 'hero_service.dart';
     styleUrls: const ['heroes_component.css'],
     directives: const [HeroDetailComponent])
 class HeroesComponent implements OnInit {
-  final Router _router;
-  final HeroService _heroService;
   List<Hero> heroes;
   Hero selectedHero;
-  // #docregion error
-  String errorMessage;
-  // #enddocregion error
+
+  final HeroService _heroService;
+  final Router _router;
 
   HeroesComponent(this._heroService, this._router);
 
-  // #docregion addHero
-  Future<Null> addHero(String name) async {
-    name = name.trim();
-    if (name.isEmpty) return;
-    try {
-      heroes.add(await _heroService.save(name));
-    } catch (e) {
-      errorMessage = e.toString();
-    }
+  Future<Null> getHeroes() async {
+    heroes = await _heroService.getHeroes();
   }
-  // #enddocregion addHero
 
-  // #docregion deleteHero
-  Future<Null> deleteHero(int id, event) async {
-    try {
-      event.stopPropagation();
-      await _heroService.delete(id);
-      heroes.removeWhere((hero) => hero.id == id);
-      if (selectedHero?.id == id) selectedHero = null;
-    } catch (e) {
-      errorMessage = e.toString();
-    }
+  // #docregion add
+  Future<Null> add(String name) async {
+    name = name.trim();
+    if (name.isEmpty) return;
+    heroes.add(await _heroService.create(name));
+    selectedHero = null;
   }
-  // #enddocregion deleteHero
+  // #enddocregion add
 
-  Future<Null> getHeroes() async {
-    heroes = await _heroService.getHeroes();
+  // #docregion delete
+  Future<Null> delete(Hero hero) async {
+    await _heroService.delete(hero.id);
+    heroes.remove(hero);
+    if (selectedHero == hero) selectedHero = null;
   }
+  // #enddocregion delete
 
   void ngOnInit() {
     getHeroes();

public/docs/_examples/toh-6/dart/lib/heroes_component.dart

@@ -1,31 +1,30 @@
 <!-- #docplaster -->
 <!-- #docregion -->
 <h2>My Heroes</h2>
-<!-- #docregion add-and-error -->
-<div class="error" *ngIf="errorMessage != null">{{errorMessage}}</div>
+<!-- #docregion add -->
 <div>
-  Name: <input #newHeroName />
-  <button (click)="addHero(newHeroName.value); newHeroName.value=''">
-    Add New Hero
+  <label>Hero name:</label> <input #heroName />
+  <button (click)="add(heroName.value); heroName.value=''">
+    Add
   </button>
 </div>
-<!-- #enddocregion add-and-error -->
+<!-- #enddocregion add -->
 <ul class="heroes">
-  <li *ngFor="let hero of heroes"
-    [class.selected]="hero === selectedHero"
-    (click)="onSelect(hero)">
-    <span class="badge">{{hero.id}}</span> {{hero.name}}
+  <!-- #docregion li-element -->
+  <li *ngFor="let hero of heroes" (click)="onSelect(hero)"
+      [class.selected]="hero === selectedHero">
+    <span class="badge">{{hero.id}}</span>
+    <span>{{hero.name}}</span>
     <!-- #docregion delete -->
-    <button class="delete-button" (click)="deleteHero(hero.id, $event)">x</button>
+    <button class="delete"
+      (click)="delete(hero); $event.stopPropagation()">x</button>
     <!-- #enddocregion delete -->
   </li>
+  <!-- #enddocregion li-element -->
 </ul>
-<!-- #docregion mini-detail -->
 <div *ngIf="selectedHero != null">
   <h2>
-    <!-- #docregion pipe -->
     {{selectedHero.name | uppercase}} is my hero
-    <!-- #enddocregion pipe -->
   </h2>
   <button (click)="gotoDetail()">View Details</button>
 </div>

public/docs/_examples/toh-6/dart/lib/heroes_component.html

@@ -1,9 +1,8 @@
-// #docregion
+// #docregion , init
 import 'dart:async';
 import 'dart:convert';
 import 'dart:math';
 
-// #docregion init
 import 'package:angular2/core.dart';
 import 'package:http/http.dart';
 import 'package:http/testing.dart';
@@ -26,7 +25,6 @@ class InMemoryDataService extends MockClient {
   ];
   static final List<Hero> _heroesDb =
       _initialHeroes.map((json) => new Hero.fromJson(json)).toList();
-  // #enddocregion init
   static int _nextId = _heroesDb.map((hero) => hero.id).reduce(max) + 1;
 
   static Future<Response> _handler(Request request) async {
@@ -37,6 +35,7 @@ class InMemoryDataService extends MockClient {
         final regExp = new RegExp(prefix, caseSensitive: false);
         data = _heroesDb.where((hero) => hero.name.contains(regExp)).toList();
         break;
+      // #enddocregion init-disabled
       case 'POST':
         var name = JSON.decode(request.body)['name'];
         var newHero = new Hero(_nextId++, name);
@@ -54,6 +53,7 @@ class InMemoryDataService extends MockClient {
         _heroesDb.removeWhere((hero) => hero.id == id);
         // No data, so leave it as null.
         break;
+      // #docregion init-disabled
       default:
         throw 'Unimplemented HTTP method ${request.method}';
     }
@@ -62,5 +62,4 @@ class InMemoryDataService extends MockClient {
   }
 
   InMemoryDataService() : super(_handler);
-  // #docregion init
 }

public/docs/_examples/toh-6/dart/lib/in_memory_data_service.dart

@@ -4,8 +4,8 @@ import 'package:angular2/core.dart';
 import 'package:angular2/platform/browser.dart';
 import 'package:angular2_tour_of_heroes/app_component.dart';
 // #enddocregion v1
-import 'package:http/http.dart';
 import 'package:angular2_tour_of_heroes/in_memory_data_service.dart';
+import 'package:http/http.dart';
 
 void main() {
   bootstrap(AppComponent,