docs(toh-6/dart): first edition of prose and example code #1687

chalin · 2016-06-17T22:58:53Z

NOTE: this PR depends on #1686.

Dart prose and example match the TS counterpart except that:

No child-to-parent event emission occurs.
Support for Add Hero is added as an unconditional feature of the Heroes view.
http _post takes only a name
http delete takes only a hero id.
The Dart in-memory-data-service has been dropped in favor of an
implementation based on the "standard" http.testing.MockClient class.

Fixes #1595. Contributes to #2108.

chalin · 2016-06-17T22:59:56Z

@kwalrath @thso : ready for review. Can only be merged after #1686.

cc @Foxandxss @wardbell @johnpapa

chalin · 2016-06-17T23:02:01Z

FYI, an diff with a slightly cleaned-up toh-5 (soon to be committed) is informative:

diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/ /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/.docsync.json /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/.docsync.json
2c2
<   "title": "Tour of Heroes: Routing",
---
>   "title": "Tour of Heroes: HTTP",
4c4
<   "docHref": "toh-pt5.html"
---
>   "docHref": "toh-pt6.html"
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/: example-config.json
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib: app_component_1.dart
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib: app_component_2.dart
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib: dashboard_component_1.dart
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib: dashboard_component_2.dart
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/hero.dart /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/hero.dart
0a1
> // #docregion
5a7,11
> 
>   factory Hero.fromJson(Map<String, dynamic> hero) =>
>     new Hero(_toInt(hero['id']), hero['name']);
> 
>   Map toJson() => {'id': id, 'name': name};
6a13,14
> 
> int _toInt(id) => id is int ? id : int.parse(id);
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/hero_detail_component.dart /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/hero_detail_component.dart
48a49,55
>   // #docregion save
>   Future<Null> save() async {
>     await _heroService.save(hero);
>     goBack();
>   }
>   // #enddocregion save
> 
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/hero_detail_component.html /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/hero_detail_component.html
11d10
<   <!-- #docregion back-button -->
13,14c12,15
<   <!-- #enddocregion back-button -->
< </div>
\ No newline at end of file
---
>   <!-- #docregion save -->
>   <button (click)="save()">Save</button>
>   <!-- #enddocregion save -->
> </div>
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/hero_service.dart /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/hero_service.dart
2a3
> import 'dart:convert';
4a6
> import 'package:http/http.dart';
7d8
< import 'mock_heroes.dart';
11c12,16
<   Future<List<Hero>> getHeroes() async => mockHeroes;
---
>   // #docregion post
>   static final _headers = {'Content-Type': 'application/json'};
>   // #enddocregion post
>   // #docregion getHeroes
>   static const _heroesUrl = 'app/heroes'; // URL to web API
13,16c18,33
<   // See the "Take it slow" appendix
<   Future<List<Hero>> getHeroesSlowly() {
<     return new Future<List<Hero>>.delayed(
<         const Duration(seconds: 2), () => mockHeroes);
---
>   final Client _http;
> 
>   HeroService(this._http);
> 
>   Future<List<Hero>> getHeroes() async {
>     try {
>       final response = await _http.get(_heroesUrl);
>       final heroes = _extractData(response)
>           .map((value) => new Hero.fromJson(value))
>           .toList();
>       return heroes;
>       // #docregion catch
>     } catch (e) {
>       throw _handleError(e);
>     }
>     // #enddocregion catch
19c36,39
<   // #docregion get-hero
---
>   // #docregion extract-data
>   dynamic _extractData(Response resp) => JSON.decode(resp.body)['data'];
>   // #enddocregion extract-data, getHeroes
> 
22c42,90
<   // #enddocregion get-hero
---
> 
>   // #docregion save
>   Future<Hero> save(dynamic heroOrName) =>
>       heroOrName is Hero ? _put(heroOrName) : _post(heroOrName);
>   // #enddocregion save
> 
>   // #docregion handleError
>   Exception _handleError(dynamic e) {
>     print(e); // for demo purposes only
>     return new Exception('Server error; cause: $e');
>   }
>   // #enddocregion handleError
> 
>   // #docregion post
>   Future<Hero> _post(String name) async {
>     try {
>       final response = await _http.post(_heroesUrl,
>           headers: _headers, body: JSON.encode({'name': name}));
>       return new Hero.fromJson(_extractData(response));
>     } catch (e) {
>       throw _handleError(e);
>     }
>   }
>   // #enddocregion post
> 
>   // #docregion put
>   Future<Hero> _put(Hero hero) async {
>     try {
>       var url = '$_heroesUrl/${hero.id}';
>       final response =
>           await _http.put(url, headers: _headers, body: JSON.encode(hero));
>       return new Hero.fromJson(_extractData(response));
>     } catch (e) {
>       throw _handleError(e);
>     }
>   }
>   // #enddocregion put
> 
>   // #docregion delete
>   Future<Null> delete(int id) async {
>     try {
>       var url = '$_heroesUrl/$id';
>       await _http.delete(url, headers: _headers);
>     } catch (e) {
>       throw _handleError(e);
>     }
>   }
>   // #enddocregion delete
> 
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/heroes_component.dart /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/heroes_component.dart
12d11
< // #docregion metadata, heroes-component-renaming
15d13
<     // #enddocregion heroes-component-renaming
19,21d16
< // #docregion heroes-component-renaming
< // #enddocregion heroes-component-renaming, metadata
< // #docregion class, heroes-component-renaming
23d17
<   // #enddocregion heroes-component-renaming
27a22,24
>   // #docregion error
>   String errorMessage;
>   // #enddocregion error
30a28,52
>   // #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();
>     }
>   }
>   // #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();
>     }
>   }
>   // #enddocregion deleteHero
> 
47d68
<   // #docregion heroes-component-renaming
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib/heroes_component.html /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib/heroes_component.html
3a4,12
> <!-- #docregion add-and-error -->
> <div class="error" *ngIf="errorMessage != null">{{errorMessage}}</div>
> <div>
>   Name: <input #newHeroName />
>   <button (click)="addHero(newHeroName.value); newHeroName.value=''">
>     Add New Hero
>   </button>
> </div>
> <!-- #enddocregion add-and-error -->
8a18,20
>     <!-- #docregion delete -->
>     <button class="delete-button" (click)="deleteHero(hero.id, $event)">x</button>
>     <!-- #enddocregion delete -->
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/lib: in_memory_data_service.dart
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/lib: mock_heroes.dart
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/pubspec.lock /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/pubspec.lock
123a124,129
>   http:
>     description:
>       name: http
>       url: "https://pub.dartlang.org"
>     source: hosted
>     version: "0.11.3+7"
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/pubspec.yaml /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/pubspec.yaml
1c1
< # #docregion
---
> # #docregion , additions
2a3
>   # #enddocregion additions
6a8
>   # #docregion additions
8a11
>   # #enddocregion additions
10a14,15
>   # #docregion additions
>   http: ^0.11.0
12a18
>     # #enddocregion additions
16a23
>     # #docregion additions
17a25,27
>     resolved_identifiers:
>         BrowserClient: 'package:http/browser_client.dart'
>         Client: 'package:http/http.dart'
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/web/index.html /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/web/index.html
1a2
> <!-- #docregion -->
3d3
<   <!-- #docregion head, base-href -->
5d4
<     <!-- For testing using pub serve directly use: -->
7,9d5
<     <!-- For testing in WebStorm use: -->
<     <!-- base href="/dart/web/" -->
<     <!-- #enddocregion base-href -->
13,14d8
<     <!-- #enddocregion head -->
<     <!-- #docregion css -->
16,17c10,11
<     <!-- #enddocregion css -->
<     <!-- #docregion head -->
---
>     <link rel="stylesheet" href="sample.css">
> 
21d14
<   <!-- #enddocregion head -->
diff -r -x .idea -x .pub -x packages -x build -x .packages /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/web/main.dart /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/web/main.dart
0a1,4
> // #docplaster
> // #docregion final
> // #docregion v1
> import 'package:angular2/core.dart';
2c6
< 
---
> import 'package:http/http.dart';
3a8,18
> // #enddocregion v1
> import 'package:angular2_tour_of_heroes/in_memory_data_service.dart';
> 
> void main() {
>   bootstrap(AppComponent, const [
>     const Provider(Client, useClass: InMemoryDataService)
>   ]);
> }
> // #enddocregion final
> /*
> // #docregion v1
6c21
<   bootstrap(AppComponent);
---
>   bootstrap(AppComponent, const [BrowserClient]);
7a23,24
> // #enddocregion v1
> */
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-6/dart/web: sample.css
Only in /Users/chalin/git/ngio/public/docs/_examples/toh-5/dart/web: styles_1.css

