docs(server-communication): cleanup, mainly for Dart (#1455)

- Dart code: fix issues raised by @thso during review.
- Dart code: remove "show x" clauses from imports.
- Dart add docsync config file.
- Prose: make consistent use of _Http variables; otherwise use "HTTP".
- Prose: add links to the demos list.

* _heroesUrl as static const
This commit is contained in:
Patrice Chalin 2016-05-20 17:14:37 -07:00 committed by Kathy Walrath
parent 6d2d52c588
commit da48db3c77
11 changed files with 45 additions and 48 deletions

View File

@ -0,0 +1,4 @@
{
"name": "HTTP client (server communication)"
"docHref": "https://angular.io/docs/dart/latest/guide/server-communication.html"
}

View File

@ -1,13 +1,13 @@
// #docplaster
// #docregion
import "package:angular2/core.dart" show Component;
import 'package:angular2/core.dart';
import "toh/hero_list_component.dart" show HeroListComponent;
import "wiki/wiki_component.dart" show WikiComponent;
import "wiki/wiki_smart_component.dart" show WikiSmartComponent;
import 'toh/hero_list_component.dart';
import 'wiki/wiki_component.dart';
import 'wiki/wiki_smart_component.dart';
@Component(
selector: "my-app",
selector: 'my-app',
template: '''
<hero-list></hero-list>
<my-wiki></my-wiki>

View File

@ -1,4 +1,6 @@
// #docregion
int _toInt(id) => id is int ? id : int.parse(id);
class Hero {
final int id;
final String name;
@ -9,6 +11,4 @@ class Hero {
new Hero(_toInt(hero['id']), hero['name']);
Map toJson() => {'id': id, 'name': name};
static int _toInt(id) => id is int ? id : int.parse(id);
}

View File

@ -6,12 +6,12 @@ import 'dart:convert';
import 'hero.dart';
import 'package:angular2/core.dart';
import 'package:http/browser_client.dart';
import 'package:http/http.dart' show Response;
import 'package:http/http.dart';
@Injectable()
class HeroService {
// #docregion endpoint, http-get
final String _heroesUrl = 'app/heroes'; // URL to web API
static const _heroesUrl = 'app/heroes'; // URL to web API
// #enddocregion endpoint, http-get
final BrowserClient _http;
@ -35,7 +35,7 @@ class HeroService {
// #docregion addhero, addhero-sig
Future<Hero> addHero(String name) async {
// #enddocregion addhero-sig
// #enddocregion addhero-sig
try {
final response = await _http.post(_heroesUrl,
headers: {'Content-Type': 'application/json'},
@ -50,8 +50,8 @@ class HeroService {
// #docregion extract-data
dynamic _extractData(Response res) {
var body = JSON.decode(res.body);
// TODO: once fixed, https://github.com/adaojunior/http-in-memory-web-api/issues/1
// Drop the `?? body` term
// TODO: https://github.com/adaojunior/http-in-memory-web-api/issues/1
// Once #1 is fixed, drop the `?? body` term:
return body['data'] ?? body;
}
// #enddocregion extract-data
@ -69,6 +69,6 @@ class HeroService {
/*
// #docregion endpoint-json
private _heroesUrl = 'heroes.json'; // URL to JSON file
static const _heroesUrl = 'heroes.json'; // URL to JSON file
// #enddocregion endpoint-json
*/

View File

@ -23,4 +23,3 @@ transformers:
resolved_identifiers:
BrowserClient: 'package:http/browser_client.dart'
- dart_to_js_script_rewriter
# #enddocregion transformers

View File

@ -1,10 +1,10 @@
// #docplaster
// #docregion final
import 'package:angular2/core.dart' show Provider;
import 'package:angular2/core.dart';
// #docregion v1
import 'package:angular2/platform/browser.dart' show bootstrap;
import 'package:angular2/platform/browser.dart';
// #docregion http-providers
import 'package:http/browser_client.dart' show BrowserClient;
import 'package:http/browser_client.dart';
// #enddocregion http-providers
import 'package:server_communication/app_component.dart';

View File

@ -80,8 +80,8 @@
},
"server-communication": {
"title": "Http Client",
"intro": "Talk to a remote server with the Angular Http Client."
"title": "HTTP Client",
"intro": "Talk to a remote server with an HTTP Client."
},
"lifecycle-hooks": {

View File

@ -5,11 +5,11 @@ block includes
- var _Http = 'BrowserClient';
- var _Angular_Http = 'Dart <code>BrowserClient</code>'
- var _httpUrl = 'https://pub.dartlang.org/packages/http'
- var _Angular_http_library = 'Dart <a href="!{_httpUrl}"><b>http</b> library</a>'
- var _Angular_http_library = 'Dart <a href="' + _httpUrl + '"><b>http</b></a> library'
block demos-list
li HTTP client: Tour of Heroes
li JSONP client: Wikipedia to fetch data from a service that doesn't support CORS (under development)
li #[a(href="#http-client") HTTP client: Tour of Heroes]
li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] #[b (under development)]
block rxjs-import
//- N/A

View File

@ -80,8 +80,8 @@
},
"server-communication": {
"title": "Http Client",
"intro": "Talk to a remote server with the Angular Http Client."
"title": "HTTP Client",
"intro": "Talk to a remote server with an HTTP Client."
},
"lifecycle-hooks": {

View File

@ -80,8 +80,8 @@
},
"server-communication": {
"title": "Http Client",
"intro": "Talk to a remote server with the Angular Http Client."
"title": "HTTP Client",
"intro": "Talk to a remote server with an HTTP Client."
},
"lifecycle-hooks": {

View File

@ -16,7 +16,7 @@ block includes
[JSONP](https://en.wikipedia.org/wiki/JSONP). A few browsers also support
[Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
The Angular HTTP client library simplifies application programming of the **XHR** and **JSONP** APIs
The !{_Angular_http_library} simplifies application programming of the **XHR** and **JSONP** APIs
as we'll learn in this chapter covering:
ul
@ -30,7 +30,7 @@ ul
li #[a(href="#update") Send data to the server]
+ifDocsFor('ts')
li #[a(href="#promises") Promises instead of observables]
li #[a(href="#cross-origin-requests") Cross-origin requests: Wikipedia example]
li #[a(href="#cors") Cross-origin requests: Wikipedia example]
+ifDocsFor('ts')
ul
li #[a(href="#search-parameters") Set query string parameters]
@ -45,10 +45,10 @@ h1 Demos
p This chapter describes server communication with the help of the following demos
ul
block demos-list
li HTTP client: Tour of Heroes with Observables
li HTTP client: Tour of Heroes with #{_Promise}s
li JSONP client: Wikipedia to fetch data from a service that doesn't support CORS
li JSONP client: Wikipedia using observable operators to reduce server calls
li #[a(href="#http-client") HTTP client: Tour of Heroes with Observables]
li #[a(href="#promises") HTTP client: Tour of Heroes with #{_Promise}s]
li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS]
li #[a(href="#more-observables") JSONP client: Wikipedia using observable operators to reduce server calls]
:marked
These demos are orchestrated by the root `AppComponent`
+makeExample('server-communication/ts/app/app.component.ts', null, 'app/app.component.ts')
@ -58,7 +58,7 @@ block rxjs-import
There is nothing remarkable here _except_ for the import of RxJS operators.
+makeExample('server-communication/ts/app/app.component.ts', 'import-rxjs')(format='.')
:marked
We'll talk about that [below](#rxjs) when we're ready to explore observables.
We'll talk about that [below](#rxjs) when we're ready to explore observables.
:marked
First, we have to configure our application to use server communication facilities.
@ -66,14 +66,14 @@ block rxjs-import
h1#http-providers Providing HTTP Services
:marked
We use the !{_Angular_Http} client to communicate with a server using a familiar HTTP request/response protocol.
The `!{_Http}` client is one of a family of services in the !{_Angular_http_library}.
The `#{_Http}` client is one of a family of services in the !{_Angular_http_library}.
block system-config-of-http
.l-sub-section
:marked
SystemJS knows how to load services from the !{_Angular_http_library} when we import from the `@angular/http` module
because we registered that module name in the `system.config` file.
:marked
Before we can use the `!{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system.
Before we can use the `#{_Http}` client , we'll have to register it as a service provider with the Dependency Injection system.
.l-sub-section
:marked
Learn about providers in the [Dependency Injection](dependency-injection.html) chapter.
@ -84,7 +84,7 @@ p In this demo, we register providers in the #[code bootstrap] method of #[code
block http-providers
:marked
We begin by importing the symbols we need, most of them familiar by now. The newcomer is `HTTP_PROVIDERS`,
a collection of service providers from the Angular HTTP library.
a collection of service providers from the !{_Angular_http_library}.
We register HTTP providers in the bootstrap method by passing them in an array as the second parameter after the root component.
@ -105,10 +105,8 @@ block http-providers
For this reason, and this reason *only*, we hide it *above* the `AppComponent` in `main.ts`.
.l-main-section
a#http-client
h1#http-client The Tour of Heroes #[i HTTP] Client Demo
:marked
# The Tour of Heroes *HTTP* Client Demo
Our 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 us add new heroes, and saves them to the server.
We use the !{_Angular_Http} client to communicate via `XMLHttpRequest (XHR)`.
@ -182,7 +180,7 @@ h2#fetch-data Fetch data with the #[b HeroService]
+makeExample('server-communication/ts/app/toh/hero.service.ts', 'v1', 'app/toh/hero.service.ts (revised)')
:marked
Notice that the Angular `!{_Http}` client service is
Notice that the !{_Angular_Http} client service is
[injected](dependency-injection.html) into the `HeroService` constructor.
+makeExample('server-communication/ts/app/toh/hero.service.ts', 'ctor')
:marked
@ -412,10 +410,8 @@ block hero-list-comp-add-hero
+makeExample('server-communication/ts/app/toh/hero-list.component.ts', 'addHero', 'app/toh/hero-list.component.ts (addHero)')(format=".")
block promises
a#promises
h2#promises Fall back to Promises
:marked
## Fall back to Promises
Although the Angular `http` client API returns an `Observable<Response>` we can turn it into a
[Promise<Response>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) if we prefer.
It's easy to do and a promise-based version looks much like the observable-based version in simple cases.
@ -461,11 +457,9 @@ block promises
Learn more about observables to understand the implications and consequences of subscriptions.
a#cross-origin-requests
h2#cors Cross-origin requests: Wikipedia example
:marked
## Cross-origin requests: Wikipedia example
We just learned how to make `XMLHttpRequests` using Angular's built-in `Http` service.
We just learned how to make `XMLHttpRequests` using the !{_Angular_Http} service.
This is the most common approach for server communication.
It doesn't work in all scenarios.
@ -496,7 +490,7 @@ figure.image-display
block wikipedia-jsonp+
:marked
Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API. Let's use the latter for this example.
The Angular `Jsonp` service both extends the `Http` service for JSONP and restricts us to `GET` requests.
The Angular `Jsonp` service both extends the `#{_Http}` service for JSONP and restricts us to `GET` requests.
All other HTTP methods throw an error because JSONP is a read-only facility.
As always, we wrap our interaction with an Angular data access client service inside a dedicated service, here called `WikipediaService`.