From a618d6e4ce38ccfeb87bee67401c3f2d3f7759a1 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Fri, 11 Aug 2017 19:07:31 -0700 Subject: [PATCH] docs(forms): add api docs for AbstractControlDirective --- .../directives/abstract_control_directive.ts | 117 ++++++++++++++++-- packages/forms/src/model.ts | 2 +- 2 files changed, 108 insertions(+), 11 deletions(-) diff --git a/packages/forms/src/directives/abstract_control_directive.ts b/packages/forms/src/directives/abstract_control_directive.ts index 1bf7524dae..10e86a0480 100644 --- a/packages/forms/src/directives/abstract_control_directive.ts +++ b/packages/forms/src/directives/abstract_control_directive.ts @@ -18,48 +18,145 @@ import {ValidationErrors} from './validators'; * @stable */ export abstract class AbstractControlDirective { + /** + * The {@link FormControl}, {@link FormGroup}, or {@link FormArray} + * that backs this directive. Most properties fall through to that + * instance. + */ abstract get control(): AbstractControl|null; + /** The value of the control. */ get value(): any { return this.control ? this.control.value : null; } + /** + * A control is `valid` when its `status === VALID`. + * + * In order to have this status, the control must have passed all its + * validation checks. + */ get valid(): boolean|null { return this.control ? this.control.valid : null; } + /** + * A control is `invalid` when its `status === INVALID`. + * + * In order to have this status, the control must have failed + * at least one of its validation checks. + */ get invalid(): boolean|null { return this.control ? this.control.invalid : null; } + /** + * A control is `pending` when its `status === PENDING`. + * + * In order to have this status, the control must be in the + * middle of conducting a validation check. + */ get pending(): boolean|null { return this.control ? this.control.pending : null; } - get errors(): ValidationErrors|null { return this.control ? this.control.errors : null; } - - get pristine(): boolean|null { return this.control ? this.control.pristine : null; } - - get dirty(): boolean|null { return this.control ? this.control.dirty : null; } - - get touched(): boolean|null { return this.control ? this.control.touched : null; } - - get untouched(): boolean|null { return this.control ? this.control.untouched : null; } - + /** + * A control is `disabled` when its `status === DISABLED`. + * + * Disabled controls are exempt from validation checks and + * are not included in the aggregate value of their ancestor + * controls. + */ get disabled(): boolean|null { return this.control ? this.control.disabled : null; } + /** + * A control is `enabled` as long as its `status !== DISABLED`. + * + * In other words, it has a status of `VALID`, `INVALID`, or + * `PENDING`. + */ get enabled(): boolean|null { return this.control ? this.control.enabled : null; } + /** + * Returns any errors generated by failing validation. If there + * are no errors, it will return null. + */ + get errors(): ValidationErrors|null { return this.control ? this.control.errors : null; } + + /** + * A control is `pristine` if the user has not yet changed + * the value in the UI. + * + * Note that programmatic changes to a control's value will + * *not* mark it dirty. + */ + get pristine(): boolean|null { return this.control ? this.control.pristine : null; } + + /** + * A control is `dirty` if the user has changed the value + * in the UI. + * + * Note that programmatic changes to a control's value will + * *not* mark it dirty. + */ + get dirty(): boolean|null { return this.control ? this.control.dirty : null; } + + /** + * A control is marked `touched` once the user has triggered + * a `blur` event on it. + */ + get touched(): boolean|null { return this.control ? this.control.touched : null; } + + /** + * A control is `untouched` if the user has not yet triggered + * a `blur` event on it. + */ + get untouched(): boolean|null { return this.control ? this.control.untouched : null; } + + /** + * Emits an event every time the validation status of the control + * is re-calculated. + */ get statusChanges(): Observable|null { return this.control ? this.control.statusChanges : null; } + /** + * Emits an event every time the value of the control changes, in + * the UI or programmatically. + */ get valueChanges(): Observable|null { return this.control ? this.control.valueChanges : null; } + /** + * Returns an array that represents the path from the top-level form + * to this control. Each index is the string name of the control on + * that level. + */ get path(): string[]|null { return null; } + /** + * Resets the form control. This means by default: + * + * * it is marked as `pristine` + * * it is marked as `untouched` + * * value is set to null + * + * For more information, see {@link AbstractControl}. + */ reset(value: any = undefined): void { if (this.control) this.control.reset(value); } + /** + * Returns true if the control with the given path has the error specified. Otherwise + * returns false. + * + * If no path is given, it checks for the error on the present control. + */ hasError(errorCode: string, path?: string[]): boolean { return this.control ? this.control.hasError(errorCode, path) : false; } + /** + * Returns error data if the control with the given path has the error specified. Otherwise + * returns null or undefined. + * + * If no path is given, it checks for the error on the present control. + */ getError(errorCode: string, path?: string[]): any { return this.control ? this.control.getError(errorCode, path) : null; } diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index 0f215ffbbb..19f067a033 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -468,7 +468,7 @@ export abstract class AbstractControl { get(path: Array|string): AbstractControl|null { return _find(this, path, '.'); } /** - * Returns true if the control with the given path has the error specified. Otherwise + * Returns error data if the control with the given path has the error specified. Otherwise * returns null or undefined. * * If no path is given, it checks for the error on the present control.