docs(cb): Add cookbook for validation (#1627)

* docs(cb-form-validation): create Form Validation Cookbook

* docs(cb-form-validation): ward's tweaks
renamed from cb-validation to cb-form-validation
other refactorings and text changes

* docs(cb-form-validation): add template2 - a step between template and reactive
Raises questions about what really separates Forms from ReactiveForms

public/docs/_examples/cb-form-validation/e2e-spec.ts

@@ -0,0 +1,64 @@
+/// <reference path="../_protractor/e2e.d.ts" />
+'use strict'; // necessary for node!
+describeIf(browser.appIsTs || browser.appIsJs, 'Forms Tests', function () {
+
+  beforeEach(function () {
+    browser.get('');
+  });
+
+  it('should display correct title', function () {
+    expect(element.all(by.css('h1')).get(0).getText()).toEqual('Hero Form');
+  });
+
+
+  it('should not display message before submit', function () {
+    let ele = element(by.css('h2'));
+    expect(ele.isDisplayed()).toBe(false);
+  });
+
+  it('should hide form after submit', function () {
+    let ele = element.all(by.css('h1')).get(0);
+    expect(ele.isDisplayed()).toBe(true);
+    let b = element.all(by.css('button[type=submit]')).get(0);
+    b.click().then(function() {
+      expect(ele.isDisplayed()).toBe(false);
+    });
+  });
+
+  it('should display message after submit', function () {
+    let b = element.all(by.css('button[type=submit]')).get(0);
+    b.click().then(function() {
+      expect(element(by.css('h2')).getText()).toContain('You submitted the following');
+    });
+  });
+
+  it('should hide form after submit', function () {
+    let alterEgoEle = element.all(by.css('input[ngcontrol=alterEgo]')).get(0);
+    expect(alterEgoEle.isDisplayed()).toBe(true);
+    let submitButtonEle = element.all(by.css('button[type=submit]')).get(0);
+    submitButtonEle.click().then(function() {
+      expect(alterEgoEle.isDisplayed()).toBe(false);
+    });
+  });
+
+  it('should reflect submitted data after submit', function () {
+    let test = 'testing 1 2 3';
+    let newValue: string;
+    let alterEgoEle = element.all(by.css('input[ngcontrol=alterEgo]')).get(0);
+    alterEgoEle.getAttribute('value').then(function(value) {
+      // alterEgoEle.sendKeys(test);
+      sendKeys(alterEgoEle, test);
+      newValue = value + test;
+      expect(alterEgoEle.getAttribute('value')).toEqual(newValue);
+    }).then(function() {
+      let b = element.all(by.css('button[type=submit]')).get(0);
+      return b.click();
+    }).then(function() {
+      let alterEgoTextEle = element(by.cssContainingText('div', 'Alter Ego'));
+      expect(alterEgoTextEle.isPresent()).toBe(true, 'cannot locate "Alter Ego" label');
+      let divEle = element(by.cssContainingText('div', newValue));
+      expect(divEle.isPresent()).toBe(true, 'cannot locate div with this text: ' + newValue);
+    });
+  });
+});
+

public/docs/_examples/cb-form-validation/ts/app/app.component.ts

@@ -0,0 +1,12 @@
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'my-app',
+  template: `<hero-form-template1></hero-form-template1>
+             <hr>
+             <hero-form-template2></hero-form-template2>
+             <hr>
+             <hero-form-reactive3></hero-form-reactive3>`
+})
+export class AppComponent { }

public/docs/_examples/cb-form-validation/ts/app/app.module.ts

@@ -0,0 +1,18 @@
+// #docregion
+import { NgModule }      from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+
+import { AppComponent }           from './app.component';
+import { HeroFormTemplateModule } from './template/hero-form-template.module';
+import { HeroFormReactiveModule } from './reactive/hero-form-reactive.module';
+
+@NgModule({
+  imports: [
+    BrowserModule,
+    HeroFormTemplateModule,
+    HeroFormReactiveModule
+  ],
+  declarations: [ AppComponent ],
+  bootstrap:    [ AppComponent ]
+})
+export class AppModule { }

public/docs/_examples/cb-form-validation/ts/app/main.ts

@@ -0,0 +1,6 @@
+// #docregion
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app.module';
+
+platformBrowserDynamic().bootstrapModule(AppModule);

public/docs/_examples/cb-form-validation/ts/app/reactive/hero-form-reactive.component.html

@@ -0,0 +1,47 @@
+ <!-- #docregion -->
+<div class="container">
+  <div [hidden]="submitted">
+    <h1>Hero Form 3 (Reactive)</h1>
+    <!-- #docregion form-tag-->
+    <form [formGroup]="heroForm"  *ngIf="active"  (ngSubmit)="onSubmit()">
+    <!-- #enddocregion form-tag-->
+      <div class="form-group">
+        <!-- #docregion name-with-error-msg -->
+        <label for="name">Name</label>
+
+        <input type="text" id="name" class="form-control"
+               formControlName="name" required >
+
+        <div *ngIf="formErrors.name" class="alert alert-danger">
+          {{ formErrors.name }}
+        </div>
+        <!-- #enddocregion name-with-error-msg -->
+      </div>
+
+      <div class="form-group">
+        <label for="alterEgo">Alter Ego</label>
+        <input type="text" id="alterEgo" class="form-control"
+            formControlName="alterEgo"  >
+      </div>
+
+      <div class="form-group">
+        <label for="power">Hero Power</label>
+        <select id="power" class="form-control"
+            formControlName="power" required >
+          <option *ngFor="let p of powers" [value]="p">{{p}}</option>
+        </select>
+
+        <div *ngIf="formErrors.power" class="alert alert-danger">
+          {{ formErrors.power }}
+        </div>
+      </div>
+
+      <button type="submit" class="btn btn-default"
+             [disabled]="!heroForm.valid">Submit</button>
+      <button type="button" class="btn btn-default"
+             (click)="addHero()">New Hero</button>
+    </form>
+  </div>
+
+  <hero-submitted [hero]="hero" [(submitted)]="submitted"></hero-submitted>
+</div>

