From 54794f9b31c09ba1d140314c0c8b3dd9196bfc1f Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Tue, 16 Jul 2019 13:20:27 -0700 Subject: [PATCH] docs: clarify docs for runtime validation change (#31596) PR Close #31596 --- packages/forms/src/model.ts | 16 +++++++++++++ packages/forms/src/validators.ts | 41 +++++++++++++++++++++++++++----- 2 files changed, 51 insertions(+), 6 deletions(-) diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts index fc71de8c72..0b446b2b18 100644 --- a/packages/forms/src/model.ts +++ b/packages/forms/src/model.ts @@ -322,6 +322,10 @@ export abstract class AbstractControl { /** * Sets the synchronous validators that are active on this control. Calling * this overwrites any existing sync validators. + * + * When you add or remove a validator at run time, you must call + * `updateValueAndValidity()` for the new validation to take effect. + * */ setValidators(newValidator: ValidatorFn|ValidatorFn[]|null): void { this.validator = coerceToValidator(newValidator); @@ -330,6 +334,10 @@ export abstract class AbstractControl { /** * Sets the async validators that are active on this control. Calling this * overwrites any existing async validators. + * + * When you add or remove a validator at run time, you must call + * `updateValueAndValidity()` for the new validation to take effect. + * */ setAsyncValidators(newValidator: AsyncValidatorFn|AsyncValidatorFn[]|null): void { this.asyncValidator = coerceToAsyncValidator(newValidator); @@ -337,11 +345,19 @@ export abstract class AbstractControl { /** * Empties out the sync validator list. + * + * When you add or remove a validator at run time, you must call + * `updateValueAndValidity()` for the new validation to take effect. + * */ clearValidators(): void { this.validator = null; } /** * Empties out the async validator list. + * + * When you add or remove a validator at run time, you must call + * `updateValueAndValidity()` for the new validation to take effect. + * */ clearAsyncValidators(): void { this.asyncValidator = null; } diff --git a/packages/forms/src/validators.ts b/packages/forms/src/validators.ts index 2dffd4a43d..68b947ced8 100644 --- a/packages/forms/src/validators.ts +++ b/packages/forms/src/validators.ts @@ -90,6 +90,8 @@ export class Validators { * @returns A validator function that returns an error map with the * `min` property if the validation check fails, otherwise `null`. * + * @see `updateValueAndValidity()` + * */ static min(min: number): ValidatorFn { return (control: AbstractControl): ValidationErrors | null => { @@ -121,6 +123,8 @@ export class Validators { * @returns A validator function that returns an error map with the * `max` property if the validation check fails, otherwise `null`. * + * @see `updateValueAndValidity()` + * */ static max(max: number): ValidatorFn { return (control: AbstractControl): ValidationErrors | null => { @@ -151,6 +155,8 @@ export class Validators { * @returns An error map with the `required` property * if the validation check fails, otherwise `null`. * + * @see `updateValueAndValidity()` + * */ static required(control: AbstractControl): ValidationErrors|null { return isEmptyInputValue(control.value) ? {'required': true} : null; @@ -173,6 +179,9 @@ export class Validators { * * @returns An error map that contains the `required` property * set to `true` if the validation check fails, otherwise `null`. + * + * @see `updateValueAndValidity()` + * */ static requiredTrue(control: AbstractControl): ValidationErrors|null { return control.value === true ? null : {'required': true}; @@ -195,6 +204,8 @@ export class Validators { * @returns An error map with the `email` property * if the validation check fails, otherwise `null`. * + * @see `updateValueAndValidity()` + * */ static email(control: AbstractControl): ValidationErrors|null { if (isEmptyInputValue(control.value)) { @@ -225,6 +236,9 @@ export class Validators { * * @returns A validator function that returns an error map with the * `minlength` if the validation check fails, otherwise `null`. + * + * @see `updateValueAndValidity()` + * */ static minLength(minLength: number): ValidatorFn { return (control: AbstractControl): ValidationErrors | null => { @@ -260,6 +274,9 @@ export class Validators { * * @returns A validator function that returns an error map with the * `maxlength` property if the validation check fails, otherwise `null`. + * + * @see `updateValueAndValidity()` + * */ static maxLength(maxLength: number): ValidatorFn { return (control: AbstractControl): ValidationErrors | null => { @@ -275,11 +292,6 @@ export class Validators { * Validator that requires the control's value to match a regex pattern. This validator is also * provided by default if you use the HTML5 `pattern` attribute. * - * Note that if a Regexp is provided, the Regexp is used as is to test the values. On the other - * hand, if a string is passed, the `^` character is prepended and the `$` character is - * appended to the provided string (if not already present), and the resulting regular - * expression is used to test the values. - * * @usageNotes * * ### Validate that the field only contains letters or spaces @@ -294,8 +306,16 @@ export class Validators { * * ``` * + * @param pattern A regular expression to be used as is to test the values, or a string. + * If a string is passed, the `^` character is prepended and the `$` character is + * appended to the provided string (if not already present), and the resulting regular + * expression is used to test the values. + * * @returns A validator function that returns an error map with the * `pattern` property if the validation check fails, otherwise `null`. + * + * @see `updateValueAndValidity()` + * */ static pattern(pattern: string|RegExp): ValidatorFn { if (!pattern) return Validators.nullValidator; @@ -328,6 +348,9 @@ export class Validators { /** * @description * Validator that performs no operation. + * + * @see `updateValueAndValidity()` + * */ static nullValidator(control: AbstractControl): ValidationErrors|null { return null; } @@ -338,6 +361,9 @@ export class Validators { * * @returns A validator function that returns an error map with the * merged error maps of the validators if the validation check fails, otherwise `null`. + * + * @see `updateValueAndValidity()` + * */ static compose(validators: null): null; static compose(validators: (ValidatorFn|null|undefined)[]): ValidatorFn|null; @@ -358,7 +384,10 @@ export class Validators { * * @returns A validator function that returns an error map with the * merged error objects of the async validators if the validation check fails, otherwise `null`. - */ + * + * @see `updateValueAndValidity()` + * + */ static composeAsync(validators: (AsyncValidatorFn|null)[]): AsyncValidatorFn|null { if (!validators) return null; const presentValidators: AsyncValidatorFn[] = validators.filter(isPresent) as any;