docs(dev guide): pipes - new dart prose; updated code; ts updates

public/_includes/_util-fns.jade

@@ -15,6 +15,10 @@
 - var _array = 'array';
 - var _an_array = 'an array';
 
+//- Promise vs. Future, etc
+- var _Promise = 'Promise';
+- var _Observable = 'Observable';
+
 //- Used to prefix identifiers that are private. In Dart this will be '_'.
 - var _priv = '';
 

public/docs/_examples/pipes/dart/lib/app_component.dart

@@ -1,20 +1,26 @@
+// #docregion
 import 'package:angular2/angular2.dart';
 
+import 'flying_heroes_component.dart';
 import 'hero_async_message_component.dart';
+import 'hero_birthday1_component.dart';
 import 'hero_birthday2_component.dart';
 import 'hero_list_component.dart';
-import 'power_booster.dart';
-import 'power_boost_calculator.dart';
+import 'power_boost_calculator_component.dart';
+import 'power_booster_component.dart';
 
 @Component(
     selector: 'my-app',
     templateUrl: 'app_component.html',
     directives: const [
+      FlyingHeroesComponent,
+      FlyingHeroesImpureComponent,
       HeroAsyncMessageComponent,
       HeroBirthday,
+      HeroBirthday2,
       HeroListComponent,
+      PowerBoostCalculator,
       PowerBooster,
-      PowerBoostCalculator
     ])
 class AppComponent {
   DateTime birthday = new DateTime(1988, 4, 15); // April 15, 1988

public/docs/_examples/pipes/dart/lib/app_component.html

@@ -1,36 +1,83 @@
-<hr>
-<!-- async examples at the top so can see them in action -->
-<hero-message></hero-message>
+<a id="toc"></a>
+<h1>Pipes</h1>
+<a href="#happy-birthday1">Happy Birthday v1</a><br>
+<a href="#birthday-date-pipe">Birthday DatePipe</a><br>
+<a href="#happy-birthday2">Happy Birthday v2</a><br>
+<a href="#birthday-pipe-chaining">Birthday Pipe Chaining</a><br>
+<a href="#power-booster">Power Booster custom pipe</a><br>
+<a href="#power-boost-calc">Power Boost Calculator custom pipe with params</a><br>
+<a href="#flying-heroes">Flying Heroes filter pipe (pure)</a><br>
+<a href="#flying-heroes-impure">Flying Heroes filter pipe (impure)</a><br>
+<a href="#hero-message">Async Hero Message and AsyncPipe</a><br>
+<a href="#hero-list">Hero List with caching FetchJsonPipe</a><br>
+
 
 <hr>
-<hero-list></hero-list>
+<a id="happy-birthday1"></a>
+<h2>Hero Birthday v1</h2>
+<hero-birthday></hero-birthday>
 
 <hr>
+<a id="birthday-date-pipe"></a>
+<h2>Birthday DatePipe</h2>
+<!-- #docregion hero-birthday-template -->
 <p>The hero's birthday is {{ birthday | date }}</p>
+<!-- #enddocregion hero-birthday-template-->
 
+<!-- #docregion format-birthday -->
 <p>The hero's birthday is {{ birthday | date:"MM/dd/yy" }} </p>
+<!-- #enddocregion format-birthday-->
 
 <hr>
-<h4>Hero Birthday v.2</h4>
-<hero-birthday>loading...</hero-birthday>
-<hr>
-
+<a id="happy-birthday2"></a>
+<h2>Hero Birthday v2</h2>
+<hero-birthday2></hero-birthday2>
 
+<hr>
+<a id="birthday-pipe-chaining"></a>
+<h2>Birthday Pipe Chaining</h2>
 <p>
-    The chained hero's birthday is
-    {{ birthday | date | uppercase}}
+<!-- #docregion chained-birthday -->
+  The chained hero's birthday is
+  {{ birthday | date | uppercase}}
+<!-- #enddocregion chained-birthday -->
 </p>
 
 <p>
-    The chained hero's birthday is
-    {{  birthday | date:'fullDate' | uppercase}}
+<!-- #docregion chained-parameter-birthday -->
+  The chained hero's birthday is
+  {{  birthday | date:'fullDate' | uppercase}}
+<!-- #enddocregion chained-parameter-birthday -->
 </p>
 <p>
-    The chained hero's birthday is
-    {{ ( birthday | date:'fullDate' ) | uppercase}}
+<!-- #docregion chained-parameter-birthday-parens -->
+  The chained hero's birthday is
+  {{ ( birthday | date:'fullDate' ) | uppercase}}
+<!-- #enddocregion chained-parameter-birthday-parens -->
 </p>
 <hr>
-<power-booster>loading...</power-booster>
+<a id="power-booster"></a>
+<power-booster></power-booster>
+
+<hr>
+<a id="power-boost-calc"></a>
+<power-boost-calculator>loading</power-boost-calculator>
 
 <hr>
-<power-boost-calculator>loading ..</power-boost-calculator>
+<a id="flying-heroes"></a>
+<flying-heroes></flying-heroes>
+
+<hr>
+<a id="flying-heroes-impure"></a>
+<flying-heroes-impure></flying-heroes-impure>
+
+<hr>
+<a id="hero-message"></a>
+<!-- async examples at the top so can see them in action -->
+<hero-message></hero-message>
+
+<hr>
+<a id="hero-list"></a>
+<hero-list></hero-list>
+
+<div style="margin-top:12em;"></div>

public/docs/_examples/pipes/dart/lib/exponential_strength_pipe.dart

@@ -1,5 +1,5 @@
+// #docregion
 import 'dart:math' as math;
-
 import 'package:angular2/angular2.dart';
 
 /*
@@ -13,11 +13,13 @@ import 'package:angular2/angular2.dart';
  */
 @Pipe(name: 'exponentialStrength')
 class ExponentialStrengthPipe extends PipeTransform {
-  transform(dynamic value, [List<dynamic> args]) {
-    var v = int.parse(value.toString(), onError: (source) => 0);
-    var p = args.isEmpty
+  num transform(dynamic _value, [List<dynamic> args]) {
+    var exponent = args.isEmpty
         ? 1
-        : int.parse(args.first.toString(), onError: (source) => 1);
-    return math.pow(v, p);
+        : args.first is num
+            ? args.first
+            : num.parse(args.first.toString(), (_) => 1);
+    var value = _value is num ? _value : num.parse(_value.toString(), (_) => 0);
+    return math.pow(value, exponent);
   }
 }

public/docs/_examples/pipes/dart/lib/fetch_json_pipe.dart

@@ -1,23 +1,24 @@
 // #docregion
-import 'dart:html';
-import 'dart:async';
 import 'dart:convert';
+import 'dart:html';
 
 import 'package:angular2/angular2.dart';
 
 // #docregion pipe-metadata
 @Pipe(name: 'fetch', pure: false)
 // #enddocregion pipe-metadata
 class FetchJsonPipe extends PipeTransform {
-  dynamic _fetchedValue;
-  Future<dynamic> _fetchPromise;
+  dynamic _fetchedJson;
+  String _prevUrl;
 
-  transform(dynamic url, [List<dynamic> args]) {
-    if (_fetchPromise == null) {
-      _fetchPromise = new Future(() async {
-        _fetchedValue = JSON.decode(await HttpRequest.getString(url));
-      });
+  dynamic transform(dynamic url, [List<dynamic> args]) {
+    if (url != _prevUrl) {
+      _prevUrl = url;
+      _fetchedJson = null;
+      HttpRequest.getString(url).then((s) {
+          _fetchedJson = JSON.decode(s);
+        });
     }
-    return _fetchedValue;
+    return _fetchedJson;
   }
 }

public/docs/_examples/pipes/dart/lib/flying_heroes_component.dart

@@ -0,0 +1,66 @@
+// #docplaster
+// #docregion
+import 'package:angular2/angular2.dart';
+import 'flying_heroes_pipe.dart';
+import 'heroes.dart';
+
+@Component(
+    selector: 'flying-heroes',
+    templateUrl: 'flying_heroes_component.html',
+    styles: const ['#flyers, #all {font-style: italic}'],
+    pipes: const [FlyingHeroesPipe])
+// #docregion v1
+class FlyingHeroesComponent {
+  List<Hero> heroes;
+  bool canFly = true;
+  // #enddocregion v1
+  bool mutate = true;
+  String title = 'Flying Heroes (pure pipe)';
+
+  // #docregion v1
+  FlyingHeroesComponent() {
+    reset();
+  }
+
+  void addHero(String name) {
+    name = name.trim();
+    if (name.isEmpty) return;
+
+    var hero = new Hero(name, canFly);
+    // #enddocregion v1
+    if (mutate) {
+      // Pure pipe won't update display because heroes list
+      // reference is unchanged; Impure pipe will display.
+      // #docregion v1, push
+      heroes.add(hero);
+      // #enddocregion v1, push
+    } else {
+      // Pipe updates display because heroes list is a new object
+      // #docregion concat
+      heroes = new List<Hero>.from(heroes)..add(hero);
+      // #enddocregion concat
+    }
+    // #docregion v1
+  }
+
+  void reset() {
+    heroes = new List<Hero>.from(mockHeroes);
+  }
+}
+// #enddocregion v1
+
+//\\\\ Identical except for impure pipe \\\\\\
+// #docregion impure-component
+@Component(
+    selector: 'flying-heroes-impure',
+    templateUrl: 'flying_heroes_component.html',
+    // #enddocregion impure-component
+    styles: const ['.flyers, .all {font-style: italic}'],
+    // #docregion impure-component
+    pipes: const [FlyingHeroesImpurePipe])
+class FlyingHeroesImpureComponent extends FlyingHeroesComponent {
+  FlyingHeroesImpureComponent() {
+    title = 'Flying Heroes (impure pipe)';
+  }
+}
+// #docregion impure-component

public/docs/_examples/pipes/dart/lib/flying_heroes_component.html

@@ -0,0 +1,38 @@
+<!-- #docplaster-->
+<!-- #docregion -->
+<h2>{{title}}</h2>
+<p>
+<!-- #docregion template-1 -->
+New hero:
+  <input type="text" #box
+          (keyup.enter)="addHero(box.value); box.value=''"
+          placeholder="hero name">
+<!-- #enddocregion template-1 -->
+  <input id="can-fly" type="checkbox" [(ngModel)]="canFly"> can fly
+</p>
+<p>
+  <input id="mutate" type="checkbox" [(ngModel)]="mutate">Mutate array
+<!-- #docregion template-1 -->
+  <button (click)="reset()">Reset</button>
+<!-- #enddocregion template-1 -->
+</p>
+
+<h4>Heroes who fly (piped)</h4>
+<div id="flyers">
+<!-- #docregion template-flying-heroes -->
+  <div *ngFor="#hero of (heroes | flyingHeroes)">
+    {{hero.name}}
+  </div>
+<!-- #enddocregion template-flying-heroes -->
+</div>
+
+<h4>All Heroes (no pipe)</h4>
+<div id="all">
+<!-- #docregion template-1 -->
+<!-- #docregion template-all-heroes -->
+  <div *ngFor="#hero of heroes">
+    {{hero.name}}
+  </div>
+<!-- #enddocregion template-all-heroes -->
+<!-- #enddocregion template-1 -->
+</div>

public/docs/_examples/pipes/dart/lib/flying_heroes_pipe.dart

@@ -0,0 +1,19 @@
+// #docregion
+// #docregion pure
+import 'package:angular2/angular2.dart';
+import 'heroes.dart';
+
+@Pipe(name: 'flyingHeroes')
+class FlyingHeroesPipe extends PipeTransform {
+  // #docregion filter
+  List<Hero> transform(dynamic value, [List<dynamic> args]) =>
+      value.where((hero) => hero.canFly).toList();
+  // #enddocregion filter
+}
+// #enddocregion pure
+
+// Identical except for the pure flag
+// #docregion impure, pipe-decorator
+@Pipe(name: 'flyingHeroes', pure: false)
+// #enddocregion pipe-decorator
+class FlyingHeroesImpurePipe extends FlyingHeroesPipe {}

public/docs/_examples/pipes/dart/lib/hero_async_message_component.dart

@@ -1,12 +1,32 @@
+// #docregion
 import 'dart:async';
 
 import 'package:angular2/angular2.dart';
 
 @Component(
-    selector: 'hero-message', template: 'Message: {{delayedMessage | async}}')
+    selector: 'hero-message',
+    template: '''
+      <h2>Async Hero Message and AsyncPipe</h2>
+      <p>Message: {{ message | async }}</p>
+      <button (click)="resend()">Resend</button>
+    ''')
 class HeroAsyncMessageComponent {
-  Future<String> delayedMessage =
-      new Future.delayed(new Duration(milliseconds: 500), () {
-    return 'You are my Hero!';
-  });
+  static const _msgEventDelay = const Duration(milliseconds: 500);
+
+  Stream<String> message;
+
+  HeroAsyncMessageComponent() {
+    resend();
+  }
+
+  void resend() {
+    message =
+        new Stream.periodic(_msgEventDelay, (i) => _msgs[i]).take(_msgs.length);
+  }
+
+  List<String> _msgs = <String>[
+    'You are my hero!',
+    'You are the best hero!',
+    'Will you be my hero?'
+  ];
 }

public/docs/_examples/pipes/dart/lib/hero_birthday1_component.dart

@@ -1,10 +1,12 @@
+// #docregion
 import 'package:angular2/angular2.dart';
 
 @Component(
     selector: 'hero-birthday',
-    template: '''
-      <p>The hero's birthday is {{ birthday | date }}</p>
-    ''')
+    // #docregion hero-birthday-template
+    template: "<p>The hero's birthday is {{ birthday | date }}</p>"
+    // #enddocregion hero-birthday-template
+    )
 class HeroBirthday {
   DateTime birthday = new DateTime(1988, 4, 15); // April 15, 1988
 }