From cdda4082de3c7530faa042e411b7ada40694eea3 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Fri, 9 Sep 2016 18:40:18 -0700 Subject: [PATCH] docs(forms): add example app for formControlName --- .../e2e_test/form_control_name_spec.ts | 38 +++++++++ .../form_control_name_example.ts | 39 +++++++++ .../forms/ts/formControlName/module.ts | 20 +++++ .../reactive_directives/form_control_name.ts | 82 ++++++------------- 4 files changed, 122 insertions(+), 57 deletions(-) create mode 100644 modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts create mode 100644 modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts create mode 100644 modules/@angular/examples/forms/ts/formControlName/module.ts diff --git a/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts b/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts new file mode 100644 index 0000000000..97dbe4e877 --- /dev/null +++ b/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts @@ -0,0 +1,38 @@ +/** + * @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('formControlName example', () => { + afterEach(verifyNoBrowserErrors); + + describe('index view', () => { + let firstInput: ElementFinder; + let lastInput: ElementFinder; + + beforeEach(() => { + browser.get('/forms/ts/formControlName/index.html'); + firstInput = element(by.css('[formControlName="first"]')); + lastInput = element(by.css('[formControlName="last"]')); + }); + + it('should populate the form control values in the DOM', () => { + expect(firstInput.getAttribute('value')).toEqual('Nancy'); + expect(lastInput.getAttribute('value')).toEqual('Drew'); + }); + + it('should show the error when the form is invalid', () => { + firstInput.click(); + firstInput.clear(); + firstInput.sendKeys('a'); + + expect(element(by.css('div')).getText()).toEqual('Name is too short.'); + }); + + }); +}); diff --git a/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts b/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts new file mode 100644 index 0000000000..9ed77c7a6e --- /dev/null +++ b/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts @@ -0,0 +1,39 @@ +/** + * @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: ` +
+
Name is too short.
+ + + + + +
+ + ` +}) +export class FormControlNameComp { + form = new FormGroup( + {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'} + } +} + + +// #enddocregion diff --git a/modules/@angular/examples/forms/ts/formControlName/module.ts b/modules/@angular/examples/forms/ts/formControlName/module.ts new file mode 100644 index 0000000000..4f1924e677 --- /dev/null +++ b/modules/@angular/examples/forms/ts/formControlName/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 {FormControlNameComp} from './form_control_name_example'; + +@NgModule({ + imports: [BrowserModule, ReactiveFormsModule], + declarations: [FormControlNameComp], + bootstrap: [FormControlNameComp] +}) +export class AppModule { +} diff --git a/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts b/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts index 184d9c7160..5ab82c88a1 100644 --- a/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts +++ b/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts @@ -28,69 +28,37 @@ export const controlNameBinding: any = { }; /** - * Syncs an existing form control with the specified name to a DOM element. + * @whatItDoes Syncs a form control element to an existing {@link FormControl} instance 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, + * any values written to the DOM element through user input will be reflected in the + * {@link FormControl} instance (view -> model). + * + * @howToUse + * + * This directive must 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 + * control registered with that name in the {@link FormGroup} passed to the parent + * {@link FormGroupDirective}. + * + * You can initialize the value of the form when instantiating the {@link FormGroup}, or you can + * set it programmatically later using {@link AbstractControl.setValue} or + * {@link AbstractControl.patchValue}. + * + * If you want to listen to changes in the value of the form, you can subscribe to the + * {@link AbstractControl.valueChanges} event. * - * This directive can only be used as a child of {@link FormGroupDirective}. It also requires - * importing the {@link ReactiveFormsModule}. - * ### Example * - * In this example, we create the login and password controls. - * We can work with each control separately: check its validity, get its value, listen to its - * changes. + * In this example, we create form controls for first name and last name. * - * ``` - * @Component({ - * selector: "login-comp", - * template: ` - *
- * Login - *
Login is invalid
- * Password - * - *
- * `}) - * class LoginComp { - * loginCtrl = new FormControl(); - * passwordCtrl = new FormControl(); - * myForm = new FormGroup({ - * login: loginCtrl, - * password: passwordCtrl - * }); - * onLogIn(): void { - * // value === {login: 'some login', password: 'some password'} - * } - * } - * ``` + * {@example forms/ts/formControlName/form_control_name_example.ts region='Component'} * - * We can also set the value of the form programmatically using setValue(). + * * **npm package**: `@angular/forms` * - * ``` - * @Component({ - * selector: "login-comp", - * template: ` - *
- * Login - * Password - * - *
- * `}) - * class LoginComp { - * myForm = new FormGroup({ - * login: new FormControl(), - * password: new FormControl() - * }); - * - * populate() { - * this.myForm.setValue({login: 'some login', password: 'some password'}); - * } - * - * onLogIn(): void { - * // this.credentials.login === "some login" - * // this.credentials.password === "some password" - * } - * } - * ``` + * * **NgModule**: {@link ReactiveFormsModule} * * @stable */