docs(forms): update example for formGroupDirective

modules/@angular/examples/forms/ts/simpleFormGroup/e2e_test/simple_form_group_spec.ts

@@ -16,7 +16,7 @@ describe('formControlName example', () => {
     let lastInput: ElementFinder;
 
     beforeEach(() => {
-      browser.get('/forms/ts/formControlName/index.html');
+      browser.get('/forms/ts/simpleFormGroup/index.html');
       firstInput = element(by.css('[formControlName="first"]'));
       lastInput = element(by.css('[formControlName="last"]'));
     });
@@ -34,5 +34,11 @@ describe('formControlName example', () => {
       expect(element(by.css('div')).getText()).toEqual('Name is too short.');
     });
 
+    it('should set the value programmatically', () => {
+      element(by.css('button:not([type="submit"])')).click();
+      expect(firstInput.getAttribute('value')).toEqual('Carson');
+      expect(lastInput.getAttribute('value')).toEqual('Drew');
+    });
+
   });
 });

modules/@angular/examples/forms/ts/simpleFormGroup/module.ts

@@ -9,12 +9,12 @@
 import {NgModule} from '@angular/core';
 import {ReactiveFormsModule} from '@angular/forms';
 import {BrowserModule} from '@angular/platform-browser';
-import {FormControlNameComp} from './form_control_name_example';
+import {SimpleFormGroup} from './simple_form_group_example';
 
 @NgModule({
   imports: [BrowserModule, ReactiveFormsModule],
-  declarations: [FormControlNameComp],
+  declarations: [SimpleFormGroup],
-  bootstrap: [FormControlNameComp]
+  bootstrap: [SimpleFormGroup]
 })
 export class AppModule {
 }

modules/@angular/examples/forms/ts/simpleFormGroup/simple_form_group_example.ts

@@ -21,18 +21,22 @@ import {FormControl, FormGroup, Validators} from '@angular/forms';
       
       <button type="submit">Submit</button>
    </form>
-  
+   <button (click)="setValue()">Set preset value</button>
-  `
+  `,
 })
