Working with the validateOn property

Actually From Sentinel describes only the validateOn setter. So you can't read it afterwards and you shouldn't reassign this property later.

The form's validateOn property may only get an array as a value. This array should contain any amount of string's and optionally one object. Every other object except the very first one will be ignored.

IMPORTANT because checkboxes and radio buttons are absolutely different kind of fields they can only be validated on the form submission.

string

Each string represents one event that will dispatch validation event. Possible values are:

1. submit
   Adds a submit event listener to the form. Happens on a form submission.

   Notice, that it also prevents form submission, so you should manually submit your form afterwards (probobly if the form has no validation errors).

2. blur
   Adds a blur event to every form's field. Happens when the field losses the focus.
3. change
   Adds a change event to every form's field. Happens when the field losses the focus and if the value of field have been changed.
4. keyup
   Adds a keyup event to every form's field. Happens when the key is pressed on the field.

   Notice, this event is not complete yet.

Examples:

form.validateOn = ["submit", "change"];
// validation will take place on a form submission and on a field's value change after the focus loss.

object

Keys of the object must represent events that happen with definit fields. Available events are:

1. change
2. blur
3. keyup

Values of those keys must be either type of array or object.

array

If type of value is array then this array must contain strings that are names of fields that listed in validationRules property. For example if your validationRules property looks like this:

form.validationRules = {
    name: {
        presence: true
    }
}

then validateOn property may look like this:

form.validateOn = [{
    blur: ["name"]
}];
// each constraint of field with `name="name"` will be validated when this fields losses the focus.

Notice in that in the example above even only name is listed in array.

object

If type of value is object then this object must contain keys that are names of fields that listed in validationRules property and values that are array's of certain constraints for definit field. For example if your validationRules property looks like this:

form.validationRules = {
    name: {
        presence: true
    }
}

then validateOn property may look like this:

form.validateOn = [{
    blur: {
        name: ["presence"]
    }
}];
// field with `name="name"` will be validated for `presence` when it losses the focus

Notice in that in the example above even only one constraint is listed in array.

Examples with explanations

form.validateOn = [];
// Validation won't ever happen

form.validateOn = ["submit"];
// Validation will happen on the form submission

form.validateOn = ["keyup", {
    blur: ["field-one", "field-two"]
}];
// fields with `name`'s `field-one` and `field-two` will be validated when they loss focus. Every other field **including** them will be validated when it's value has been changed and focus on then have been lost.