From 711ab6d573ebe0d26a426ea9202b705017cc9c0d Mon Sep 17 00:00:00 2001
From: Alex Rickabaugh <alx+alxhub@alxandria.net>
Date: Wed, 23 Sep 2015 13:28:50 -0700
Subject: [PATCH] docs(forms): Add documentation and live examples for NgForm,
 NgFormControl, NgFormModel, and NgModel.

Closes #4343
---
 .../src/core/forms/directives/ng_form.ts      | 78 +++++++++++++------
 .../core/forms/directives/ng_form_control.ts  | 36 ++++++---
 .../core/forms/directives/ng_form_model.ts    | 54 +++++++------
 .../src/core/forms/directives/ng_model.ts     | 12 ++-
 4 files changed, 117 insertions(+), 63 deletions(-)

diff --git a/modules/angular2/src/core/forms/directives/ng_form.ts b/modules/angular2/src/core/forms/directives/ng_form.ts
index b31bf7d49e..4d5a38743a 100644
--- a/modules/angular2/src/core/forms/directives/ng_form.ts
+++ b/modules/angular2/src/core/forms/directives/ng_form.ts
@@ -19,36 +19,64 @@ const formDirectiveBinding =
     CONST_EXPR(new Binding(ControlContainer, {toAlias: forwardRef(() => NgForm)}));
 
 /**
- * Creates and binds a form object to a DOM element.
+ * If `NgForm` is bound in a component, `<form>` elements in that component will be
+ * upgraded to use the Angular form system.
  *
- * # Example
+ * # Typical Use
  *
- *  ```
- * @Component({selector: "signup-comp"})
+ * Include `FORM_DIRECTIVES` in the `directives` section of a {@link View} annotation
+ * to use `NgForm` and its associated controls.
+ *
+ * # Structure
+ *
+ * An Angular form is a collection of {@link Control}s in some hierarchy.
+ * `Control`s can be at the top level or can be organized in {@link ControlGroups}
+ * or {@link ControlArray}s. This hierarchy is reflected in the form's `value`, a
+ * JSON object that mirrors the form structure.
+ *
+ * # Submission
+ *
+ * The `ng-submit` event signals when the user triggers a form submission.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/ltdgYj4P0iY64AR71EpL?p=preview))
+ *
+ *  ```typescript
+ * @Component({
+ *   selector: 'my-app'
+ * })
  * @View({
- *      directives: [FORM_DIRECTIVES],
- *      template: `
- *              <form #f="form" (submit)='onSignUp(f.value)'>
- *                <div ng-control-group='credentials' #credentials="form">
- *                  Login <input type='text' ng-control='login'>
- *                  Password <input type='password' ng-control='password'>
- *                </div>
- *                <div *ng-if="!credentials.valid">Credentials are invalid</div>
+ *   template: `
+ *     <div>
+ *       <p>Submit the form to see the data object Angular builds</p>
+ *       <h2>NgForm demo</h2>
+ *       <form #f="form" (ng-submit)="onSubmit(f.value)">
+ *         <h3>Control group: credentials</h3>
+ *         <div ng-control-group="credentials">
+ *           <p>Login: <input type="text" ng-control="login"></p>
+ *           <p>Password: <input type="password" ng-control="password"></p>
+ *         </div>
+ *         <h3>Control group: person</h3>
+ *         <div ng-control-group="person">
+ *           <p>First name: <input type="text" ng-control="firstName"></p>
+ *           <p>Last name: <input type="text" ng-control="lastName"></p>
+ *         </div>
+ *         <button type="submit">Submit Form</button>
+ *       <p>Form data submitted:</p>
+ *       </form>
+ *       <pre>{{data}}</pre>
+ *     </div>
+ * `,
+ *   directives: [CORE_DIRECTIVES, FORM_DIRECTIVES]
+ * })
+ * export class App {
+ *   constructor() {}
  *
- *                <div ng-control-group='personal'>
- *                  Name <input type='text' ng-control='name'>
- *                </div>
- *                <button type='submit'>Sign Up!</button>
- *              </form>
- *      `})
- * class SignupComp {
- *  onSignUp(value): void {
- *    // value === {
- *    //  personal: {name: 'some name'},
- *    //  credentials: {login: 'some login', password: 'some password'}}
- *  }
+ *   data: string;
+ *
+ *   onSubmit(data) {
+ *     this.data = JSON.stringify(data, null, 2);
+ *   }
  * }
- *
  *  ```
  */
 @Directive({
diff --git a/modules/angular2/src/core/forms/directives/ng_form_control.ts b/modules/angular2/src/core/forms/directives/ng_form_control.ts
index ee67f7b128..7745998ad2 100644
--- a/modules/angular2/src/core/forms/directives/ng_form_control.ts
+++ b/modules/angular2/src/core/forms/directives/ng_form_control.ts
@@ -12,29 +12,43 @@ const formControlBinding =
     CONST_EXPR(new Binding(NgControl, {toAlias: forwardRef(() => NgFormControl)}));
 
 /**
- * Binds an existing control to a DOM element.
+ * Binds an existing {@link Control} to a DOM element.
  *
- * # Example
+ * ### Example ([live demo](http://plnkr.co/edit/jcQlZ2tTh22BZZ2ucNAT?p=preview))
  *
  * In this example, we bind the control to an input element. When the value of the input element
  * changes, the value of the control will reflect that change. Likewise, if the value of the
  * control changes, the input element reflects that change.
  *
- *  ```
- * @Component({selector: "login-comp"})
+ *  ```typescript
+ * @Component({
+ *   selector: 'my-app'
+ * })
  * @View({
- *      directives: [FORM_DIRECTIVES],
- *      template: "<input type='text' [ng-form-control]='loginControl'>"
- *      })
- * class LoginComp {
- *  loginControl: Control = new Control('');;
+ *   template: `
+ *     <div>
+ *       <h2>NgFormControl Example</h2>
+ *       <form>
+ *         <p>Element with existing control: <input type="text"
+ * [ng-form-control]="loginControl"></p>
+ *         <p>Value of existing control: {{loginControl.value}}</p>
+ *       </form>
+ *     </div>
+ *   `,
+ *   directives: [CORE_DIRECTIVES, FORM_DIRECTIVES]
+ * })
+ * export class App {
+ *   loginControl: Control = new Control('');
  * }
- *
  *  ```
  *
+ * # ng-model
+ *
  * We can also use `ng-model` to bind a domain model to the form.
  *
- *  ```
+ * ### Example ([live demo](http://plnkr.co/edit/yHMLuHO7DNgT8XvtjTDH?p=preview))
+ *
+ *  ```typescript
  * @Component({selector: "login-comp"})
  * @View({
  *      directives: [FORM_DIRECTIVES],
diff --git a/modules/angular2/src/core/forms/directives/ng_form_model.ts b/modules/angular2/src/core/forms/directives/ng_form_model.ts
index 78ce068a1c..b00fb5c176 100644
--- a/modules/angular2/src/core/forms/directives/ng_form_model.ts
+++ b/modules/angular2/src/core/forms/directives/ng_form_model.ts
@@ -18,42 +18,48 @@ const formDirectiveBinding =
 /**
  * Binds an existing control group to a DOM element.
  *
- * # Example
+ * ### Example ([live demo](http://plnkr.co/edit/jqrVirudY8anJxTMUjTP?p=preview))
  *
  * In this example, we bind the control group to the form element, and we bind the login and
  * password controls to the login and password elements.
  *
- *  ```
- * @Component({selector: "login-comp"})
+ *  ```typescript
+ * @Component({
+ *   selector: 'my-app'
+ * })
  * @View({
- *      directives: [FORM_DIRECTIVES],
- *      template: `
- *        <form [ng-form-model]='loginForm'>
- *          Login <input type='text' ng-control='login'>
- *          Password <input type='password' ng-control='password'>
- *          <button (click)="onLogin()">Login</button>
- *        </form>`
- *      })
- * class LoginComp {
- *  loginForm: ControlGroup;
+ *   template: `
+ *     <div>
+ *       <h2>NgFormModel Example</h2>
+ *       <form [ng-form-model]="loginForm">
+ *         <p>Login: <input type="text" ng-control="login"></p>
+ *         <p>Password: <input type="password" ng-control="password"></p>
+ *       </form>
+ *       <p>Value:</p>
+ *       <pre>{{value}}</pre>
+ *     </div>
+ *   `,
+ *   directives: [FORM_DIRECTIVES]
+ * })
+ * export class App {
+ *   loginForm: ControlGroup;
  *
- *  constructor() {
- *    this.loginForm = new ControlGroup({
- *      login: new Control(""),
- *      password: new Control("")
- *    });
- *  }
+ *   constructor() {
+ *     this.loginForm = new ControlGroup({
+ *       login: new Control(""),
+ *       password: new Control("")
+ *     });
+ *   }
  *
- *  onLogin(): void {
- *    // this.loginForm.value
- *  }
+ *   get value(): string {
+ *     return JSON.stringify(this.loginForm.value, null, 2);
+ *   }
  * }
- *
  *  ```
  *
  * We can also use ng-model to bind a domain model to the form.
  *
- *  ```
+ *  ```typescript
  * @Component({selector: "login-comp"})
  * @View({
  *      directives: [FORM_DIRECTIVES],
diff --git a/modules/angular2/src/core/forms/directives/ng_model.ts b/modules/angular2/src/core/forms/directives/ng_model.ts
index 3e125798e2..9d985a4ab5 100644
--- a/modules/angular2/src/core/forms/directives/ng_model.ts
+++ b/modules/angular2/src/core/forms/directives/ng_model.ts
@@ -13,10 +13,16 @@ import {setUpControl, isPropertyUpdated} from './shared';
 const formControlBinding = CONST_EXPR(new Binding(NgControl, {toAlias: forwardRef(() => NgModel)}));
 
 /**
- * Binds a domain model to the form.
+ * Binds a domain model to a form control.
  *
- * # Example
- *  ```
+ * # Usage
+ *
+ * `ng-model` binds an existing domain model to a form control. For a
+ * two-way binding, use `[(ng-model)]` to ensure the model updates in
+ * both directions.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/R3UX5qDaUqFO2VYR0UzH?p=preview))
+ *  ```typescript
  * @Component({selector: "search-comp"})
  * @View({
  *      directives: [FORM_DIRECTIVES],