From a433baf99aed805deba62df4e8cf913519eef94d Mon Sep 17 00:00:00 2001 From: Brandon Roberts Date: Thu, 1 Nov 2018 13:51:37 -0500 Subject: [PATCH] docs(forms): update API reference for validator directives (#26926) PR Close #26926 --- packages/forms/src/directives/validators.ts | 239 ++++++++++++++++---- packages/forms/src/model.ts | 7 +- 2 files changed, 204 insertions(+), 42 deletions(-) diff --git a/packages/forms/src/directives/validators.ts b/packages/forms/src/directives/validators.ts index 210ac90432..d3e000dc24 100644 --- a/packages/forms/src/directives/validators.ts +++ b/packages/forms/src/directives/validators.ts @@ -15,7 +15,7 @@ import {NG_VALIDATORS, Validators} from '../validators'; /** * @description - * Defines the map of errors returned from failed validation checks + * Defines the map of errors returned from failed validation checks. * * @publicApi */ @@ -53,7 +53,7 @@ export interface Validator { * @description * Method that performs synchronous validation against the provided control. * - * @param c The control to validate against. + * @param control The control to validate against. * * @returns A map of validation errors if validation fails, * otherwise null. @@ -102,7 +102,7 @@ export interface AsyncValidator extends Validator { * @description * Method that performs async validation against the provided control. * - * @param c The control to validate against. + * @param control The control to validate against. * * @returns A promise or observable that resolves a map of validation errors * if validation fails, otherwise null. @@ -111,12 +111,20 @@ export interface AsyncValidator extends Validator { Promise|Observable; } +/** + * @description + * Provider which adds `RequiredValidator` to the `NG_VALIDATORS` multi-provider list. + */ export const REQUIRED_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => RequiredValidator), multi: true }; +/** + * @description + * Provider which adds `CheckboxRequiredValidator` to the `NG_VALIDATORS` multi-provider list. + */ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => CheckboxRequiredValidator), @@ -125,11 +133,15 @@ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = { /** - * A Directive that adds the `required` validator to any controls marked with the - * `required` attribute, via the `NG_VALIDATORS` binding. + * @description + * A directive that adds the `required` validator to any controls marked with the + * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. + * + * @see [Form Validation](guide/form-validation) * * @usageNotes - * ### Example + * + * ### Adding a required validator using template-driven forms * * ``` * @@ -151,6 +163,10 @@ export class RequiredValidator implements Validator { // TODO(issue/24571): remove '!'. private _onChange !: () => void; + /** + * @description + * Tracks changes to the required attribute bound to this directive. + */ @Input() get required(): boolean|string { return this._required; } @@ -159,21 +175,37 @@ export class RequiredValidator implements Validator { if (this._onChange) this._onChange(); } + /** + * @description + * Method that validates whether the control is empty. + * Returns the validation result if enabled, otherwise null. + */ validate(control: AbstractControl): ValidationErrors|null { return this.required ? Validators.required(control) : null; } + /** + * @description + * Registers a callback function to call when the validator inputs change. + * + * @param fn The callback function + */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } /** * A Directive that adds the `required` validator to checkbox controls marked with the - * `required` attribute, via the `NG_VALIDATORS` binding. + * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. + * + * @see [Form Validation](guide/form-validation) * * @usageNotes - * ### Example + * + * ### Adding a required checkbox validator using template-driven forms * + * The following example shows how to add a checkbox required validator to an input attached to an ngModel binding. + * * ``` * * ``` @@ -189,13 +221,19 @@ export class RequiredValidator implements Validator { host: {'[attr.required]': 'required ? "" : null'} }) export class CheckboxRequiredValidator extends RequiredValidator { + /** + * @description + * Method that validates whether or not the checkbox has been checked. + * Returns the validation result if enabled, otherwise null. + */ validate(control: AbstractControl): ValidationErrors|null { return this.required ? Validators.requiredTrue(control) : null; } } /** - * Provider which adds `EmailValidator` to `NG_VALIDATORS`. + * @description + * Provider which adds `EmailValidator` to the `NG_VALIDATORS` multi-provider list. */ export const EMAIL_VALIDATOR: any = { provide: NG_VALIDATORS, @@ -204,12 +242,17 @@ export const EMAIL_VALIDATOR: any = { }; /** - * A Directive that adds the `email` validator to controls marked with the - * `email` attribute, via the `NG_VALIDATORS` binding. + * A directive that adds the `email` validator to controls marked with the + * `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. + * + * @see [Form Validation](guide/form-validation) * * @usageNotes - * ### Example + * + * ### Adding an email validator * + * The following example shows how to add an email validator to an input attached to an ngModel binding. + * * ``` * * @@ -230,25 +273,48 @@ export class EmailValidator implements Validator { // TODO(issue/24571): remove '!'. private _onChange !: () => void; + /** + * @description + * Tracks changes to the email attribute bound to this directive. + */ @Input() set email(value: boolean|string) { this._enabled = value === '' || value === true || value === 'true'; if (this._onChange) this._onChange(); } + /** + * @description + * Method that validates whether an email address is valid. + * Returns the validation result if enabled, otherwise null. + */ validate(control: AbstractControl): ValidationErrors|null { return this._enabled ? Validators.email(control) : null; } + /** + * @description + * Registers a callback function to call when the validator inputs change. + * + * @param fn The callback function + */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } /** + * @description + * A function that receives a control and synchronously returns a map of + * validation errors if present, otherwise null. + * * @publicApi */ export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; } /** + * @description + * A function that receives a control and returns a Promise or observable + * that emits validation errors if present, otherwise null. + * * @publicApi */ export interface AsyncValidatorFn { @@ -256,12 +322,8 @@ export interface AsyncValidatorFn { } /** - * Provider which adds `MinLengthValidator` to `NG_VALIDATORS`. - * - * @usageNotes - * ### Example: - * - * {@example common/forms/ts/validators/validators.ts region='min'} + * @description + * Provider which adds `MinLengthValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MIN_LENGTH_VALIDATOR: any = { provide: NG_VALIDATORS, @@ -270,11 +332,24 @@ export const MIN_LENGTH_VALIDATOR: any = { }; /** - * A directive which installs the `MinLengthValidator` for any `formControlName`, - * `formControl`, or control with `ngModel` that also has a `minlength` attribute. + * A directive that adds minimum length validation to controls marked with the + * `minlength` attribute. The directive is provided with the `NG_VALIDATORS` mult-provider list. + * + * @see [Form Validation](guide/form-validation) + * + * @usageNotes + * + * ### Adding a minimum length validator + * + * The following example shows how to add a minimum length validator to an input attached to an + * ngModel binding. + * + * ```html + * + * ``` * - * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @ngModule FormsModule * @publicApi */ @Directive({ @@ -289,9 +364,20 @@ export class MinLengthValidator implements Validator, // TODO(issue/24571): remove '!'. private _onChange !: () => void; + /** + * @description + * Tracks changes to the the minimum length bound to this directive. + */ // TODO(issue/24571): remove '!'. @Input() minlength !: string; + /** + * @description + * A lifecycle method called when the directive's inputs change. For internal use + * only. + * + * @param changes A object of key/value pairs for the set of changed inputs. + */ ngOnChanges(changes: SimpleChanges): void { if ('minlength' in changes) { this._createValidator(); @@ -299,10 +385,21 @@ export class MinLengthValidator implements Validator, } } + /** + * @description + * Method that validates whether the value meets a minimum length + * requirement. Returns the validation result if enabled, otherwise null. + */ validate(control: AbstractControl): ValidationErrors|null { return this.minlength == null ? null : this._validator(control); } + /** + * @description + * Registers a callback function to call when the validator inputs change. + * + * @param fn The callback function + */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { @@ -311,12 +408,8 @@ export class MinLengthValidator implements Validator, } /** - * Provider which adds `MaxLengthValidator` to `NG_VALIDATORS`. - * - * @usageNotes - * ### Example: - * - * {@example common/forms/ts/validators/validators.ts region='max'} + * @description + * Provider which adds `MaxLengthValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MAX_LENGTH_VALIDATOR: any = { provide: NG_VALIDATORS, @@ -325,11 +418,24 @@ export const MAX_LENGTH_VALIDATOR: any = { }; /** - * A directive which installs the `MaxLengthValidator` for any `formControlName`, - * `formControl`, or control with `ngModel` that also has a `maxlength` attribute. + * A directive that adds max length validation to controls marked with the + * `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. + * + * @see [Form Validation](guide/form-validation) + * + * @usageNotes + * + * ### Adding a maximum length validator + * + * The following example shows how to add a maximum length validator to an input attached to an + * ngModel binding. + * + * ```html + * + * ``` * - * @ngModule FormsModule * @ngModule ReactiveFormsModule + * @ngModule FormsModule * @publicApi */ @Directive({ @@ -344,9 +450,20 @@ export class MaxLengthValidator implements Validator, // TODO(issue/24571): remove '!'. private _onChange !: () => void; + /** + * @description + * Tracks changes to the the maximum length bound to this directive. + */ // TODO(issue/24571): remove '!'. @Input() maxlength !: string; + /** + * @description + * A lifecycle method called when the directive's inputs change. For internal use + * only. + * + * @param changes A object of key/value pairs for the set of changed inputs. + */ ngOnChanges(changes: SimpleChanges): void { if ('maxlength' in changes) { this._createValidator(); @@ -354,10 +471,21 @@ export class MaxLengthValidator implements Validator, } } + /** + * @description + * Method that validates whether the value exceeds + * the maximum length requirement. + */ validate(control: AbstractControl): ValidationErrors|null { return this.maxlength != null ? this._validator(control) : null; } + /** + * @description + * Registers a callback function to call when the validator inputs change. + * + * @param fn The callback function + */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { @@ -365,7 +493,10 @@ export class MaxLengthValidator implements Validator, } } - +/** + * @description + * Provider which adds `PatternValidator` to the `NG_VALIDATORS` multi-provider list. + */ export const PATTERN_VALIDATOR: any = { provide: NG_VALIDATORS, useExisting: forwardRef(() => PatternValidator), @@ -374,20 +505,26 @@ export const PATTERN_VALIDATOR: any = { /** - * A Directive that adds the `pattern` validator to any controls marked with the - * `pattern` attribute, via the `NG_VALIDATORS` binding. Uses attribute value - * as the regex to validate Control value against. Follows pattern attribute - * semantics; i.e. regex must match entire Control value. + * @description + * A directive that adds regex pattern validation to controls marked with the + * `pattern` attribute. The regex must match the entire control value. + * The directive is provided with the `NG_VALIDATORS` multi-provider list. + * + * @see [Form Validation](guide/form-validation) * * @usageNotes - * ### Example * - * ``` - * - * ``` + * ### Adding a pattern validator * - * @ngModule FormsModule + * The following example shows how to add a pattern validator to an input attached to an + * ngModel binding. + * + * ```html + * + * ``` + * * @ngModule ReactiveFormsModule + * @ngModule FormsModule * @publicApi */ @Directive({ @@ -402,9 +539,20 @@ export class PatternValidator implements Validator, // TODO(issue/24571): remove '!'. private _onChange !: () => void; + /** + * @description + * Tracks changes to the pattern bound to this directive. + */ // TODO(issue/24571): remove '!'. @Input() pattern !: string | RegExp; + /** + * @description + * A lifecycle method called when the directive's inputs change. For internal use + * only. + * + * @param changes A object of key/value pairs for the set of changed inputs. + */ ngOnChanges(changes: SimpleChanges): void { if ('pattern' in changes) { this._createValidator(); @@ -412,8 +560,19 @@ export class PatternValidator implements Validator, } } + /** + * @description + * Method that validates whether the value matches the + * the pattern requirement. + */ validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); } + /** + * @description + * Registers a callback function to call when the validator inputs change. + * + * @param fn The callback function + */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { this._validator = Validators.pattern(this.pattern); } diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index 35aad3a464..88fed8ed55 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -97,14 +97,17 @@ export type FormHooks = 'change' | 'blur' | 'submit'; */ export interface AbstractControlOptions { /** - * List of validators applied to control. + * @description + * The list of validators applied to a control. */ validators?: ValidatorFn|ValidatorFn[]|null; /** - * List of async validators applied to control. + * @description + * The list of async validators applied to control. */ asyncValidators?: AsyncValidatorFn|AsyncValidatorFn[]|null; /** + * @description * The event name for control to update upon. */ updateOn?: 'change'|'blur'|'submit';