From dd8204a655161ad9c37a4e9c696240834a89fafe Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Sun, 11 Sep 2016 12:43:43 -0700 Subject: [PATCH] docs(forms): update example for formGroupDirective --- .../e2e_test/simple_form_group_spec.ts} | 8 +- .../module.ts | 6 +- .../simple_form_group_example.ts} | 14 ++-- .../reactive_directives/form_control_name.ts | 33 +++++--- .../form_group_directive.ts | 75 +++++-------------- 5 files changed, 59 insertions(+), 77 deletions(-) rename modules/@angular/examples/forms/ts/{formControlName/e2e_test/form_control_name_spec.ts => simpleFormGroup/e2e_test/simple_form_group_spec.ts} (77%) rename modules/@angular/examples/forms/ts/{formControlName => simpleFormGroup}/module.ts (76%) rename modules/@angular/examples/forms/ts/{formControlName/form_control_name_example.ts => simpleFormGroup/simple_form_group_example.ts} (74%) diff --git a/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts b/modules/@angular/examples/forms/ts/simpleFormGroup/e2e_test/simple_form_group_spec.ts similarity index 77% rename from modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts rename to modules/@angular/examples/forms/ts/simpleFormGroup/e2e_test/simple_form_group_spec.ts index 97dbe4e877..b9a93beb4c 100644 --- a/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts +++ b/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'); + }); + }); }); diff --git a/modules/@angular/examples/forms/ts/formControlName/module.ts b/modules/@angular/examples/forms/ts/simpleFormGroup/module.ts similarity index 76% rename from modules/@angular/examples/forms/ts/formControlName/module.ts rename to modules/@angular/examples/forms/ts/simpleFormGroup/module.ts index 4f1924e677..cbafcdd503 100644 --- a/modules/@angular/examples/forms/ts/formControlName/module.ts +++ b/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], - bootstrap: [FormControlNameComp] + declarations: [SimpleFormGroup], + bootstrap: [SimpleFormGroup] }) export class AppModule { } diff --git a/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts b/modules/@angular/examples/forms/ts/simpleFormGroup/simple_form_group_example.ts similarity index 74% rename from modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts rename to modules/@angular/examples/forms/ts/simpleFormGroup/simple_form_group_example.ts index 9ed77c7a6e..cf6be98c56 100644 --- a/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts +++ b/modules/@angular/examples/forms/ts/simpleFormGroup/simple_form_group_example.ts @@ -21,18 +21,22 @@ import {FormControl, FormGroup, Validators} from '@angular/forms'; - - ` + + `, }) -export class FormControlNameComp { - form = new FormGroup( - {first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew')}); +export class SimpleFormGroup { + 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'} } + + setValue() { this.form.setValue({first: 'Carson', last: 'Drew'}); } } 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 5ab82c88a1..6e22c45ecc 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,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 - * control registered with that name in the {@link FormGroup} passed to the parent - * {@link FormGroupDirective}. + * It accepts the string name of the {@link FormControl} instance you want to + * link, and will look for a {@link FormControl} registered with that name in the + * closest {@link FormGroup} or {@link FormArray} above it. * - * 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}. + * **Access the control**: You can access the {@link FormControl} associated with + * this directive by using the {@link AbstractControl.get} method. + * Ex: `this.form.get('first');` * - * If you want to listen to changes in the value of the form, you can subscribe to the - * {@link AbstractControl.valueChanges} event. + * **Get value**: the `value` property is always synced and available on the {@link FormControl}. + * 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` * diff --git a/modules/@angular/forms/src/directives/reactive_directives/form_group_directive.ts b/modules/@angular/forms/src/directives/reactive_directives/form_group_directive.ts index c75b16662f..baa102c012 100644 --- a/modules/@angular/forms/src/directives/reactive_directives/form_group_directive.ts +++ b/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 - * ReactiveFormsModule}. + * @whatItDoes Binds an existing {@link FormGroup} to a DOM element. * - * In this example, we bind the form group to the form element, and we bind the login and - * password controls to the login and password elements. + * @howToUse * - * ```typescript - * @Component({ - * selector: 'my-app', - * template: ` - *
- *

Binding an existing form group

- *
- *

Login:

- *

Password:

- *
- *

Value:

- * 
{{ loginForm.value | json}}
- *
- * ` - * }) - * export class App { - * loginForm: FormGroup; + * This directive accepts an existing {@link FormGroup} instance. It will then use this + * {@link FormGroup} instance to match any child {@link FormControl}, {@link FormGroup}, + * and {@link FormArray} instances to child {@link FormControlName}, {@link FormGroupName}, + * and {@link FormArrayName} directives. * - * constructor() { - * this.loginForm = new FormGroup({ - * login: new FormControl(""), - * password: new FormControl("") - * }); - * } + * **Set value**: You can set the form's initial value when instantiating the + * {@link FormGroup}, or you can set it programmatically later using the {@link FormGroup}'s + * {@link AbstractControl.setValue} or {@link AbstractControl.patchValue} methods. * - * } - * ``` + * **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 - * @Component({ - * selector: "login-comp", - * template: ` - *
- * Login - * Password - * - *
` - * }) - * class LoginComp { - * loginForm: FormGroup; + * In this example, we create form controls for first name and last name. * - * constructor() { - * this.loginForm = new FormGroup({ - * login: new FormControl(''), - * password: new FormControl('') - * }); - * } + * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'} * - * populate() { - * this.loginForm.setValue({ login: 'some login', password: 'some password'}); - * } + * **npm package**: `@angular/forms` * - * onLogin(): void { - * // this.credentials.login === 'some login' - * // this.credentials.password === 'some password' - * } - * } - * ``` + * **NgModule**: {@link ReactiveFormsModule} * * @stable */