docs(pipes) clarify impure pipes; explain missing filter/orderBy pipes

adds flying-heroes example and its test
adds random-pipe example

Author: joeeames

public/docs/_examples/pipes/e2e-spec.js

@@ -5,19 +5,19 @@ describe('Pipes', function () {
   });
 
   it('should open correctly', function () {
-    expect(element.all(by.css('h4')).get(0).getText()).toEqual('Hero Birthday v.1');
-    expect(element(by.css('body > hero-birthday p')).getText()).toEqual("The hero's birthday is Apr 15, 1988");
+    expect(element.all(by.tagName('h1')).get(0).getText()).toEqual('Pipes');
+    expect(element(by.css('hero-birthday p')).getText()).toEqual("The hero's birthday is Apr 15, 1988");
   });
 
-  it('should show delayed message', function () {
-    expect(element.all(by.css('hero-message')).get(0).getText()).toEqual('Message: You are my Hero!');
+  it('should show an async hero message', function () {
+    expect(element.all(by.tagName('hero-message')).get(0).getText()).toContain('hero');
   });
 
   it('should show 4 heroes', function () {
     expect(element.all(by.css('hero-list div')).count()).toEqual(4);
   });
 
-  it('should show 4 heroes in json', function () {
+  it('should show a familiar hero in json', function () {
     expect(element(by.cssContainingText('hero-list p', 'Heroes as JSON')).getText()).toContain('Bombasto');
   });
 
@@ -27,9 +27,9 @@ describe('Pipes', function () {
   });
 
   it('should be able to toggle birthday formats', function () {
-    var birthDayEle = element(by.css('my-app > hero-birthday > p'));
+    var birthDayEle = element(by.css('hero-birthday2 > p'));
     expect(birthDayEle.getText()).toEqual("The hero's birthday is 4/15/1988");
-    var buttonEle = element(by.cssContainingText('my-app > hero-birthday > button', "Toggle Format"));
+    var buttonEle = element(by.cssContainingText('hero-birthday2 > button', "Toggle Format"));
     expect(buttonEle.isDisplayed()).toBe(true);
     buttonEle.click().then(function() {
       expect(birthDayEle.getText()).toEqual("The hero's birthday is Friday, April 15, 1988");
@@ -66,5 +66,52 @@ describe('Pipes', function () {
   });
 
 
+  it('should support flying heroes (pure) ', function () {
+    var nameEle = element(by.css('flying-heroes input[type="text"]'));
+    var canFlyCheckEle = element(by.css('flying-heroes #can-fly'));    
+    var mutateCheckEle = element(by.css('flying-heroes #mutate'));
+    var resetEle = element(by.css('flying-heroes button'));
+    var flyingHeroesEle = element.all(by.css('flying-heroes #flyers div'));
+
+    expect(canFlyCheckEle.getAttribute('checked')).toEqual('true', 'should default to "can fly"');
+    expect(mutateCheckEle.getAttribute('checked')).toEqual('true', 'should default to mutating array');
+    expect(flyingHeroesEle.count()).toEqual(2, 'only two of the original heroes can fly');
+    
+    return sendKeys(nameEle, "test1\n")
+    .then(function(){
+       expect(flyingHeroesEle.count()).toEqual(2, 'no change while mutating array');
+       return mutateCheckEle.click();
+    })
+    .then(function() {
+      return sendKeys(nameEle, "test2\n");
+    })
+    .then(function() {
+      expect(flyingHeroesEle.count()).toEqual(4, 'not mutating; should see both adds');
+      expect(flyingHeroesEle.get(2).getText()).toContain('test1');
+      expect(flyingHeroesEle.get(3).getText()).toContain('test2');
+      return resetEle.click();
+    })
+    .then(function() {
+       expect(flyingHeroesEle.count()).toEqual(2, 'reset should restore orginal flying heroes');
+    })
+  });
+  
+  
+  it('should support flying heroes (impure) ', function () {
+    var nameEle = element(by.css('flying-heroes-impure input[type="text"]'));
+    var canFlyCheckEle = element(by.css('flying-heroes-impure #can-fly'));    
+    var mutateCheckEle = element(by.css('flying-heroes-impure #mutate'));
+    var resetEle = element(by.css('flying-heroes-impure button'));
+    var flyingHeroesEle = element.all(by.css('flying-heroes-impure #flyers div'));
+
+    expect(canFlyCheckEle.getAttribute('checked')).toEqual('true', 'should default to "can fly"');
+    expect(mutateCheckEle.getAttribute('checked')).toEqual('true', 'should default to mutating array');
+    expect(flyingHeroesEle.count()).toEqual(2, 'only two of the original heroes can fly');
+    
+    return sendKeys(nameEle, "test1\n")
+    .then(function(){
+       expect(flyingHeroesEle.count()).toEqual(3, 'new flying hero should show in mutating array');
+    })
+  });
 
 });

public/docs/_examples/pipes/ts/app/app.component.html

@@ -1,11 +1,26 @@
-<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 v.1</a><br>
+<a href="#birthday-date-pipe">Birthday DatePipe</a><br>
+<a href="#happy-birthday2">Happy Birthday v.2</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>
+<a href="#random-pipe">Random Pipe (pure pipe / impure function)</a><br>
+
 
 <hr>
-<hero-list></hero-list>
+<a id="happy-birthday1"></a>
+<h2>Hero Birthday v.1</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-->
@@ -15,33 +30,59 @@
 <!-- #enddocregion format-birthday-->
 
 <hr>
-<h4>Hero Birthday v.2</h4>
-<hero-birthday>loading...</hero-birthday>
-<hr>
-
+<a id="happy-birthday2"></a>
+<h2>Hero Birthday v.2</h2>
+<hero-birthday2></hero-birthday2>
 
-<!-- #docregion chained-birthday -->
+<hr>
+<a id="birthday-pipe-chaining"></a>
+<h2>Birthday Pipe Chaining</h2>
 <p>
+<!-- #docregion chained-birthday -->
   The chained hero's birthday is
   {{ birthday | date | uppercase}}
-</p>
 <!-- #enddocregion chained-birthday -->
+</p>
 
-<!-- #docregion chained-parameter-birthday -->
 <p>
+<!-- #docregion chained-parameter-birthday -->
   The chained hero's birthday is
   {{  birthday | date:'fullDate' | uppercase}}
-</p>
 <!-- #enddocregion chained-parameter-birthday -->
-<!-- #docregion chained-parameter-birthday-parens -->
+</p>
 <p>
+<!-- #docregion chained-parameter-birthday-parens -->
   The chained hero's birthday is
   {{ ( birthday | date:'fullDate' ) | uppercase}}
-</p>
 <!-- #enddocregion chained-parameter-birthday-parens -->
+</p>
+<hr>
+<a id="power-booster"></a>
+<power-booster></power-booster>
+
+<hr>
+<a id="power-boost-calc"></a>
+<power-boost-calculator>loading</power-boost-calculator>
+
+<hr>
+<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>
-<power-booster>loading...</power-booster>
+<a id="hero-list"></a>
+<hero-list></hero-list>
 
 <hr>
-<power-boost-calculator>loading ..</power-boost-calculator>
+<a id="random-pipe"></a>
+<random-pipe></random-pipe>
 
+<div style="margin-top:12em;"></div>

public/docs/_examples/pipes/ts/app/app.component.ts

@@ -1,20 +1,30 @@
 // #docregion
 import {Component} from 'angular2/core';
+import {HTTP_PROVIDERS}    from 'angular2/http';
+
+import {FlyingHeroesComponent,
+        FlyingHeroesImpureComponent} from './flying-heroes.component';
 import {HeroAsyncMessageComponent} from './hero-async-message.component';
-import {HeroBirthday} from './hero-birthday2.component';
+import {HeroBirthday} from './hero-birthday1.component';
+import {HeroBirthday2} from './hero-birthday2.component';
 import {HeroListComponent} from './hero-list.component';
 import {PowerBooster} from './power-booster.component';
 import {PowerBoostCalculator} from './power-boost-calculator.component';
+import {RandomPipeComponent} from './random-pipe.component';
 
 @Component({
   selector: 'my-app',
   templateUrl: 'app/app.component.html',
   directives:[
+    FlyingHeroesComponent, FlyingHeroesImpureComponent,
     HeroAsyncMessageComponent,
     HeroBirthday,
+    HeroBirthday2,
     HeroListComponent,
-    PowerBooster, PowerBoostCalculator
-  ]
+    PowerBooster, PowerBoostCalculator,
+    RandomPipeComponent
+  ],
+  providers:[HTTP_PROVIDERS]
 })
 export class AppComponent {
   birthday = new Date(1988,3,15); // April 15, 1988

public/docs/_examples/pipes/ts/app/exponential-strength.pipe.ts

@@ -11,8 +11,8 @@ import {Pipe, PipeTransform} from 'angular2/core';
 */
 @Pipe({name: 'exponentialStrength'})
 export class ExponentialStrengthPipe implements PipeTransform {
-
-  transform(value:number, args:string[]) : any {
-    return Math.pow(value, parseInt(args[0] || '1', 10));
+  transform(value:number, [exponent]) : number {
+    var exp = parseFloat(exponent);
+    return Math.pow(value, isNaN(exp) ? 1 : exp);
   }
 }

public/docs/_examples/pipes/ts/app/fetch-json.pipe.ts

@@ -1,6 +1,6 @@
-/// <reference path='./window.extension.d.ts'/>
 // #docregion
 import {Pipe, PipeTransform} from 'angular2/core';
+import {Http}                from 'angular2/http';
 
 // #docregion pipe-metadata
 @Pipe({
@@ -9,16 +9,20 @@ import {Pipe, PipeTransform} from 'angular2/core';
 })
 // #enddocregion pipe-metadata
 export class FetchJsonPipe  implements PipeTransform{
-  private fetchedValue:any;
-  private fetchPromise:Promise<any>;
+  private fetched:any = null;
+  private prevUrl = '';
 
-  transform(value:string, args:string[]):any {
-    if (!this.fetchPromise) {
-      this.fetchPromise = window.fetch(value)
-        .then((result:any) => result.json())
-        .then((json:any)   => this.fetchedValue = json);
+  constructor(private _http: Http) { }
+
+  transform(url:string):any {
+    if (url !== this.prevUrl) {
+      this.prevUrl = url;
+      this.fetched = null;
+      this._http.get(url)
+        .map( result => result.json() )
+        .subscribe( result => this.fetched = result )
     }
 
-    return this.fetchedValue;
+    return this.fetched;
   }
-}
+}

public/docs/_examples/pipes/ts/app/flying-heroes.component.html

@@ -0,0 +1,39 @@
+<!-- #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/ts/app/flying-heroes.component.ts

@@ -0,0 +1,64 @@
+// #docplaster
+// #docregion
+import {Component}              from 'angular2/core';
+import {FlyingHeroesPipe,
+        FlyingHeroesImpurePipe} from './flying-heroes.pipe';
+import {HEROES}                 from './heroes';
+
+@Component({
+  selector: 'flying-heroes',
+  templateUrl: 'app/flying-heroes.component.html',
+  styles: ['#flyers, #all {font-style: italic}'],
+  pipes: [FlyingHeroesPipe]
+})
+// #docregion v1
+export class FlyingHeroesComponent {
+  heroes:any[] = [];
+  canFly = true;
+// #enddocregion v1
+  mutate = true;
+  title = 'Flying Heroes (pure pipe)';
+
+// #docregion v1
+  constructor() { this.reset(); }
+
+  addHero(name:string) {
+    name = name.trim();
+    if (!name) { return; }
+    let hero = {name, canFly: this.canFly};
+// #enddocregion v1
+    if (this.mutate) {
+    // Pure pipe won't update display because heroes array reference is unchanged
+    // Impure pipe will display
+// #docregion v1
+// #docregion push
+    this.heroes.push(hero)
+// #enddocregion push
+// #enddocregion v1
+    } else {
+      // Pipe updates display because heroes array is a new object
+// #docregion concat
+      this.heroes = this.heroes.concat(hero);
+// #enddocregion concat
+    }
+// #docregion v1
+  }
+
+  reset() { this.heroes = HEROES.slice(); }
+}
+// #enddocregion v1
+
+////// Identical except for impure pipe //////
+// #docregion impure-component
+@Component({
+  selector: 'flying-heroes-impure',
+  templateUrl: 'app/flying-heroes.component.html',
+// #enddocregion impure-component
+  styles: ['.flyers, .all {font-style: italic}'],
+// #docregion impure-component
+  pipes: [FlyingHeroesImpurePipe]
+})
+export class FlyingHeroesImpureComponent extends FlyingHeroesComponent {
+  title = 'Flying Heroes (impure pipe)';
+}
+// #docregion impure-component