From da48db3c77ea0af4915b9acc23f70bb9979d9594 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 20 May 2016 17:14:37 -0700 Subject: [PATCH] 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 --- .../server-communication/dart/.docsync.json | 4 ++ .../dart/lib/app_component.dart | 10 ++--- .../dart/lib/toh/hero.dart | 4 +- .../dart/lib/toh/hero_service.dart | 12 +++--- .../server-communication/dart/pubspec.yaml | 1 - .../server-communication/dart/web/main.dart | 6 +-- public/docs/dart/latest/guide/_data.json | 4 +- .../latest/guide/server-communication.jade | 6 +-- public/docs/js/latest/guide/_data.json | 4 +- public/docs/ts/latest/guide/_data.json | 4 +- .../ts/latest/guide/server-communication.jade | 38 ++++++++----------- 11 files changed, 45 insertions(+), 48 deletions(-) create mode 100644 public/docs/_examples/server-communication/dart/.docsync.json diff --git a/public/docs/_examples/server-communication/dart/.docsync.json b/public/docs/_examples/server-communication/dart/.docsync.json new file mode 100644 index 0000000000..09097599c8 --- /dev/null +++ b/public/docs/_examples/server-communication/dart/.docsync.json @@ -0,0 +1,4 @@ +{ + "name": "HTTP client (server communication)" + "docHref": "https://angular.io/docs/dart/latest/guide/server-communication.html" +} diff --git a/public/docs/_examples/server-communication/dart/lib/app_component.dart b/public/docs/_examples/server-communication/dart/lib/app_component.dart index 55c91e6e4d..cd52ca413f 100644 --- a/public/docs/_examples/server-communication/dart/lib/app_component.dart +++ b/public/docs/_examples/server-communication/dart/lib/app_component.dart @@ -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: ''' diff --git a/public/docs/_examples/server-communication/dart/lib/toh/hero.dart b/public/docs/_examples/server-communication/dart/lib/toh/hero.dart index 6e788437c7..a990373a72 100644 --- a/public/docs/_examples/server-communication/dart/lib/toh/hero.dart +++ b/public/docs/_examples/server-communication/dart/lib/toh/hero.dart @@ -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); } diff --git a/public/docs/_examples/server-communication/dart/lib/toh/hero_service.dart b/public/docs/_examples/server-communication/dart/lib/toh/hero_service.dart index d8d602d2e7..5da269fff7 100644 --- a/public/docs/_examples/server-communication/dart/lib/toh/hero_service.dart +++ b/public/docs/_examples/server-communication/dart/lib/toh/hero_service.dart @@ -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 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 */ diff --git a/public/docs/_examples/server-communication/dart/pubspec.yaml b/public/docs/_examples/server-communication/dart/pubspec.yaml index 60e431bf51..6b1e961d75 100644 --- a/public/docs/_examples/server-communication/dart/pubspec.yaml +++ b/public/docs/_examples/server-communication/dart/pubspec.yaml @@ -23,4 +23,3 @@ transformers: resolved_identifiers: BrowserClient: 'package:http/browser_client.dart' - dart_to_js_script_rewriter -# #enddocregion transformers diff --git a/public/docs/_examples/server-communication/dart/web/main.dart b/public/docs/_examples/server-communication/dart/web/main.dart index a66ddb454b..ca055c9d10 100644 --- a/public/docs/_examples/server-communication/dart/web/main.dart +++ b/public/docs/_examples/server-communication/dart/web/main.dart @@ -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'; diff --git a/public/docs/dart/latest/guide/_data.json b/public/docs/dart/latest/guide/_data.json index fe30a34965..4b6553b64d 100644 --- a/public/docs/dart/latest/guide/_data.json +++ b/public/docs/dart/latest/guide/_data.json @@ -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": { diff --git a/public/docs/dart/latest/guide/server-communication.jade b/public/docs/dart/latest/guide/server-communication.jade index 0195d5cb88..51bd3a63db 100644 --- a/public/docs/dart/latest/guide/server-communication.jade +++ b/public/docs/dart/latest/guide/server-communication.jade @@ -5,11 +5,11 @@ block includes - var _Http = 'BrowserClient'; - var _Angular_Http = 'Dart BrowserClient' - var _httpUrl = 'https://pub.dartlang.org/packages/http' - - var _Angular_http_library = 'Dart http library' + - var _Angular_http_library = 'Dart http 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 diff --git a/public/docs/js/latest/guide/_data.json b/public/docs/js/latest/guide/_data.json index 62a168eae5..59ba8dfd01 100644 --- a/public/docs/js/latest/guide/_data.json +++ b/public/docs/js/latest/guide/_data.json @@ -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": { diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index f1f32bbbc6..9fae3fe5be 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -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": { diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade index b41274113c..fb9257d9f0 100644 --- a/public/docs/ts/latest/guide/server-communication.jade +++ b/public/docs/ts/latest/guide/server-communication.jade @@ -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` we can turn it into a [Promise](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`.