Diff finished.  Fri Jun 17 16:00:31 2016

kwalrath · 2016-06-27T20:39:41Z

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

+block http-library
+  :marked
+    We'll be using the !{_Angular_Http} to communicate with a server.
+    This class is exported by the !{_Angular_http_library}.


This paragraph currently says "We'll be using the Dart BrowserClient to communicate with a server. This class is exported by the Dart http library."

A more correct, natural way to say it might be:

We'll be using the http package's BrowserClient class to communicate with a server.

I agree that it is more accurate and that it reads better. I have made the change.

FYI, the http pub page uses both terms

http

A composable, Future-based library for making HTTP requests.

This package contains a set of high-level functions ...

Yes, I saw that too. :) I wasted a few minutes of my life thinking about what that meant, but once I saw that we couldn't get BrowserClient by importing http, muddling the library and package seemed wrong.

kwalrath · 2016-06-28T18:04:30Z

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

+    ### Edit in the *HeroDetailComponent*
+
+    We already have `HeroDetailComponent` for viewing details about a specific hero. 
+    Supporting edit functionality is natural extensions of the detail view, so we are able to reuse `HeroDetailComponent` with a few tweaks. 


natural extensions -> a natural extension

Right. Fixed.

kwalrath · 2016-06-28T18:15:20Z

