docs(forms): add example app for formControlDirective (#11508)

modules/@angular/examples/forms/ts/simpleFormControl/e2e_test/simple_form_control_spec.ts

@@ -0,0 +1,53 @@
+/**
+ * @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('simpleFormControl example', () => {
+  afterEach(verifyNoBrowserErrors);
+
+  describe('index view', () => {
+    let input: ElementFinder;
+    let valueP: ElementFinder;
+    let statusP: ElementFinder;
+
+    beforeEach(() => {
+      browser.get('/forms/ts/simpleFormControl/index.html');
+      input = element(by.css('input'));
+      valueP = element(by.css('p:first-of-type'));
+      statusP = element(by.css('p:last-of-type'));
+    });
+
+    it('should populate the form control value in the DOM', () => {
+      expect(input.getAttribute('value')).toEqual('value');
+      expect(valueP.getText()).toEqual('Value: value');
+    });
+
+    it('should update the value as user types', () => {
+      input.click();
+      input.sendKeys('s!');
+
+      expect(valueP.getText()).toEqual('Value: values!');
+    });
+
+    it('should show the correct validity state', () => {
+      expect(statusP.getText()).toEqual('Validation status: VALID');
+
+      input.click();
+      input.clear();
+      input.sendKeys('a');
+      expect(statusP.getText()).toEqual('Validation status: INVALID');
+    });
+
+    it('should set the value programmatically', () => {
+      element(by.css('button')).click();
+      expect(input.getAttribute('value')).toEqual('new value');
+    });
+
+  });
+});

modules/@angular/examples/forms/ts/simpleFormControl/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 {SimpleFormControl} from './simple_form_control_example';
+
+@NgModule({
+  imports: [BrowserModule, ReactiveFormsModule],
+  declarations: [SimpleFormControl],
+  bootstrap: [SimpleFormControl]
+})
+export class AppModule {
+}

modules/@angular/examples/forms/ts/simpleFormControl/simple_form_control_example.ts

@@ -0,0 +1,29 @@
+/**
+ * @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, Validators} from '@angular/forms';
+
+@Component({
+  selector: 'example-app',
+  template: `
+     <input [formControl]="control">
+      
+     <p>Value: {{ control.value }}</p>
+     <p>Validation status: {{ control.status }}</p>
+     
+     <button (click)="setValue()">Set value</button>
+  `,
+})
+export class SimpleFormControl {
+  control: FormControl = new FormControl('value', Validators.minLength(2));
+
+  setValue() { this.control.setValue('new value'); }
+}
+// #enddocregion

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

@@ -24,51 +24,44 @@ export const formControlBinding: any = {
 };
 
 /**
- * Binds an existing {@link FormControl} to a DOM element. It requires importing the {@link
- * ReactiveFormsModule}.
+ * @whatItDoes Syncs a standalone {@link FormControl} instance to a form control element.
  *
- * 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.
+ * 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,
+ * any values written to the DOM element through user input will be reflected in the
+ * {@link FormControl} instance (view -> model).
  *
- *  ```typescript
- * @Component({
- *   selector: 'my-app',
- *   template: `
- *     <div>
- *       <h2>Bind existing control example</h2>
- *       <form>
- *         <p>Element with existing control: <input type="text"
- * [formControl]="loginControl"></p>
- *         <p>Value of existing control: {{loginControl.value}}</p>
- *       </form>
- *     </div>
- *   `,
- * })
- * export class App {
- *   loginControl: FormControl = new FormControl('');
- * }
- *  ```
+ * @howToUse
  *
- * ### ngModel
+ * Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
+ * Simply create a {@link FormControl}, save it to your component class, and pass it into the
+ * {@link FormControlDirective}.
  *
- * We can also set the value of the form programmatically with setValue().
- **
- *  ```typescript
- * @Component({
- *      selector: "login-comp",
-
- *      template: "<input type='text' [formControl]='loginControl'>"
- *      })
- * class LoginComp {
- *  loginControl: FormControl = new FormControl('');
+ * This directive is designed to be used as a standalone control.  Unlike {@link FormControlName},
+ * it does not require that your {@link FormControl} instance be part of any parent
+ * {@link FormGroup}, and it won't be registered to any {@link FormGroupDirective} that
+ * exists above it.
  *
- *  populate() {
- *    this.loginControl.setValue('some login');
- *  }
+ * **Get the value**: the `value` property is always synced and available on the
+ * {@link FormControl} instance. See a full list of available properties in
+ * {@link AbstractControl}.
  *
- * }
- *  ```
+ * **Set the value**: You can pass in an initial value 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
+ *
+ * {@example forms/ts/simpleFormControl/simple_form_control_example.ts region='Component'}
+ *
+ * * **npm package**: `@angular/forms`
+ *
+ * * **NgModule**: `ReactiveFormsModule`
  *
  *  @stable
  */