CodeAPI

ValidatableMixin

Provides functionality for elements that can be validated.

Certain input elements contain properties that are used in basic form validation, such as required and maxlength. More complex validation logic is achieved using the properties and functions below.

Basic validation of elements against the constraints set in the Editor or programmatically is always peformed, regardless of any custom validation.

However, sometimes more complex validation is needed, including validations that depend on more than one element. This is typically achieved by adding custom validation logic in an event handler that you set using the input element's onCustomValidation() function. Within that handler, you call the reject() function to indicate that the element is invalid. The element's validity is checked when the value of the element changes either by user interaction or programmatically.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Table of Contents

PROPERTIES

?
Store values associated with an object.
validIndicates if an input element's value is valid.
validationMessage

Gets a message indicating why the element is invalid, or an empty string if the message is valid.

validity

Gets a ValidityState object that contains detailed information about the validity states of the element.

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
ValidityStateContains detailed information about the validity states of an element.

valid

Indicates if an input element's value is valid.

Description

The valid property indicates if an element's value satisfies all conditions to pass a validation check. This includes basic validity conditions, such as whether the element has a value if it is required, and those specified in its onCustomValidation() event handler, if you defined one.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

See Also

onCustomValidation( )

Syntax

get valid(): boolean
TYPE
?
The kind of data the property stores.
boolean

Examples

Get whether the element is valid

let isValid = $w("#myElement").valid; // false

validationMessage

Gets a message indicating why the element is invalid, or an empty string if the message is valid.

Description

Set the value of the validationMessage property using the reject() function of the onCustomValidation() event handler.

See Also

validity

Syntax

get validationMessage(): string
TYPE
?
The kind of data the property stores.
string

Examples

Get the validation message

let msg = $w("#myElement").validationMessage; // "value missing"

validity

Gets a ValidityState object that contains detailed information about the validity states of the element.

See Also

validationMessage

Syntax

get validity(): ValidityState

Examples

Log ValidityState info

let validityObj = $w("#myElement").validity;

let customError = validityObj.customError;          // true
let valid = validityObj.valid;                      // false
let valueMissing = validityObj.valueMissing;        // false
let typeMismatch = validityObj.typeMismatch;        // false
let patternMismatch = validityObj.patternMismatch;  // false
let tooLong = validityObj.tooLong;                  // false
let tooShort = validityObj.tooShort;                // false
let rangeUnderflow = validityObj.rangeUnderflow;    // false
let rangeOverflow = validityObj.rangeOverflow;      // false
let fileNotUploaded = validityObj.fileNotUploaded;  // false
let stepMismatch = validityObj.stepMismatch;        // false
let badInput = validityObj.badInput;                // false

onCustomValidation( )

Adds an event handler that runs when the element's validation is checked.

Description

The onCustomValidation() function allows you perform custom validation in addition to any basic validation that was defined in the Editor.

To invalidate the element, call the reject() function that is passed into the validator callback function and pass it a validation message.

The element's validity is checked when the value of the element changes either by user interaction or programmatically.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Syntax

function onCustomValidation(validator: Validator): void
callback Validator(value: string | Array<File> | boolean, reject: Function): void
PARAMETERS
?
The kind of data the property stores.
validator
function(value: string | Array<File> | boolean, reject: Function)

The name of the function or the function expression to run when the element's custom validation is checked.

?
The kind of data the property stores.
value
string | Array<File> | boolean
The value of the element being validated.
reject
Function
A function that invalidates the element with the specified message.

Examples

Set an element to invalid if its value is "evil"

$w("#myElement").onCustomValidation( (value, reject) => {
  if(value === "evil") {
    reject("Evil is invalid");
  }
} );

resetValidityIndication( )

Resets the element's visual validity indication.

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

The resetValidityIndication() function resets the validity indication of an element to show the element as valid. The actual validity state of the element is not affected. If the element was invalid, it remains invalid. The validity indication shows the element as valid until the element's validity is checked when the value of the element changes either by user interaction or programmatically. At that point, the element's validity indication shows the element as invalid if its value is not valid.

Syntax

function resetValidityIndication(): void

updateValidityIndication( )

Updates the element's visual validity indication based on its current validity state.

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

Syntax

function updateValidityIndication(): void

Examples

Update an element's validatity indicator

$w("#myElement").updateValidityIndication();

ValidityState

Contains detailed information about the validity states of an element.

Description

This object is returned by an element's validity property.

See Also

validity

Syntax

type ValidityState = {
  customError: boolean
  valid: boolean
  valueMissing: boolean
  typeMismatch: boolean
  patternMismatch: boolean
  tooLong: boolean
  tooShort: boolean
  rangeUnderflow: boolean
  rangeOverflow: boolean
  fileNotUploaded: boolean
  stepMismatch: boolean
  badInput: boolean
}
MEMBERS
?
The kind of data the property stores.
customError
boolean

true if the element's custom validity message has been set to a non-empty string.

valid
boolean

true if the element meets all constraint validations.

valueMissing
boolean

true if the element's required property is true, but it does not contain a value.

typeMismatch
boolean

true if the element's value does not match its type when the type is email or url.

patternMismatch
boolean

true if the element's value does not match its pattern validation.

tooLong
boolean

true if the length of the element's value exceeds its maxlength property.

tooShort
boolean

true if the length of the element's value is smaller than its minlength.

rangeUnderflow
boolean

true if the element's value is less than the its min property.

rangeOverflow
boolean

true if the element's value is more than the its max property.

fileNotUploaded
boolean

true if the element is an upload button that is required and a file has been selected but not uploaded.

stepMismatch
boolean
badInput
boolean

true if the element's value cannot be converted to a value

Examples

Get ValidityState info

let validityObj = $w("#myElement").validity;

let customError = validityObj.customError;          // true
let valid = validityObj.valid;                      // false
let valueMissing = validityObj.valueMissing;        // false
let typeMismatch = validityObj.typeMismatch;        // false
let patternMismatch = validityObj.patternMismatch;  // false
let tooLong = validityObj.tooLong;                  // false
let tooShort = validityObj.tooShort;                // false
let rangeUnderflow = validityObj.rangeUnderflow;    // false
let rangeOverflow = validityObj.rangeOverflow;      // false
let fileNotUploaded = validityObj.fileNotUploaded;  // false
let stepMismatch = validityObj.stepMismatch;        // false
let badInput = validityObj.badInput;                // false