From 57cb82052bbe7bad452e8a3f28a63561254540eb Mon Sep 17 00:00:00 2001 From: Kara Date: Mon, 12 Sep 2016 11:24:09 -0700 Subject: [PATCH] docs(forms): add example app for formControlDirective (#11508) --- .../e2e_test/simple_form_control_spec.ts | 53 ++++++++++++++ .../forms/ts/simpleFormControl/module.ts | 20 ++++++ .../simple_form_control_example.ts | 29 ++++++++ .../form_control_directive.ts | 71 +++++++++---------- 4 files changed, 134 insertions(+), 39 deletions(-) create mode 100644 modules/@angular/examples/forms/ts/simpleFormControl/e2e_test/simple_form_control_spec.ts create mode 100644 modules/@angular/examples/forms/ts/simpleFormControl/module.ts create mode 100644 modules/@angular/examples/forms/ts/simpleFormControl/simple_form_control_example.ts diff --git a/modules/@angular/examples/forms/ts/simpleFormControl/e2e_test/simple_form_control_spec.ts b/modules/@angular/examples/forms/ts/simpleFormControl/e2e_test/simple_form_control_spec.ts new file mode 100644 index 0000000000..82165df137 --- /dev/null +++ b/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'); + }); + + }); +}); diff --git a/modules/@angular/examples/forms/ts/simpleFormControl/module.ts b/modules/@angular/examples/forms/ts/simpleFormControl/module.ts new file mode 100644 index 0000000000..a16a1f4369 --- /dev/null +++ b/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 { +} diff --git a/modules/@angular/examples/forms/ts/simpleFormControl/simple_form_control_example.ts b/modules/@angular/examples/forms/ts/simpleFormControl/simple_form_control_example.ts new file mode 100644 index 0000000000..cd799034c7 --- /dev/null +++ b/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: ` + + +

Value: {{ control.value }}

+

Validation status: {{ control.status }}

+ + + `, +}) +export class SimpleFormControl { + control: FormControl = new FormControl('value', Validators.minLength(2)); + + setValue() { this.control.setValue('new value'); } +} +// #enddocregion diff --git a/modules/@angular/forms/src/directives/reactive_directives/form_control_directive.ts b/modules/@angular/forms/src/directives/reactive_directives/form_control_directive.ts index 07acf6db9a..9d7251c311 100644 --- a/modules/@angular/forms/src/directives/reactive_directives/form_control_directive.ts +++ b/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: ` - *
- *

Bind existing control example

- *
- *

Element with existing control:

- *

Value of existing control: {{loginControl.value}}

- *
- *
- * `, - * }) - * 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: "" - * }) - * 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 */