-export class FormControlNameComp {
+export class SimpleFormGroup {
-  form = new FormGroup(
+  form = new FormGroup({
-      {first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew')});
+    first: new FormControl('Nancy', Validators.minLength(2)),
+    last: new FormControl('Drew'),
+  });
 
   get first() { return this.form.get('first'); }
 
   onSubmit(): void {
     console.log(this.form.value);  // {first: 'Nancy', last: 'Drew'}
   }
+
+  setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); }
 }
 
 

modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts

@@ -28,7 +28,8 @@ export const controlNameBinding: any = {
 };
 
 /**
- * @whatItDoes  Syncs a form control element to an existing {@link FormControl} instance by name.
+ * @whatItDoes  Syncs a {@link FormControl} in an existing {@link FormGroup} to a form control
+ * element by name.
  *
  * In other words, this directive ensures that any values written to the {@link FormControl}
  * instance programmatically will be written to the DOM element (model -> view). Conversely,
@@ -37,24 +38,34 @@ export const controlNameBinding: any = {
  *
  * @howToUse
  *
- * This directive must be used with a parent {@link FormGroupDirective} (selector: `[formGroup]`).
+ * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
+ * `[formGroup]`).
  *
- * Pass in the string name of the {@link FormControl} instance you want to link. It will look for a
+ * It accepts the string name of the {@link FormControl} instance you want to
- * control registered with that name in the {@link FormGroup} passed to the parent
+ * link, and will look for a {@link FormControl} registered with that name in the
- * {@link FormGroupDirective}.
+ * closest {@link FormGroup} or {@link FormArray} above it.
  *
- *  You can initialize the value of the form when instantiating the {@link FormGroup}, or you can
+ * **Access the control**: You can access the {@link FormControl} associated with
- * set it programmatically later using {@link AbstractControl.setValue} or
+ * this directive by using the {@link AbstractControl.get} method.
- * {@link AbstractControl.patchValue}.
+ * Ex: `this.form.get('first');`
  *
- * If you want to listen to changes in the value of the form, you can subscribe to the
+ * **Get value**: the `value` property is always synced and available on the {@link FormControl}.
- * {@link AbstractControl.valueChanges} event.
+ * See a full list of available properties in {@link AbstractControl}.
+ *
+ *  **Set value**: You can set an initial value for the control when instantiating the
+ *  {@link FormControl}, or you can set it programmatically later using
+ *  {@link AbstractControl.setValue} or {@link AbstractControl.patchValue}.
+ *
+ * **Listen to value**: If you want to listen to changes in the value of the control, you can
+ * subscribe to the {@link AbstractControl.valueChanges} event.  You can also listen to
+ * {@link AbstractControl.statusChanges} to be notified when the validation status is
+ * re-calculated.
  *
  * ### Example
  *
  * In this example, we create form controls for first name and last name.
  *
- * {@example forms/ts/formControlName/form_control_name_example.ts region='Component'}
+ * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'}
  *
  *  * **npm package**: `@angular/forms`
  *

modules/@angular/forms/src/directives/reactive_directives/form_group_directive.ts

@@ -27,72 +27,33 @@ export const formDirectiveProvider: any = {
 };
 
 /**
- * Binds an existing form group to a DOM element.  It requires importing the {@link
+ * @whatItDoes Binds an existing {@link FormGroup} to a DOM element.
- * ReactiveFormsModule}.
  *
- * In this example, we bind the form group to the form element, and we bind the login and
+ * @howToUse
- * password controls to the login and password elements.
  *
- *  ```typescript
+ * This directive accepts an existing {@link FormGroup} instance. It will then use this
- * @Component({
+ * {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup},
- *   selector: 'my-app',
+ * and {@link FormArray} instances to child {@link FormControlName}, {@link FormGroupName},
- *   template: `
+ * and {@link FormArrayName} directives.
- *     <div>
- *       <h2>Binding an existing form group</h2>
- *       <form [formGroup]="loginForm">
- *         <p>Login: <input type="text" formControlName="login"></p>
- *         <p>Password: <input type="password" formControlName="password"></p>
- *       </form>
- *       <p>Value:</p>
- *       <pre>{{ loginForm.value | json}}</pre>
- *     </div>
- *   `
- * })
- * export class App {
- *   loginForm: FormGroup;
  *
- *   constructor() {
+ * **Set value**: You can set the form's initial value when instantiating the
- *     this.loginForm = new FormGroup({
+ * {@link FormGroup}, or you can set it programmatically later using the {@link FormGroup}'s
- *       login: new FormControl(""),
+ * {@link AbstractControl.setValue} or {@link AbstractControl.patchValue} methods.
- *       password: new FormControl("")
- *     });
- *   }
  *
- * }
+ * **Listen to value**: If you want to listen to changes in the value of the form, you can subscribe
- *  ```
+ * to the {@link FormGroup}'s {@link AbstractControl.valueChanges} event.  You can also listen to
+ * its {@link AbstractControl.statusChanges} event to be notified when the validation status is
+ * re-calculated.
  *
- * We can also use setValue() to populate the form programmatically.
+ * ### Example
  *
- *  ```typescript
+ * In this example, we create form controls for first name and last name.
- * @Component({
- *      selector: "login-comp",
- *      template: `
- *        <form [formGroup]='loginForm'>
- *          Login <input type='text' formControlName='login'>
- *          Password <input type='password' formControlName='password'>
- *          <button (click)="onLogin()">Login</button>
- *        </form>`
- *      })
- * class LoginComp {
- *  loginForm: FormGroup;
  *
- *  constructor() {
+ * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'}
- *    this.loginForm = new FormGroup({
- *      login: new FormControl(''),
- *      password: new FormControl('')
- *    });
- *  }
  *
- *  populate() {
+ * **npm package**: `@angular/forms`
- *    this.loginForm.setValue({ login: 'some login', password: 'some password'});
- *  }
  *
- *  onLogin(): void {
+ * **NgModule**: {@link ReactiveFormsModule}
- *    // this.credentials.login === 'some login'
- *    // this.credentials.password === 'some password'
- *  }
- * }
- *  ```
  *
  *  @stable
  */