docs(forms): update example for formGroupName (#11510)

modules/@angular/examples/forms/ts/nestedFormGroup/e2e_test/nested_form_group_spec.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+
+describe('nestedFormGroup example', () => {
+  afterEach(verifyNoBrowserErrors);
+  let firstInput: ElementFinder;
+  let lastInput: ElementFinder;
+  let button: ElementFinder;
+
+  beforeEach(() => {
+    browser.get('/forms/ts/nestedFormGroup/index.html');
+    firstInput = element(by.css('[formControlName="first"]'));
+    lastInput = element(by.css('[formControlName="last"]'));
+    button = element(by.css('button:not([type="submit"])'));
+  });
+
+  it('should populate the UI with initial values', () => {
+    expect(firstInput.getAttribute('value')).toEqual('Nancy');
+    expect(lastInput.getAttribute('value')).toEqual('Drew');
+  });
+
+  it('should show the error when name is invalid', () => {
+    firstInput.click();
+    firstInput.clear();
+    firstInput.sendKeys('a');
+
+    expect(element(by.css('p')).getText()).toEqual('Name is invalid.');
+  });
+
+  it('should set the value programmatically', () => {
+    button.click();
+    expect(firstInput.getAttribute('value')).toEqual('Bess');
+    expect(lastInput.getAttribute('value')).toEqual('Marvin');
+  });
+
+});

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

@@ -0,0 +1,20 @@
+/**
+  * @license
+  * Copyright Google Inc. All Rights Reserved.
+  *
+  * Use of this source code is governed by an MIT-style license that can be
+  * found in the LICENSE file at https://angular.io/license
+  */
+
+import {NgModule} from '@angular/core';
+import {ReactiveFormsModule} from '@angular/forms';
+import {BrowserModule} from '@angular/platform-browser';
+import {NestedFormGroupComp} from './nested_form_group_example';
+
+@NgModule({
+  imports: [BrowserModule, ReactiveFormsModule],
+  declarations: [NestedFormGroupComp],
+  bootstrap: [NestedFormGroupComp]
+})
+export class AppModule {
+}

modules/@angular/examples/forms/ts/nestedFormGroup/nested_form_group_example.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// #docregion Component
+import {Component} from '@angular/core';
+import {FormControl, FormGroup, Validators} from '@angular/forms';
+
+@Component({
+  selector: 'example-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <p *ngIf="name.invalid">Name is invalid.</p>
+    
+      <div formGroupName="name">
+        <input formControlName="first" placeholder="First name">
+        <input formControlName="last" placeholder="Last name">
+      </div>  
+      <input formControlName="email" placeholder="Email">
+      <button type="submit">Submit</button>
+    </form>
+     
+    <button (click)="setPreset()">Set preset</button>
+`,
+})
+export class NestedFormGroupComp {
+  form = new FormGroup({
+    name: new FormGroup({
+      first: new FormControl('Nancy', Validators.minLength(2)),
+      last: new FormControl('Drew', Validators.required)
+    }),
+    email: new FormControl()
+  });
+
+  get first() { return this.form.get('name.first'); }
+
+  get name() { return this.form.get('name'); }
+
+  onSubmit() {
+    console.log(this.first.value);  // 'Nancy'
+    console.log(this.name.value);   // {first: 'Nancy', last: 'Drew'}
+    console.log(this.form.value);   // {name: {first: 'Nancy', last: 'Drew'}, email: ''}
+    console.log(this.form.status);  // VALID
+  }
+
+  setPreset() { this.name.setValue({first: 'Bess', last: 'Marvin'}); }
+}
+// #enddocregion

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

@@ -24,49 +24,46 @@ export const formGroupNameProvider: any = {
 };
 
 /**
- * Syncs an existing form group to a DOM element.
+ * @whatItDoes Syncs a nested {@link FormGroup} to a DOM element.
  *
- * This directive can only be used as a child of {@link FormGroupDirective}.  It also requires
+ * @howToUse
- * importing the {@link ReactiveFormsModule}.
  *
- * ```typescript
+ * This directive can only be used with a parent {@link FormGroupDirective} (selector:
- * @Component({
+ * `[formGroup]`).
- *   selector: 'my-app',
- *   template: `
- *     <div>
- *       <h2>Angular FormGroup Example</h2>
- *       <form [formGroup]="myForm">
- *         <div formGroupName="name">
- *           <h3>Enter your name:</h3>
- *           <p>First: <input formControlName="first"></p>
- *           <p>Middle: <input formControlName="middle"></p>
- *           <p>Last: <input formControlName="last"></p>
- *         </div>
- *         <h3>Name value:</h3>
- *         <pre>{{ myForm.get('name') | json }}</pre>
- *         <p>Name is {{myForm.get('name')?.valid ? "valid" : "invalid"}}</p>
- *         <h3>What's your favorite food?</h3>
- *         <p><input formControlName="food"></p>
- *         <h3>Form value</h3>
- *         <pre> {{ myForm | json }} </pre>
- *       </form>
- *     </div>
- *   `
- * })
- * export class App {
- *   myForm = new FormGroup({
- *     name: new FormGroup({
- *       first: new FormControl('', Validators.required),
- *       middle: new FormControl(''),
- *       last: new FormControl('', Validators.required)
- *     }),
- *     food: new FormControl()
- *   });
- * }
- * ```
  *
- * This example syncs the form group for the user's name. The value and validation state of
+ * It accepts the string name of the nested {@link FormGroup} you want to link, and
- * this group can be accessed separately from the overall form.
+ * will look for a {@link FormGroup} registered with that name in the parent
+ * {@link FormGroup} instance you passed into {@link FormGroupDirective}.
+ *
+ * Nested form groups can come in handy when you want to validate a sub-group of a
+ * form separately from the rest or when you'd like to group the values of certain
+ * controls into their own nested object.
+ *
+ * **Access the group**: You can access the associated {@link FormGroup} using the
+ * {@link AbstractControl.get} method. Ex: `this.form.get('name')`.
+ *
+ * You can also access individual controls within the group using dot syntax.
+ * Ex: `this.form.get('name.first')`
+ *
+ * **Get the value**: the `value` property is always synced and available on the
+ * {@link FormGroup}. See a full list of available properties in {@link AbstractControl}.
+ *
+ * **Set the value**: You can set an initial value for each child control when instantiating
+ * the {@link FormGroup}, 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 group, 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
+ *
+ * {@example forms/ts/nestedFormGroup/nested_form_group_example.ts region='Component'}
+ *
+ * * **npm package**: `@angular/forms`
+ *
+ * * **NgModule**: `ReactiveFormsModule`
  *
  * @stable
  */