extends ../../../ts/latest/guide/server-communication.jade

block includes
  include ../_util-fns
  - 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></a> library'

block demos-list
  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

block http-client
  
block system-config-of-http
  //- N/A

block http-providers
  :marked
    Actually, it is unnecessary to include `BrowserClient` in the list of providers.
    ***But*** as is mentioned in the *Angular 2 Dart Transformer* [wiki page][ng2dtri],
    the template compiler _generates_ dependency injection code, hence all the
    identifiers used in DI have to be collected by the Angular 2 transformer
    so that the libraries containing these identifiers can be transformed.

    Unless special steps are taken, Dart libraries like `http`
    are not transformed. To ensure that the `BrowserClient` identifier is available
    for DI, we must add a `resolved_identifiers` parameter to the `angular2`
    transformer in `pubspec.yaml`:

    [ng2dtri]: https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer#resolved_identifiers

  - var stylePattern = { pnk: /(resolved_identifiers:|Browser.*)/gm, otl: /(- angular2:)|(transformers:)/g };
  +makeExcerpt('pubspec.yaml', 'transformers', null, stylePattern)

block getheroes-and-addhero
  :marked
    The hero service `getHeroes()` and `addHero()` asynchronous methods return the
    [`Future`](https://api.dartlang.org/stable/1.16.0/dart-async/Future-class.html)
    values of the current hero list and the newly added hero,
    respectively. The hero list component methods of the same name specifying
    the actions to be taken when the asynchronous method calls succeed or fail.

    For more information about `Future`s, consult any one
    of the [articles](https://www.dartlang.org/articles/) on asynchronous
    programming in Dart, or the tutorial on 
    [_Asynchronous Programming: Futures_](https://www.dartlang.org/docs/tutorials/futures/).

block rxjs
  //- N/A

block parse-json
  :marked
    The response data are in JSON string form.
    We must parse that string into Objects which we do by calling
    the `JSON.decode()` method from the `dart:convert` library.

block error-handling
  //- TODO: describe `_handleError`?

block hlc-error-handling
  :marked
    Back in the `HeroListComponent`, we wrapped our call to
    `#{_priv}heroService.getHeroes()` in a `try` clause. When an exception is
    caught, the `errorMessage` variable &mdash; which we've bound conditionally in the
    template &mdash; gets assigned to.

block hero-list-comp-add-hero
  :marked
    Back in the `HeroListComponent`, we see that *its* `addHero()`
    awaits for the *service's* asynchronous `addHero()` to return, and when it does,
    the new hero is added to the `heroes` list for presentation to the user.

block promises
  //- N/A

block wikipedia-jsonp+
  :marked
    Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API.
  .alert.is-important
    :marked
      The remaining content of this section is coming soon.
      In the meantime, consult the 
      [example sources](https://github.com/angular-examples/server-communication)
      to see how to access Wikipedia via its `JSONP` API.

block redirect-to-web-api
  :marked
    To achieve this, we have Angular inject an in-memory web API server
    instance as a provider for the `BrowserClient`. This is possible because
    the in-memory web API server class extends `BrowserClient`.