public/docs/_examples/cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts

@@ -0,0 +1,115 @@
+/* tslint:disable: member-ordering forin */
+// #docplaster
+// #docregion
+import { Component, OnInit }                  from '@angular/core';
+import { FormGroup, FormBuilder, Validators } from '@angular/forms';
+
+import { Hero }                   from '../shared/hero';
+import { forbiddenNameValidator } from '../shared/forbidden-name.directive';
+
+@Component({
+  moduleId:  module.id,
+  selector: 'hero-form-reactive3',
+  templateUrl: 'hero-form-reactive.component.html'
+})
+export class HeroFormReactiveComponent implements OnInit {
+
+  powers = ['Really Smart', 'Super Flexible', 'Weather Changer'];
+
+  hero = new Hero(18, 'Dr. WhatIsHisName', this.powers[0], 'Dr. What');
+
+  submitted = false;
+
+  // #docregion on-submit
+  onSubmit() {
+    this.submitted = true;
+    this.hero = this.heroForm.value;
+  }
+  // #enddocregion on-submit
+// #enddocregion
+
+  // Reset the form with a new hero AND restore 'pristine' class state
+  // by toggling 'active' flag which causes the form
+  // to be removed/re-added in a tick via NgIf
+  // TODO: Workaround until NgForm has a reset method (#6822)
+  active = true;
+// #docregion
+  // #docregion add-hero
+  addHero() {
+    this.hero = new Hero(42, '', '');
+    this.buildForm();
+    this.onValueChanged();
+  // #enddocregion add-hero
+// #enddocregion class
+
+    this.active = false;
+    setTimeout(() => this.active = true, 0);
+// #docregion
+  // #docregion add-hero
+  }
+  // #enddocregion add-hero
+
+  // #docregion form-builder
+  heroForm: FormGroup;
+  constructor(private fb: FormBuilder) { }
+
+  ngOnInit(): void {
+    this.buildForm();
+  }
+
+  buildForm(): void {
+    this.heroForm = this.fb.group({
+      // #docregion name-validators
+      'name': [this.hero.name, [
+          Validators.required,
+          Validators.minLength(4),
+          Validators.maxLength(24),
+          forbiddenNameValidator(/bob/i)
+        ]
+      ],
+      // #enddocregion name-validators
+      'alterEgo': [this.hero.alterEgo],
+      'power':    [this.hero.power, Validators.required]
+    });
+
+    this.heroForm.valueChanges
+      .subscribe(data => this.onValueChanged(data));
+  }
+
+  // #enddocregion form-builder
+
+  onValueChanged(data?: any) {
+    const controls = this.heroForm ? this.heroForm.controls : {};
+
+    for (const field in this.formErrors) {
+      // clear previous error message (if any)
+      this.formErrors[field] = '';
+      const control = controls[field];
+
+      if (control && control.dirty && !control.valid) {
+        const messages = this.validationMessages[field];
+        for (const key in control.errors) {
+          this.formErrors[field] += messages[key] + ' ';
+        }
+      }
+    }
+  }
+
+  formErrors = {
+    'name': '',
+    'power': ''
+  };
+
+  validationMessages = {
+    'name': {
+      'required':      'Name is required.',
+      'minlength':     'Name must be at least 4 characters long.',
+      'maxlength':     'Name cannot be more than 24 characters long.',
+      'forbiddenName': 'Someone named "Bob" cannot be a hero.'
+    },
+    'power': {
+      'required': 'Power is required.'
+    }
+  };
+}
+// #enddocregion

public/docs/_examples/cb-form-validation/ts/app/reactive/hero-form-reactive.module.ts

@@ -0,0 +1,13 @@
+// #docregion
+import { NgModule }            from '@angular/core';
+import { ReactiveFormsModule } from '@angular/forms';
+
+import { SharedModule }              from '../shared/shared.module';
+import { HeroFormReactiveComponent } from './hero-form-reactive.component';
+
+@NgModule({
+  imports:      [ SharedModule, ReactiveFormsModule ],
+  declarations: [ HeroFormReactiveComponent ],
+  exports:      [ HeroFormReactiveComponent ]
+})
+export class HeroFormReactiveModule { }

public/docs/_examples/cb-form-validation/ts/app/shared/forbidden-name.directive.ts

@@ -0,0 +1,43 @@
+// #docregion
+import { Directive, Input, OnChanges, SimpleChanges } from '@angular/core';
+import { AbstractControl, NG_VALIDATORS, Validator, ValidatorFn, Validators } from '@angular/forms';
+
+// #docregion custom-validator
+/** A hero's name can't match the given regular expression */
+export function forbiddenNameValidator(nameRe: RegExp): ValidatorFn {
+  return (control: AbstractControl): {[key: string]: any} => {
+    const name = control.value;
+    const no = nameRe.test(name);
+    return no ? {'forbiddenName': {name}} : null;
+  };
+}
+// #enddocregion custom-validator
+
+// #docregion directive
+@Directive({
+  selector: '[forbiddenName]',
+  // #docregion directive-providers
+  providers: [{provide: NG_VALIDATORS, useExisting: ForbiddenValidatorDirective, multi: true}]
+  // #enddocregion directive-providers
+})
+export class ForbiddenValidatorDirective implements Validator, OnChanges {
+  @Input() forbiddenName: string;
+  private valFn = Validators.nullValidator;
+
+  ngOnChanges(changes: SimpleChanges): void {
+    const change = changes['forbiddenName'];
+    if (change) {
+      const val: string | RegExp = change.currentValue;
+      const re = val instanceof RegExp ? val : new RegExp(val, 'i');
+      this.valFn = forbiddenNameValidator(re);
+    } else {
+      this.valFn = Validators.nullValidator;
+    }
+  }
+
+  validate(control: AbstractControl): {[key: string]: any} {
+    return this.valFn(control);
+  }
+}
+// #docregion directive
+