I didn't try following the steps, but this looks fine. I like how you simplified it (caveat: I didn't try to really understand either version). I had a few comments/questions...

NOTE: this PR depends on angular#1686. Dart prose and example match TS except that: - No child-to-parent event emission occurs. - Support for Add Hero is added as an unconditional feature of the Heroes view. - http `_post` takes only a name - http `delete` takes only a hero id. - The Dart in-memory-data-service has been dropped in favor of an implementation based on the "standard" `http.testing.MockClient` class.

googlebot added the CLA: yes label Jun 17, 2016

Foxandxss added the dart label Jun 18, 2016

chalin force-pushed the chalin-dart-toh-6-new-prose-and-code-0614 branch from 2528a05 to 2b9cdd9 Compare June 26, 2016 19:10

kwalrath reviewed Jun 27, 2016
View reviewed changes

chalin force-pushed the chalin-dart-toh-6-new-prose-and-code-0614 branch from 2b9cdd9 to a33ed7d Compare June 28, 2016 17:47

kwalrath reviewed Jun 28, 2016
View reviewed changes

chalin force-pushed the chalin-dart-toh-6-new-prose-and-code-0614 branch from a33ed7d to 4a2c9ec Compare June 28, 2016 18:36

chalin added 2 commits June 28, 2016 13:00

post-review changes

ef2695d

chalin force-pushed the chalin-dart-toh-6-new-prose-and-code-0614 branch from 4a2c9ec to ef2695d Compare June 28, 2016 20:00

kwalrath merged commit f06398c into angular:master Jun 28, 2016

chalin deleted the chalin-dart-toh-6-new-prose-and-code-0614 branch June 28, 2016 21:02

chalin mentioned this pull request Aug 13, 2016

Update Tutorial to new design scheme using Jade extends/blocks #2108

Closed

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(toh-6/dart): first edition of prose and example code #1687

docs(toh-6/dart): first edition of prose and example code #1687

chalin commented Jun 17, 2016 •

edited

Loading

chalin commented Jun 17, 2016

chalin commented Jun 17, 2016

kwalrath Jun 27, 2016

chalin Jun 27, 2016

kwalrath Jun 27, 2016

kwalrath Jun 28, 2016

chalin Jun 28, 2016

kwalrath commented Jun 28, 2016 •

edited

Loading

docs(toh-6/dart): first edition of prose and example code #1687

docs(toh-6/dart): first edition of prose and example code #1687

Conversation

chalin commented Jun 17, 2016 • edited Loading

chalin commented Jun 17, 2016

chalin commented Jun 17, 2016

kwalrath Jun 27, 2016

Choose a reason for hiding this comment

chalin Jun 27, 2016

Choose a reason for hiding this comment

http

kwalrath Jun 27, 2016

Choose a reason for hiding this comment

kwalrath Jun 28, 2016

Choose a reason for hiding this comment

chalin Jun 28, 2016

Choose a reason for hiding this comment

kwalrath commented Jun 28, 2016 • edited Loading

chalin commented Jun 17, 2016 •

edited

Loading

kwalrath commented Jun 28, 2016 •

edited

Loading