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

block includes
  include ../_util-fns

block http-providers
  //- TODO(chalin): mention the Angular transformer resolved_identifiers.
  //- Maybe not yet at this point in the chapter.

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 http-client-service
  :marked
    The imported `BrowserClient` client service gets
    [injected](dependency-injection.html) into the `HeroService` constructor.
    Note that `BrowserClient` is not part of the Angular core. 
    It's an optional service provided by the Dart 
    [`http` package](https://pub.dartlang.org/packages/http).

block rxjs
  //- N/A

block non-success-status-codes
  :marked
    Because a status code outside the 200-299 range _is an error_ from the
    application point of view, we test for this condition and throw an
    exception when detected.

block parse-json
  :marked
    The response data are in JSON string form.
    We must parse that string into JavaScript 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 — which we've bound conditionally in the
    template — 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.
  +makeExample('server-communication/ts/app/toh/hero-list.component.ts', 'addHero', 'app/toh/hero-list.component.ts (addHero)')(format=".")

block promises
  //- N/A

block wikipedia-jsonp+
  :marked
    Wikipedia offers both `CORS` and `JSONP` search APIs.
  .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`. Here are the
    pertinent details, excerpt from `TohComponent`:
  +makeExample('server-communication/ts/app/toh/toh.component.ts', 'in-mem-web-api', 'app/toh.component.ts (excerpt)')(format=".")