public/docs/_examples/cb-form-validation/ts/app/shared/hero.ts

@@ -0,0 +1,9 @@
+// #docregion
+export class Hero {
+  constructor(
+    public id: number,
+    public name: string,
+    public power: string,
+    public alterEgo?: string
+  ) {  }
+}

public/docs/_examples/cb-form-validation/ts/app/shared/shared.module.ts

@@ -0,0 +1,14 @@
+// #docregion
+import { NgModule }     from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+import { ForbiddenValidatorDirective } from './forbidden-name.directive';
+import { SubmittedComponent }          from './submitted.component';
+
+@NgModule({
+  imports:      [ CommonModule],
+  declarations: [ ForbiddenValidatorDirective, SubmittedComponent ],
+  exports:      [ ForbiddenValidatorDirective, SubmittedComponent,
+                  CommonModule ]
+})
+export class SharedModule { }

public/docs/_examples/cb-form-validation/ts/app/shared/submitted.component.ts

@@ -0,0 +1,32 @@
+// #docregion
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+
+import { Hero } from './hero';
+
+@Component({
+  selector: 'hero-submitted',
+  template: `
+  <div *ngIf="submitted">
+    <h2>You submitted the following:</h2>
+    <div class="row">
+      <div class="col-xs-3">Name</div>
+      <div class="col-xs-9  pull-left">{{ hero.name }}</div>
+    </div>
+    <div class="row">
+      <div class="col-xs-3">Alter Ego</div>
+      <div class="col-xs-9 pull-left">{{ hero.alterEgo }}</div>
+    </div>
+    <div class="row">
+      <div class="col-xs-3">Power</div>
+      <div class="col-xs-9 pull-left">{{ hero.power }}</div>
+    </div>
+    <br>
+    <button class="btn btn-default" (click)="onClick()">Edit</button>
+  </div>`
+})
+export class SubmittedComponent {
+  @Input()  hero: Hero;
+  @Input()  submitted = false;
+  @Output() submittedChange = new EventEmitter<boolean>();
+  onClick() { this.submittedChange.emit(false); }
+}

public/docs/_examples/cb-form-validation/ts/app/template/hero-form-template.module.ts

@@ -0,0 +1,14 @@
+// #docregion
+import { NgModule }     from '@angular/core';
+import { FormsModule }  from '@angular/forms';
+
+import { SharedModule }               from '../shared/shared.module';
+import { HeroFormTemplate1Component } from './hero-form-template1.component';
+import { HeroFormTemplate2Component } from './hero-form-template2.component';
+
+@NgModule({
+  imports:      [ SharedModule, FormsModule ],
+  declarations: [ HeroFormTemplate1Component, HeroFormTemplate2Component ],
+  exports:      [ HeroFormTemplate1Component, HeroFormTemplate2Component ]
+})
+export class HeroFormTemplateModule { }

public/docs/_examples/cb-form-validation/ts/app/template/hero-form-template1.component.html

@@ -0,0 +1,61 @@
+ <!-- #docregion -->
+<div class="container">
+  <div [hidden]="submitted">
+    <h1>Hero Form 1 (Template)</h1>
+    <!-- #docregion form-tag-->
+    <form #heroForm="ngForm"  *ngIf="active"  (ngSubmit)="onSubmit()">
+    <!-- #enddocregion form-tag-->
+      <div class="form-group">
+        <!-- #docregion name-with-error-msg -->
+        <label for="name">Name</label>
+
+        <input type="text" id="name" class="form-control"
+               required minlength="4" maxlength="24"
+               name="name" [(ngModel)]="hero.name"
+               #name="ngModel" >
+
+        <div *ngIf="name.errors && (name.dirty || name.touched)"
+             class="alert alert-danger">
+            <div [hidden]="!name.errors.required">
+              Name is required
+            </div>
+            <div [hidden]="!name.errors.minlength">
+              Name must be at least 4 characters long.
+            </div>
+            <div [hidden]="!name.errors.maxlength">
+              Name cannot be more than 24 characters long.
+            </div>
+        </div>
+        <!-- #enddocregion name-with-error-msg -->
+      </div>
+
+      <div class="form-group">
+        <label for="alterEgo">Alter Ego</label>
+        <input type="text" id="alterEgo" class="form-control"
+               name="alterEgo"
+               [(ngModel)]="hero.alterEgo" >
+      </div>
+
+      <div class="form-group">
+        <label for="power">Hero Power</label>
+        <select id="power" class="form-control"
+                name="power"
+                [(ngModel)]="hero.power" required
+                #power="ngModel" >
+          <option *ngFor="let p of powers" [value]="p">{{p}}</option>
+        </select>
+
+        <div *ngIf="power.errors && power.touched" class="alert alert-danger">
+          <div [hidden]="!power.errors.required">Power is required</div>
+        </div>
+      </div>
+
+      <button type="submit" class="btn btn-default"
+             [disabled]="!heroForm.form.valid">Submit</button>
+      <button type="button" class="btn btn-default"
+             (click)="addHero()">New Hero</button>
+    </form>
+  </div>
+
+  <hero-submitted [hero]="hero" [(submitted)]="submitted"></hero-submitted>
+</div>

public/docs/_examples/cb-form-validation/ts/app/template/hero-form-template1.component.ts

