$w.ValidatableMixin

$w.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.

Contents

valid Indicates 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.
onCustomValidation( ) Adds an event handler that runs when the element's validation is checked.
resetValidityIndication( ) Resets the element's visual validity indication.
updateValidityIndication( ) Updates the element's visual validity indication based on it's current validity state.
ValidityState Contains detailed information about the validity states of an element.
valid

valid

Indicates if an input element's value is valid.

Syntax

get valid(): boolean

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.

Type

Boolean

Examples

Get whether the element is valid

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

See Also

onCustomValidation( )

validationMessage

validationMessage

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

Syntax

get validationMessage(): string

Description

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

Type

String

Examples

Get the validation message

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

See Also

validity

validity

validity

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

Syntax

get validity(): ValidityState

Type

ValidityState

Examples

Log ValidityState info

bGV0IHZhbGlkaXR5T2JqID0gJHcoIiNteUVsZW1lbnQiKS52YWxpZGl0eTsKCmxldCBjdXN0b21FcnJvciA9IHZhbGlkaXR5T2JqLmN1c3RvbUVycm9yOyAgICAgICAgICAvLyB0cnVlCmxldCB2YWxpZCA9IHZhbGlkaXR5T2JqLnZhbGlkOyAgICAgICAgICAgICAgICAgICAgICAvLyBmYWxzZQpsZXQgdmFsdWVNaXNzaW5nID0gdmFsaWRpdHlPYmoudmFsdWVNaXNzaW5nOyAgICAgICAgLy8gZmFsc2UKbGV0IHR5cGVNaXNtYXRjaCA9IHZhbGlkaXR5T2JqLnR5cGVNaXNtYXRjaDsgICAgICAgIC8vIGZhbHNlCmxldCBwYXR0ZXJuTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5wYXR0ZXJuTWlzbWF0Y2g7ICAvLyBmYWxzZQpsZXQgdG9vTG9uZyA9IHZhbGlkaXR5T2JqLnRvb0xvbmc7ICAgICAgICAgICAgICAgICAgLy8gZmFsc2UKbGV0IHRvb1Nob3J0ID0gdmFsaWRpdHlPYmoudG9vU2hvcnQ7ICAgICAgICAgICAgICAgIC8vIGZhbHNlCmxldCByYW5nZVVuZGVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlVW5kZXJmbG93OyAgICAvLyBmYWxzZQpsZXQgcmFuZ2VPdmVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlT3ZlcmZsb3c7ICAgICAgLy8gZmFsc2UKbGV0IGZpbGVOb3RVcGxvYWRlZCA9IHZhbGlkaXR5T2JqLmZpbGVOb3RVcGxvYWRlZDsgIC8vIGZhbHNlCmxldCBzdGVwTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5zdGVwTWlzbWF0Y2g7ICAgICAgICAvLyBmYWxzZQpsZXQgYmFkSW5wdXQgPSB2YWxpZGl0eU9iai5iYWRJbnB1dDsgICAgICAgICAgICAgICAgLy8gZmFsc2UK
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

See Also

validationMessage

onCustomValidation( )

onCustomValidation( )

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

function onCustomValidation(validator: Validator): void
callback Validator(value: string | File[] | boolean, reject: Function): void

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.

Parameters

validator function(value, reject) The name of the function or the function expression to run when the element's custom validation is checked.
value String |
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"

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

resetValidityIndication( )

Resets the element's visual validity indication.

function resetValidityIndication(): void

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 will remain invalid. The validity indication will show 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 will show the element as invalid if its value is not valid.

updateValidityIndication( )

updateValidityIndication( )

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

function updateValidityIndication(): void

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.

Examples

Update an element's validatity indicator

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

ValidityState

Contains detailed information about the validity states of an element.

Description

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

Type

Object

Properties

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

bGV0IHZhbGlkaXR5T2JqID0gJHcoIiNteUVsZW1lbnQiKS52YWxpZGl0eTsKCmxldCBjdXN0b21FcnJvciA9IHZhbGlkaXR5T2JqLmN1c3RvbUVycm9yOyAgICAgICAgICAvLyB0cnVlCmxldCB2YWxpZCA9IHZhbGlkaXR5T2JqLnZhbGlkOyAgICAgICAgICAgICAgICAgICAgICAvLyBmYWxzZQpsZXQgdmFsdWVNaXNzaW5nID0gdmFsaWRpdHlPYmoudmFsdWVNaXNzaW5nOyAgICAgICAgLy8gZmFsc2UKbGV0IHR5cGVNaXNtYXRjaCA9IHZhbGlkaXR5T2JqLnR5cGVNaXNtYXRjaDsgICAgICAgIC8vIGZhbHNlCmxldCBwYXR0ZXJuTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5wYXR0ZXJuTWlzbWF0Y2g7ICAvLyBmYWxzZQpsZXQgdG9vTG9uZyA9IHZhbGlkaXR5T2JqLnRvb0xvbmc7ICAgICAgICAgICAgICAgICAgLy8gZmFsc2UKbGV0IHRvb1Nob3J0ID0gdmFsaWRpdHlPYmoudG9vU2hvcnQ7ICAgICAgICAgICAgICAgIC8vIGZhbHNlCmxldCByYW5nZVVuZGVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlVW5kZXJmbG93OyAgICAvLyBmYWxzZQpsZXQgcmFuZ2VPdmVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlT3ZlcmZsb3c7ICAgICAgLy8gZmFsc2UKbGV0IGZpbGVOb3RVcGxvYWRlZCA9IHZhbGlkaXR5T2JqLmZpbGVOb3RVcGxvYWRlZDsgIC8vIGZhbHNlCmxldCBzdGVwTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5zdGVwTWlzbWF0Y2g7ICAgICAgICAvLyBmYWxzZQpsZXQgYmFkSW5wdXQgPSB2YWxpZGl0eU9iai5iYWRJbnB1dDsgICAgICAgICAgICAgICAgLy8gZmFsc2UK
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

See Also

validity