From 80a74b450a5954bb5e3fbf32449fc475b95804a2 Mon Sep 17 00:00:00 2001 From: Brandon Roberts Date: Wed, 27 Jun 2018 14:33:16 -0500 Subject: [PATCH] docs(forms): update form builder API reference (#24693) PR Close #24693 --- .../ts/formBuilder/form_builder_example.ts | 21 ++++++- packages/forms/src/form_builder.ts | 63 ++++++++++++------- packages/forms/src/model.ts | 15 ++--- 3 files changed, 67 insertions(+), 32 deletions(-) diff --git a/packages/examples/forms/ts/formBuilder/form_builder_example.ts b/packages/examples/forms/ts/formBuilder/form_builder_example.ts index 01a9690977..e6fbd9c3eb 100644 --- a/packages/examples/forms/ts/formBuilder/form_builder_example.ts +++ b/packages/examples/forms/ts/formBuilder/form_builder_example.ts @@ -6,9 +6,10 @@ * found in the LICENSE file at https://angular.io/license */ -// #docregion Component +// #docregion Component, disabled-control import {Component, Inject} from '@angular/core'; -import {FormBuilder, FormGroup, Validators} from '@angular/forms'; +import {FormBuilder, FormControl, FormGroup, Validators} from '@angular/forms'; +// #enddocregion disabled-control @Component({ selector: 'example-app', @@ -40,3 +41,19 @@ export class FormBuilderComp { } } // #enddocregion + +// #docregion disabled-control +@Component({ + selector: 'app-disabled-form-control', + template: ` + + ` +}) +export class DisabledFormControlComponent { + control: FormControl; + + constructor(private fb: FormBuilder) { + this.control = fb.control({value: 'my val', disabled: true}); + } +} +// #enddocregion disabled-control \ No newline at end of file diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts index ccb1fd9563..9b3c4570ec 100644 --- a/packages/forms/src/form_builder.ts +++ b/packages/forms/src/form_builder.ts @@ -13,31 +13,28 @@ import {AbstractControl, FormArray, FormControl, FormGroup} from './model'; /** * @description - * * Creates an `AbstractControl` from a user-specified configuration. * - * This is essentially syntactic sugar that shortens the `new FormGroup()`, - * `new FormControl()`, and `new FormArray()` boilerplate that can build up in larger + * The `FormBuilder` provides syntactic sugar that shortens creating instances of a `FormControl`, + * `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to build complex * forms. * - * To use, inject `FormBuilder` into your component class. You can then call its methods - * directly. - * - * {@example forms/ts/formBuilder/form_builder_example.ts region='Component'} - * - * * **npm package**: `@angular/forms` - * - * * **NgModule**: `ReactiveFormsModule` - * + * @see [Reactive Forms Guide](/guide/reactive-forms) * */ @Injectable() export class FormBuilder { /** - * Construct a new `FormGroup` with the given map of configuration. - * Valid keys for the `extra` parameter map are `validator` and `asyncValidator`. + * @description + * Construct a new `FormGroup` instance. + * + * @param controlsConfig A collection of child controls. The key for each child is the name + * under which it is registered. + * + * @param extra An object of configuration options for the `FormGroup`. + * * `validator`: A synchronous validator function, or an array of validator functions + * * `asyncValidator`: A single async validator or array of async validator functions * - * See the `FormGroup` constructor for more details. */ group(controlsConfig: {[key: string]: any}, extra: {[key: string]: any}|null = null): FormGroup { const controls = this._reduceControls(controlsConfig); @@ -45,12 +42,28 @@ export class FormBuilder { const asyncValidator: AsyncValidatorFn = extra != null ? extra['asyncValidator'] : null; return new FormGroup(controls, validator, asyncValidator); } + /** - * Construct a new `FormControl` with the given `formState`,`validator`, and - * `asyncValidator`. + * @description + * Construct a new `FormControl` instance. * - * `formState` can either be a standalone value for the form control or an object - * that contains both a value and a disabled status. + * @param formState Initializes the control with an initial value, + * or an object that defines the initial value and disabled state. + * + * @param validator A synchronous validator function, or an array of synchronous validator + * functions. + * + * @param asyncValidator A single async validator or array of async validator functions + * + * @usageNotes + * + * ### Initialize a control as disabled + * + * The following example returns a control with an initial value in a disabled state. + * + * + * * */ control( @@ -60,8 +73,16 @@ export class FormBuilder { } /** - * Construct a `FormArray` from the given `controlsConfig` array of - * configuration, with the given optional `validator` and `asyncValidator`. + * @description + * Construct a new `FormArray` instance. + * + * @param controlsConfig An array of child controls. The key for each child control is its index + * in the array. + * + * @param validator A synchronous validator function, or an array of synchronous validator + * functions. + * + * @param asyncValidator A single async validator or array of async validator functions */ array( controlsConfig: any[], validator?: ValidatorFn|ValidatorFn[]|null, diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index af833c8e39..834b48c64a 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -880,9 +880,8 @@ export class FormControl extends AbstractControl { /** * Creates a new `FormControl` instance. * - * @param formState Initializes the control with an initial state value, - * or with an object that defines the initial value, status, and options - * for handling updates and validation. + * @param formState Initializes the control with an initial value, + * or an object that defines the initial value and disabled state. * * @param validatorOrOpts A synchronous validator function, or an array of * such functions, or an `AbstractControlOptions` object that contains validation functions @@ -963,9 +962,8 @@ export class FormControl extends AbstractControl { * Resets the form control, marking it `pristine` and `untouched`, and setting * the value to null. * - * @param formState Initializes the control with an initial state value, - * or with an object that defines the initial value, status, and options - * for handling updates and validation. + * @param formState Resets the control with an initial value, + * or an object that defines the initial value and disabled state. * * @param options Configuration options that determine how the control propagates changes * and emits events after the value changes. @@ -1319,9 +1317,8 @@ export class FormGroup extends AbstractControl { * is a standalone value or a form state object with both a value and a disabled * status. * - * @param value Initializes the control with an initial state value, - * or with an object that defines the initial value, status, - * and options for handling updates and validation. + * @param formState Resets the control with an initial value, + * or an object that defines the initial value and disabled state. * * @param options Configuration options that determine how the control propagates changes * and emits events when the group is reset.