@@ -0,0 +1,48 @@
+/* tslint:disable: member-ordering */
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+
+
+import { Hero }      from '../shared/hero';
+
+@Component({
+  moduleId:  module.id,
+  selector: 'hero-form-template1',
+  templateUrl: 'hero-form-template1.component.html'
+})
+// #docregion class
+export class HeroFormTemplate1Component {
+
+  powers = ['Really Smart', 'Super Flexible', 'Weather Changer'];
+
+  hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What');
+
+  submitted = false;
+
+  onSubmit() {
+    this.submitted = true;
+  }
+// #enddocregion class
+// #enddocregion
+  // Reset the form with a new hero AND restore 'pristine' class state
+  // by toggling 'active' flag which causes the form
+  // to be removed/re-added in a tick via NgIf
+  // TODO: Workaround until NgForm has a reset method (#6822)
+  active = true;
+// #docregion
+// #docregion class
+
+  addHero() {
+    this.hero = new Hero(42, '', '');
+// #enddocregion class
+// #enddocregion
+
+    this.active = false;
+    setTimeout(() => this.active = true, 0);
+// #docregion
+// #docregion class
+  }
+}
+// #enddocregion class
+// #enddocregion

public/docs/_examples/cb-form-validation/ts/app/template/hero-form-template2.component.html

@@ -0,0 +1,52 @@
+ <!-- #docregion -->
+<div class="container">
+  <div [hidden]="submitted">
+    <h1>Hero Form 2 (Template & Messages)</h1>
+    <!-- #docregion form-tag-->
+    <form #heroForm="ngForm"  *ngIf="active"  (ngSubmit)="onSubmit()">
+    <!-- #enddocregion form-tag-->
+      <div class="form-group">
+        <!-- #docregion name-with-error-msg -->
+        <label for="name">Name</label>
+
+        <!-- #docregion name-input -->
+        <input type="text" id="name" class="form-control"
+               required minlength="4" maxlength="24" forbiddenName="bob"
+               name="name" [(ngModel)]="hero.name" >
+        <!-- #enddocregion name-input -->
+
+        <div *ngIf="formErrors.name" class="alert alert-danger">
+          {{ formErrors.name }}
+        </div>
+        <!-- #enddocregion name-with-error-msg -->
+      </div>
+
+      <div class="form-group">
+        <label for="alterEgo">Alter Ego</label>
+        <input type="text" id="alterEgo" class="form-control"
+               name="alterEgo"
+               [(ngModel)]="hero.alterEgo" >
+      </div>
+
+      <div class="form-group">
+        <label for="power">Hero Power</label>
+        <select id="power" class="form-control"
+                name="power"
+                [(ngModel)]="hero.power" required >
+          <option *ngFor="let p of powers" [value]="p">{{p}}</option>
+        </select>
+
+        <div *ngIf="formErrors.power" class="alert alert-danger">
+          {{ formErrors.power }}
+        </div>
+      </div>
+
+      <button type="submit" class="btn btn-default"
+             [disabled]="!heroForm.form.valid">Submit</button>
+      <button type="button" class="btn btn-default"
+             (click)="addHero()">New Hero</button>
+    </form>
+  </div>
+
+  <hero-submitted [hero]="hero" [(submitted)]="submitted"></hero-submitted>
+</div>

public/docs/_examples/cb-form-validation/ts/app/template/hero-form-template2.component.ts

@@ -0,0 +1,99 @@
+/* tslint:disable: member-ordering forin */
+// #docplaster
+// #docregion
+import { Component, AfterViewChecked, ViewChild } from '@angular/core';
+import { NgForm } from '@angular/forms';
+
+import { Hero }      from '../shared/hero';
+
+@Component({
+  moduleId:  module.id,
+  selector: 'hero-form-template2',
+  templateUrl: 'hero-form-template2.component.html'
+})
+export class HeroFormTemplate2Component implements AfterViewChecked {
+
+  powers = ['Really Smart', 'Super Flexible', 'Weather Changer'];
+
+  hero = new Hero(18, 'Dr. WhatIsHisWayTooLongName', this.powers[0], 'Dr. What');
+
+  submitted = false;
+
+  onSubmit() {
+    this.submitted = true;
+  }
+// #enddocregion
+
+  // Reset the form with a new hero AND restore 'pristine' class state
+  // by toggling 'active' flag which causes the form
+  // to be removed/re-added in a tick via NgIf
+  // TODO: Workaround until NgForm has a reset method (#6822)
+  active = true;
+// #docregion
+
+  addHero() {
+    this.hero = new Hero(42, '', '');
+// #enddocregion
+
+    this.active = false;
+    setTimeout(() => this.active = true, 0);
+// #docregion
+  }
+
+  // #docregion view-child
+  heroForm: NgForm;
+  @ViewChild('heroForm') currentForm: NgForm;
+
+  ngAfterViewChecked() {
+    this.formChanged();
+  }
+
+  formChanged() {
+    if (this.currentForm === this.heroForm) { return; }
+    this.heroForm = this.currentForm;
+    if (this.heroForm) {
+      this.heroForm.valueChanges
+        .subscribe(data => this.onValueChanged(data));
+    }
+  }
+  // #enddocregion view-child
+
+  // #docregion handler
+  onValueChanged(data?: any) {
+    const controls = this.heroForm ? this.heroForm.controls : {};
+
+    for (const field in this.formErrors) {
+      // clear previous error message (if any)
+      this.formErrors[field] = '';
+      const control = controls[field];
+
+      if (control && control.dirty && !control.valid) {
+        const messages = this.validationMessages[field];
+        for (const key in control.errors) {
+          this.formErrors[field] += messages[key] + ' ';
+        }
+      }
+    }
+  }
+
+  formErrors = {
+    'name': '',
+    'power': ''
+  };
+  // #enddocregion handler
+
+  // #docregion messages
+  validationMessages = {
+    'name': {
+      'required':      'Name is required.',
+      'minlength':     'Name must be at least 4 characters long.',
+      'maxlength':     'Name cannot be more than 24 characters long.',
+      'forbiddenName': 'Someone named "Bob" cannot be a hero.'
+    },
+    'power': {
+      'required': 'Power is required.'
+    }
+  };
+  // #enddocregion messages
+}
+// #enddocregion

public/docs/_examples/cb-form-validation/ts/forms.css

@@ -0,0 +1,11 @@
+.ng-valid[required] {
+  border-left: 5px solid #42A948; /* green */
+}
+
+.ng-invalid {
+  border-left: 5px solid #a94442; /* red */
+}
+
+.ng-valid.required {
+  border-left: 5px solid #42A948; /* green */
+}

