From cfaeea0622aca33ed41338a00533626e181c43bf Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 6 Dec 2016 21:27:11 -0800 Subject: [PATCH] docs(pipes/dart): improve FetchJsonPipe discussion (#2937) Followup to #2923 ``` Suites passed: public/docs/_examples/pipes/dart ``` --- .../pipes/dart/lib/fetch_json_pipe.dart | 16 ++++----- .../pipes/dart/lib/hero_list_component.dart | 7 ++-- public/docs/ts/_cache/guide/pipes.jade | 35 +++++++++++-------- public/docs/ts/latest/guide/pipes.jade | 31 +++++++++------- 4 files changed, 50 insertions(+), 39 deletions(-) diff --git a/public/docs/_examples/pipes/dart/lib/fetch_json_pipe.dart b/public/docs/_examples/pipes/dart/lib/fetch_json_pipe.dart index e5ff8d34d6..60b2472325 100644 --- a/public/docs/_examples/pipes/dart/lib/fetch_json_pipe.dart +++ b/public/docs/_examples/pipes/dart/lib/fetch_json_pipe.dart @@ -8,17 +8,17 @@ import 'package:angular2/angular2.dart'; @Pipe(name: 'fetch', pure: false) // #enddocregion pipe-metadata class FetchJsonPipe extends PipeTransform { - dynamic _fetchedJson; - String _prevUrl; + dynamic _cachedData; + String _cachedUrl; dynamic transform(String url) { - if (url != _prevUrl) { - _prevUrl = url; - _fetchedJson = null; + if (url != _cachedUrl) { + _cachedUrl = url; + _cachedData = null; HttpRequest.getString(url).then((s) { - _fetchedJson = JSON.decode(s); - }); + _cachedData = JSON.decode(s); + }); } - return _fetchedJson; + return _cachedData; } } diff --git a/public/docs/_examples/pipes/dart/lib/hero_list_component.dart b/public/docs/_examples/pipes/dart/lib/hero_list_component.dart index fcbe8c6d1e..84d294065a 100644 --- a/public/docs/_examples/pipes/dart/lib/hero_list_component.dart +++ b/public/docs/_examples/pipes/dart/lib/hero_list_component.dart @@ -5,17 +5,14 @@ import 'fetch_json_pipe.dart'; @Component( selector: 'hero-list', - // #docregion template template: ''' -

Heroes from JSON File

+

Heroes from JSON File

{{hero['name']}}
-

Heroes as JSON: - {{'heroes.json' | fetch | json}} -

+

Heroes as JSON: {{'heroes.json' | fetch | json}}

''', pipes: const [FetchJsonPipe]) class HeroListComponent {} diff --git a/public/docs/ts/_cache/guide/pipes.jade b/public/docs/ts/_cache/guide/pipes.jade index 1d07f08bab..2138f5e541 100644 --- a/public/docs/ts/_cache/guide/pipes.jade +++ b/public/docs/ts/_cache/guide/pipes.jade @@ -162,14 +162,16 @@ figure.image-display figure.image-display img(src='/resources/images/devguide/pipes/power-booster.png' alt="Power Booster") +- var _decls = _docsFor == 'dart' ? 'pipes' : 'declarations'; +- var _appMod = _docsFor == 'dart' ? '@Component' : 'AppModule'; :marked Two things to note: - 1. We use our custom pipe the same way we use the built-in pipes. - 1. We must include our pipe in the `pipes` #{_array} of the `@Component` #{_decorator}. + 1. We use our custom pipe the same way we use built-in pipes. + 1. We must include our pipe in the `!{_decls}` #{_array} of the `!{_appMod}`. .callout.is-helpful - header Remember the pipes #{_array}! + header Remember the !{_decls} #{_array}! :marked Angular reports an error if we neglect to list our custom pipe. We didn't list the `DatePipe` in our previous example because all @@ -186,7 +188,7 @@ figure.image-display We could upgrade the example to a "Power Boost Calculator" that combines our pipe and two-way data binding with `ngModel`. -+makeExample('pipes/ts/app/power-boost-calculator.component.ts', null, '/app/power-boost-calculator.component.ts')(format='.') ++makeExample('app/power-boost-calculator.component.ts') figure.image-display img(src='/resources/images/devguide/pipes/power-boost-calculator-anim.gif' alt="Power Boost Calculator") @@ -331,10 +333,16 @@ block pure-change The only difference is the `pure` flag in the pipe metadata. This is a good candidate for an impure pipe because the `transform` function is trivial and fast. -+makeExample('pipes/ts/app/flying-heroes.pipe.ts','filter')(format='.') - We can derive a `FlyingHeroesImpureComponent` that we derive from the `FlyingHeroesComponent`. -+makeExample('pipes/ts/app/flying-heroes.component.ts','impure-component','app/flying-heroes.component.ts (FlyingHeroesImpureComponent)')(format='.') ++makeExcerpt('app/flying-heroes.pipe.ts','filter', '') + +:marked + We can derive a `FlyingHeroesImpureComponent` from `FlyingHeroesComponent`. + +- var _fnSuffix = _docsFor == 'dart' ? '.component.ts' : '-impure.component.html'; +- var _region = _docsFor == 'dart' ? 'impure-component' : 'template-flying-heroes'; ++makeExcerpt('app/flying-heroes' + _fnSuffix + ' (excerpt)', _region) + :marked The only substantive change is the pipe in the template. We can confirm in the that the _flying heroes_ @@ -361,7 +369,7 @@ h3#async-pipe The impure #[i AsyncPipe] The component doesn't have to subscribe to the async data source, it doesn't extract the resolved values and expose them for binding, and the component doesn't have to unsubscribe when it is destroyed - (a potential source of memory leaks). + (a potent source of memory leaks). ### An impure caching pipe @@ -372,14 +380,14 @@ h3#async-pipe The impure #[i AsyncPipe] We are careful. The pipe only calls the server when the request URL changes and it caches the server response. - Here's the code, which uses the [Angular http](server-communication.html) client to retrieve data: + Here's the code, which uses the [Angular http](server-communication.html) client to retrieve data: -+makeExample('pipes/ts/app/fetch-json.pipe.ts', null, 'app/fetch-json.pipe.ts') ++makeExample('app/fetch-json.pipe.ts') :marked Then we demonstrate it in a harness component whose template defines two bindings to this pipe, both requesting the heroes from the `heroes.json` file. -+makeExample('pipes/ts/app/hero-list.component.ts', null, 'app/hero-list.component.ts') ++makeExample('app/hero-list.component.ts') :marked The component renders like this: @@ -392,7 +400,6 @@ figure.image-display * each pipe instance caches its own url and data * each pipe instance only calls the server once -:marked ### *JsonPipe* The second `fetch` pipe binding above demonstrates more pipe chaining. @@ -404,8 +411,8 @@ figure.image-display The [JsonPipe](../api/common/index/JsonPipe-pipe.html) provides an easy way to diagnosis a mysteriously failing data binding or inspect an object for future binding. - -a(id="pure-pipe-pure-fn") + +a#pure-pipe-pure-fn :marked ### Pure pipes and pure functions diff --git a/public/docs/ts/latest/guide/pipes.jade b/public/docs/ts/latest/guide/pipes.jade index 652bff4f7e..2138f5e541 100644 --- a/public/docs/ts/latest/guide/pipes.jade +++ b/public/docs/ts/latest/guide/pipes.jade @@ -162,14 +162,16 @@ figure.image-display figure.image-display img(src='/resources/images/devguide/pipes/power-booster.png' alt="Power Booster") +- var _decls = _docsFor == 'dart' ? 'pipes' : 'declarations'; +- var _appMod = _docsFor == 'dart' ? '@Component' : 'AppModule'; :marked Two things to note: - 1. We use our custom pipe the same way we use the built-in pipes. - 1. We must include our pipe in the `declarations` #{_array} of the AppModule. + 1. We use our custom pipe the same way we use built-in pipes. + 1. We must include our pipe in the `!{_decls}` #{_array} of the `!{_appMod}`. .callout.is-helpful - header Remember the declarations #{_array}! + header Remember the !{_decls} #{_array}! :marked Angular reports an error if we neglect to list our custom pipe. We didn't list the `DatePipe` in our previous example because all @@ -186,7 +188,7 @@ figure.image-display We could upgrade the example to a "Power Boost Calculator" that combines our pipe and two-way data binding with `ngModel`. -+makeExample('pipes/ts/app/power-boost-calculator.component.ts', null, '/app/power-boost-calculator.component.ts')(format='.') ++makeExample('app/power-boost-calculator.component.ts') figure.image-display img(src='/resources/images/devguide/pipes/power-boost-calculator-anim.gif' alt="Power Boost Calculator") @@ -331,10 +333,16 @@ block pure-change The only difference is the `pure` flag in the pipe metadata. This is a good candidate for an impure pipe because the `transform` function is trivial and fast. -+makeExample('pipes/ts/app/flying-heroes.pipe.ts','filter')(format='.') - We can derive a `FlyingHeroesImpureComponent` that we derive from the `FlyingHeroesComponent`. -+makeExample('pipes/ts/app/flying-heroes-impure.component.html','template-flying-heroes','app/flying-heroes-impure.component.html (FlyingHeroesImpureComponent)')(format='.') ++makeExcerpt('app/flying-heroes.pipe.ts','filter', '') + +:marked + We can derive a `FlyingHeroesImpureComponent` from `FlyingHeroesComponent`. + +- var _fnSuffix = _docsFor == 'dart' ? '.component.ts' : '-impure.component.html'; +- var _region = _docsFor == 'dart' ? 'impure-component' : 'template-flying-heroes'; ++makeExcerpt('app/flying-heroes' + _fnSuffix + ' (excerpt)', _region) + :marked The only substantive change is the pipe in the template. We can confirm in the that the _flying heroes_ @@ -372,14 +380,14 @@ h3#async-pipe The impure #[i AsyncPipe] We are careful. The pipe only calls the server when the request URL changes and it caches the server response. - Here's the code, which uses the [Angular http](server-communication.html) client to retrieve data: + Here's the code, which uses the [Angular http](server-communication.html) client to retrieve data: -+makeExample('pipes/ts/app/fetch-json.pipe.ts', null, 'app/fetch-json.pipe.ts') ++makeExample('app/fetch-json.pipe.ts') :marked Then we demonstrate it in a harness component whose template defines two bindings to this pipe, both requesting the heroes from the `heroes.json` file. -+makeExample('pipes/ts/app/hero-list.component.ts', null, 'app/hero-list.component.ts') ++makeExample('app/hero-list.component.ts') :marked The component renders like this: @@ -392,7 +400,6 @@ figure.image-display * each pipe instance caches its own url and data * each pipe instance only calls the server once -:marked ### *JsonPipe* The second `fetch` pipe binding above demonstrates more pipe chaining. @@ -405,7 +412,7 @@ figure.image-display provides an easy way to diagnosis a mysteriously failing data binding or inspect an object for future binding. -a(id="pure-pipe-pure-fn") +a#pure-pipe-pure-fn :marked ### Pure pipes and pure functions