public/docs/_examples/cb-form-validation/ts/index.html

@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <title>Hero Form with Validation</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="styles.css">
+
+    <link rel="stylesheet" href="node_modules/bootstrap/dist/css/bootstrap.min.css">
+    <link rel="stylesheet" href="styles.css">
+    <link rel="stylesheet" href="forms.css">
+
+    <!-- Polyfill(s) for older browsers -->
+    <script src="node_modules/core-js/client/shim.min.js"></script>
+
+    <script src="node_modules/zone.js/dist/zone.js"></script>
+    <script src="node_modules/reflect-metadata/Reflect.js"></script>
+    <script src="node_modules/systemjs/dist/system.src.js"></script>
+
+    <script src="systemjs.config.js"></script>
+    <script>
+      System.import('app').catch(function(err){ console.error(err); });
+    </script>
+  </head>
+
+  <body>
+    <my-app>Loading...</my-app>
+  </body>
+</html>
+

public/docs/_examples/cb-form-validation/ts/plnkr.json

@@ -0,0 +1,7 @@
+{
+  "description": "Validation",
+  "files":[
+    "!**/*.d.ts",  
+    "!**/*.js"
+  ]
+}

public/docs/dart/latest/cookbook/_data.json

@@ -41,6 +41,12 @@
     "hide": true
   },
 
+  "form-validation": {
+    "title": "Form Validation",
+    "intro": "Validate user's form entries",
+    "hide": true
+  },
+
   "rc4-to-rc5": {
     "title": "RC4 to RC5 Migration",
     "intro": "Migrate your RC4 app to RC5 in minutes.",

public/docs/dart/latest/cookbook/form-validation.jade

@@ -0,0 +1 @@
+!= partial("../../../_includes/_ts-temp")

public/docs/js/latest/cookbook/_data.json

@@ -37,6 +37,11 @@
     "intro": "Render dynamic forms with NgFormModel"
   },
 
+  "form-validation": {
+    "title": "Form Validation",
+    "intro": "Validate user's form entries"
+  },
+
   "rc4-to-rc5": {
     "title": "RC4 to RC5 Migration",
     "intro": "Migrate your RC4 app to RC5 in minutes.",

public/docs/js/latest/cookbook/form-validation.jade

@@ -0,0 +1 @@
+!= partial("../../../_includes/_ts-temp")

public/docs/ts/latest/cookbook/_data.json

@@ -43,6 +43,11 @@
     "intro": "Render dynamic forms with FormGroup"
   },
 
+  "form-validation": {
+    "title": "Form Validation",
+    "intro": "Validate user's form entries"
+  },
+
   "rc4-to-rc5": {
     "title": "RC4 to RC5 Migration",
     "intro": "Migrate your RC4 app to RC5 in minutes."

public/docs/ts/latest/cookbook/form-validation.jade

@@ -0,0 +1,462 @@
+include ../_util-fns
+
+a#top
+:marked
+  We can improve overall data quality by validating user input for accuracy and completeness.
+
+  In this cookbook we show how to validate user input in the UI and display useful validation messages 
+  using first the template-driven forms and then the reactive forms approach.
+.l-sub-section
+  :marked
+    Learn more about these choices in the [Forms chapter.](../guide/forms.html)
+
+a#toc
+:marked
+  ## Contents
+
+    [Simple Template-Driven Forms](#template1)
+
+    [Template-Driven Forms with validation messages in code](#template2)
+
+    [Reactive Forms with validation in code](#reactive)
+
+    [Custom validation](#custom-validation)
+
+    [Testing](#testing)
+
+a#live-example
+:marked
+  **Try the live example to see and download the full cookbook source code**
+live-example(name="cb-form-validation" embedded img="cookbooks/form-validation/plunker.png")
+
+.l-main-section
+a#template1
+:marked
+   ## Simple Template-Driven Forms
+
+   In the template-driven approach, you arrange 
+   [form elements](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Forms_in_HTML) in the component's template.
+
+   You add Angular form directives (mostly directives beginning `ng...`) to help
+   Angular construct a corresponding internal control model that implements form functionality.
+   We say that the control model is _implicit_ in the template.
+
+   To validate user input, you add [HTML validation attributes](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) 
+   to the elements. Angular interprets those as well, adding validator functions to the control model.
+
+   Angular exposes information about the state of the controls including 
+   whether the user has "touched" the control or made changes and if the control values are valid.
+
+   In the first template validation example, 
+   we add more HTML to read that control state and update the display appropriately.
+   Here's an excerpt from the template html for a single input box control bound to the hero name:
++makeExample('cb-form-validation/ts/app/template/hero-form-template1.component.html','name-with-error-msg','template/hero-form-template1.component.html (Hero name)')(format='.')
+
+:marked
+  Note the following:
+  - The `<input>` element carries the HTML validation attributes: `required`, `minlength`, and `maxlength`.
+
+  - We set the `name` attribute of the input box to `"name"` so Angular can track this input element and associate it
+  with an Angular form control called `name` in its internal control model.
+
+  - We use the `[(ngModel)]` directive to two-way data bind the input box to the `hero.name` property.
+  
+  - We set a template variable (`#name`) to the value `"ngModel"` (always `ngModel`).
+  This gives us a reference to the Angular `NgModel` directive 
+  associated with this control that we can use _in the template_
+  to check for control states such as `valid` and `dirty`.
+
+  - The `*ngIf` on `<div>` element reveals a set of nested message `divs` but only if there are "name" errors and
+  the control is either `dirty` or `touched`.
+
+  - Each nested `<div>` can present a custom message for one of the possible validation errors.
+  We've prepared messages for `required`, `minlength`, and `maxlength`.
+
+  The full template repeats this kind of layout for each data entry control on the form.
+.l-sub-section
+  :marked
+    #### Why check _dirty_ and _touched_?
+
+    We shouldn't show errors for a new hero before the user has had a chance to edit the value.
+    The checks for `dirty` and `touched` prevent premature display of errors.
+
+    Learn about `dirty` and `touched` in the [Forms](../guide/forms.html) chapter.
+:marked
+  The component class manages the hero model used in the data binding
+  as well as other code to support the view.
+
++makeExample('cb-form-validation/ts/app/template/hero-form-template1.component.ts','class','template/hero-form-template1.component.ts (class)')
+
+:marked
+   Use this template-driven validation technique when working with static forms with simple, standard validation rules.
+
+   Here are the complete files for the first version of `HeroFormTemplateCompononent` in the template-driven approach:
+
++makeTabs(
+  `cb-form-validation/ts/app/template/hero-form-template1.component.html,
+   cb-form-validation/ts/app/template/hero-form-template1.component.ts`,
+  '', 
+  `template/hero-form-template1.component.html,
+   template/hero-form-template1.component.ts`)
+
+.l-main-section
+a#template2
+:marked
+  ## Template-Driven Forms with validation messages in code
+
+  While the layout is straightforward, 
+  there are obvious shortcomings with the way we handle validation messages:
+
+  * It takes a lot of HTML to represent all possible error conditions. 
+  This gets out of hand when there are many controls and many validation rules.
+  
+  * We're not fond of so much JavaScript logic in HTML.
+
+  * The messages are static strings, hard-coded into the template. 
+  We often require dynamic messages that we should shape in code.
+
+  We can move the logic and the messages into the component with a few changes to 
+  the template and component.
+  
+  Here's the hero name again, excerpted from the revised template ("Template 2"), next to the original version:
++makeTabs(
+  `cb-form-validation/ts/app/template/hero-form-template2.component.html, 
+   cb-form-validation/ts/app/template/hero-form-template1.component.html`,
+  'name-with-error-msg, name-with-error-msg',
+  `hero-form-template2.component.html (name #2),
+   hero-form-template1.component.html (name #1)`)
+
+:marked
+  The `<input>` element HTML is almost the same. There are noteworthy differences:
+  - The hard-code error message `<divs>` are gone.
+
+  - There's a new attribute, `forbiddenName`, that is actually a custom validation directive.
+  It invalidates the control if the user enters "bob" anywhere in the name ([try it](#live-example)).
+  We discuss [custom validation directives](#custom-validation) later in this cookbook.
+
+  - The `#name` template variable is gone because we no longer refer to the Angular control for this element.
+
+  -  Binding to the new `formErrors.name` property is sufficent to display all name validation error messages.
+
+  #### Component class
+  The original component code stays the same.
+  We _added_ new code to acquire the Angular form control and compose error messages.
+
+  The first step is to acquire the form control that Angular created from the template by querying for it.
+
+  Look back at the top of the component template where we set the 
+  `#heroForm` template variable in the `<form>` element:
++makeExample('cb-form-validation/ts/app/template/hero-form-template1.component.html','form-tag','template/hero-form-template1.component.html (form tag)')(format='.')
+
+:marked
+  The `heroForm` variable is a reference to the control model that Angular derived from the template.
+  We tell Angular to inject that model into the component class's `currentForm` property using a `@ViewChild` query:
++makeExample('cb-form-validation/ts/app/template/hero-form-template2.component.ts','view-child','template/hero-form-template2.component.ts (heroForm)')(format='.')
+
+:marked
+  Some observations:
+
+  - Angular `@ViewChild` queries for a template variable when you pass it 
+  the name of that variable as a string (`'heroForm'` in this case).
+
+  - The `heroForm` object changes several times during the life of the component, most notably when we add a new hero.
+  We'll have to re-inspect it periodically.
+
+  - Angular calls the `ngAfterViewChecked` [lifecycle hook method](../guide/lifecycle-hooks.html#afterview) 
+  when anything changes in the view.
+  That's the right time to see if there's a new `heroForm` object.
+  
+  - When there _is_ a new `heroForm` model, we subscribe to its `valueChanged` _Observable_ property.
+  The `onValueChanged` handler looks for validation errors after every user keystroke.  
++makeExample('cb-form-validation/ts/app/template/hero-form-template2.component.ts','handler','template/hero-form-template2.component.ts (handler)')(format='.')
+
+:marked
+  The `onValueChanged` handler interprets user data entry. 
+  The `data` object passed into the handler contains the current element values.
+  The handler ignores them. Instead, it iterates over the fields of the component's `formErrors` object.
+
+  The `formErrors` is a dictionary of the hero fields that have validation rules and their current error messages.
+  Only two hero properties have validation rules, `name` and `power`.
+  The messages are empty strings when the hero data are valid.
+
+  For each field, the handler
+    - clears the prior error message if any
+    - acquires the field's corresponding Angular form control 
+    - if such a control exists _and_ its been changed ("dirty") _and_ its invalid ...
+    - the handler composes a consolidated error message for all of the control's errors.
+
+  We'll need some error messages of course, a set for each validated property, one message per validation rule:
++makeExample('cb-form-validation/ts/app/template/hero-form-template2.component.ts','messages','template/hero-form-template2.component.ts (messages)')(format='.')
+:marked
+  Now every time the user makes a change, the `onValueChanged` handler checks for validation errors and produces messages accordingly.
+  
+  ### Is this an improvement?
+  
+  Clearly the template got substantially smaller while the component code got substantially larger. 
+  It's not easy to see the benefit when there are just three fields and only two of them have validation rules.
+
+  Consider what happens as we increase the number of validated fields and rules.
+  In general, HTML is harder to read and maintain than code. 
+  The initial template was already large and threatening to get rapidly worse as we add more validation message `<divs>`.
+  
+  After moving the validation messaging to the component, 
+  the template grows more slowly and proportionally.
+  Each field has approximately the same number of lines no matter its number of validation rules.
+  The component also grows proportionally, at the rate of one line per validated field
+  and one line per validation message.
+  
+  Both trends are manageable.
+
+  Now that the messages are in code, we have more flexibility. We can compose messages more intelligently. 
+  We can refactor the messages out of the component, perhaps to a service class that retrieves them from the server.
+  In short, there are more opportunities to improve message handling now that text and logic have moved from template to code.
+
+  ### _FormModule_ and template-driven forms
+
+  Angular has two different forms modules &mdash; `FormsModule` and `ReactiveFormsModule` &mdash; 
+  that correspond with the two approaches to form development.
+  Both modules come from the same `@angular/forms` library package.
+
+  We've been reviewing the "Template-driven" approach which requires the `FormsModule`
+  Here's how we imported it in the `HeroFormTemplateModule`.
+
++makeExample('cb-form-validation/ts/app/template/hero-form-template.module.ts','','template/hero-form-template.module.ts')(format='.')
+.l-sub-section
+  :marked
+    We haven't talked about the `SharedModule` or its `SubmittedComponent` which appears at the bottom of every
+    form template in this cookbook.  
+    
+    They're not germane to the validation story. Look at the [live example](#live-example) if you're interested.
+
+.l-main-section
+a#reactive
+:marked
+  ## Reactive Forms
+
+  In the template-driven approach, you markup the template with form elements, validation attributes, 
+  and `ng...` directives from the Angular `FormsModule`.
+  At runtime, Angular interprets the template and derives its _form control model_.
+  
+  **Reactive Forms** takes a different approach. 
+  You create the form control model in code. You write the template with form elements
+  and`form...` directives from the Angular `ReactiveFormsModule`.
+  At runtime, Angular binds the template elements to your control model based on your instructions.
+
+  This approach requires a bit more effort. *You have to write the control model and manage it*.
+
+  In return, you can
+  * add, change, and remove validation functions on the fly
+  * manipulate the control model dynamically from within the component
+  * [test](#testing) validation and control logic with isolated unit tests.
+
+  The third cookbook sample re-writes the hero form in _reactive forms_ style.
+
+  ### Switch to the _ReactiveFormsModule_
+  The reactive forms classes and directives come from the Angular `ReactiveFormsModule`, not the `FormsModule`.
+  The application module for the "Reactive Forms" feature in this sample looks like this:
++makeExample('cb-form-validation/ts/app/reactive/hero-form-reactive.module.ts','','app/reactive/hero-form-reactive.module.ts')(format='.')
+:marked
+  The "Reactive Forms" feature module and component are in the `app/reactive` folder. 
+  Let's focus on the `HeroFormReactiveComponent` there, starting with its template.
+
+  ### Component template
+
+  We begin by changing the `<form>` tag so that it binds the Angular `formGroup` directive in the template
+  to the `heroForm` property in the component class. 
+  The `heroForm` is the control model that the component class builds and maintains.
+
++makeExample('cb-form-validation/ts/app/reactive/hero-form-reactive.component.html','form-tag')(format='.')
+:marked
+  Then we modify the template HTML elements to match the _reactive forms_ style.
+  Here is the "name" portion of the template again, revised for reactive forms and compared with the template-driven version:
++makeTabs(
+  `cb-form-validation/ts/app/reactive/hero-form-reactive.component.html, 
+   cb-form-validation/ts/app/template/hero-form-template2.component.html`,
+  'name-with-error-msg, name-with-error-msg',
+  `hero-form-reactive.component.html (name #3),
+   hero-form-template1.component.html (name #2)`)
+
+:marked
+  Key changes:
+  - the validation attributes are gone (except `required`) because we'll be validating in code.
+
+  - `required` remains, not for validation purposes (we'll cover that in the code), 
+  but rather for css styling and accessibility.
+
+.l-sub-section
+  :marked
+    A future version of reactive forms will add the `required` HTML validation attribute to the DOM element
+    (and perhaps the `aria-required` attribute) when the control has the `required` validator function. 
+
+    Until then, apply the `required` attribute _and_ add the `Validator.required` function
+    to the control model, as we'll do below.
+
+:marked
+  - the `formControlName` replaces the `name` attribute; it serves the same
+  purpose of correlating the input box with the Angular form control.
+
+  - the two-way `[(ngModel)]` binding is gone. 
+  The reactive approach does not use data binding to move data into and out of the form controls.
+  We do that in code.
+
+.l-sub-section
+  :marked
+    The retreat from data binding is a principle of the reactive paradigm rather than a technical limitation.
+:marked
+  ### Component class
+
+  The component class is now responsible for defining and managing the form control model. 
+  
+  Angular no longer derives the control model from the template so we can no longer query for it.
+  We create the Angular form control model explicitly with the help of the `FormBuilder`.
+
+  Here's the section of code devoted to that process, paired with the template-driven code it replaces:
++makeTabs(
+  `cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts,
+   cb-form-validation/ts/app/template/hero-form-template2.component.ts`,
+  'form-builder, view-child',
+  `reactive/hero-form-reactive.component.ts (FormBuilder),
+   template/hero-form-template2.component.ts (ViewChild)`)
+:marked
+  - we inject the `FormBuilder` in a constructor.
+
+  - we call a `buildForm` method in the `ngOnInit` [lifecycle hook method](../guide/lifecycle-hooks.html#hooks-overview)
+  because that's when we'll have the hero data. We'll call it again in the `addHero` method.
+.l-sub-section
+  :marked
+    A real app would retrieve the hero asynchronously from a data service, a task best performed in the `ngOnInit` hook.
+:marked
+  - the `buildForm` method uses the `FormBuilder` (`fb`) to declare the form control model.
+  Then it attaches the same `onValueChanged` handler to the form.
+
+:marked
+  #### _FormBuilder_ declaration
+  The `FormBuilder` declaration object specifies the three controls of the sample's hero form. 
+
+  Each control spec is a control name with an array value. 
+  The first array element is the current value of the corresponding hero field.
+  The (optional) second value is a validator function or an array of validator functions.
+  
+  Most of the validator functions are stock validators provided by Angular as static methods of the `Validators` class.
+  Angular has stock validators that correspond to the standard HTML validation attributes.
+
+  The `forbiddenNames` validator on the `"name"` control is a custom validator, 
+  discussed in a separate [section below](#custom-validation).
+
+.l-sub-section  
+  :marked
+    Learn more about `FormBuilder` in a _forthcoming_ chapter on reactive forms. 
+
+:marked
+  #### Committing hero value changes
+  
+  In two-way data binding, the user's changes flow automatically from the controls back to the data model properties.
+  Reactive forms do not use data binding to update data model properties. 
+  The developer decides _when and how_ to update the data model from control values.
+
+  This sample updates the model twice:
+  1. when the user submits the form
+  1. when the user chooses to add a new hero
+
+  The `onSubmit` method simply replaces the `hero` object with the combined values of the form:
++makeExample('cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts','on-submit')(format='.')
+.l-sub-section
+  :marked
+    This example is "lucky" in that the `heroForm.value` properties _just happen_ to
+    correspond _exactly_ to the hero data object properties.
+:marked
+  The `addHero` method discards pending changes and creates a brand new `hero` model object.
++makeExample('cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts','add-hero')(format='.')
+:marked
+  Then it calls `buildForm` again which replaces the previous `heroForm` control model with a new one.
+  The `<form>` tag's `[formGroup]` binding refreshes the page with the new control model.
+
+  Finally, it calls the `onValueChanged` handler to clear previous error messages and reset them
+  to reflect Angular's validation of the new `hero` object.
+
+  Here's the complete reactive component file, compared to the two template-driven component files.
++makeTabs(
+  `cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts,
+   cb-form-validation/ts/app/template/hero-form-template2.component.ts, 
+   cb-form-validation/ts/app/template/hero-form-template1.component.ts`,
+  '',
+  `reactive/hero-form-reactive.component.ts (#3),
+   template/hero-form-template2.component.ts (#2),
+   template/hero-form-template1.component.ts (#1)`)
+
+.l-sub-section
+  :marked
+    Run the [live example](#live-example) to see how the reactive form behaves
+    and to compare all of the files in this cookbook sample.
+
+.l-main-section
+a#custom-validation
+:marked
+  ## Custom validation
+  This cookbook sample has a custom `forbiddenNamevalidator` function that's applied to both the 
+  template-driven and the reactive form controls. It's in the `app/shared` folder
+  and declared in the `SharedModule`.
+
+  Here's the `forbiddenNamevalidator` function itself:
++makeExample('cb-form-validation/ts/app/shared/forbidden-name.directive.ts','custom-validator', 'shared/forbidden-name.directive.ts (forbiddenNameValidator)')(format='.')
+:marked
+  The function is actually a factory that takes a regular expression to detect a _specific_ forbidden name
+  and returns a validator function.
+
+  In this sample, the forbidden name is "bob"; 
+  the validator rejects any hero name containing "bob".
+  Elsewhere it could reject "alice" or any name that the configuring regular expression matches.
+  
+  The `forbiddenNamevalidator` factory returns the configured validator function.
+  That function takes an Angular control object and returns _either_
+  null if the control value is valid _or_ a validation error object.
+  The validation error object typically has a property whose name is the validation key ('forbiddenName')
+  and whose value is an arbitrary dictionary of values that we could insert into an error message (`{name}`).
+
+.l-sub-section
+  :marked
+    Learn more about validator functions in a _forthcoming_ chapter on custom form validation.
+:marked
+  #### Custom validation directive
+  In the reactive forms component we added a configured `forbiddenNamevalidator`
+  to the bottom of the `'name'` control's validator function list.
++makeExample('cb-form-validation/ts/app/reactive/hero-form-reactive.component.ts','name-validators', 'reactive/hero-form-reactive.component.ts (name validators)')(format='.')
+:marked
+  In the template-driven component template, we add the selector (`forbiddenName`) of a custom _attribute directive_ to the name's input box
+  and configured it to reject "bob".
++makeExample('cb-form-validation/ts/app/template/hero-form-template2.component.html','name-input', 'template/hero-form-template2.component.html (name input)')(format='.')
+:marked
+  The corresponding `ForbiddenValidatorDirective` is a wrapper around the `forbiddenNamevalidator`.
+  
+  Angular forms recognizes the directive's role in the validation process because the directive registers itself
+  with the `NG_VALIDATORS` provider, a provider with an extensible collection of validation directives.
++makeExample('cb-form-validation/ts/app/shared/forbidden-name.directive.ts','directive-providers', 'shared/forbidden-name.directive.ts (providers)')(format='.')
+:marked
+  The rest of the directive is unremarkable and we present it here without further comment.
++makeExample('cb-form-validation/ts/app/shared/forbidden-name.directive.ts','directive', 'shared/forbidden-name.directive.ts (directive)')
+:marked
+.l-sub-section
+  :marked
+    See the [Attribute Directives](../guide/attribute-directives.html) chapter.
+
+.l-main-section
+a#testing
+:marked
+  ## Testing Considerations
+
+  We can write _isolated unit tests_ of validation and control logic in _Reactive Forms_.
+
+  _Isolated unit tests_ probe the component class directly, independent of its
+  interactions with its template, the DOM, other dependencies, or Angular itself.
+
+  Such tests have minimal setup, are quick to write, and easy to maintain.
+  They do not require the `Angular TestBed` or asynchronous testing practices.
+
+  That's not possible with _Template-driven_ forms.
+  The template-driven approach relies on Angular to produce the control model and 
+  to derive validation rules from the HTML validation attributes.
+  You must use the `Angular TestBed` to create component test instances,
+  write asynchronous tests, and interact with the DOM.
+
+  While not difficult, this takes more time, work and skill &mdash; 
+  factors that tend to diminish test code coverage and quality.