regula.validate

Overview

regula.validate performs the actual validation. When regula.bind runs, it builds a list of validation groups, elements, and all constraints bound to an element. With regula.validate it is possible to validate any combination of groups, elements, and constraints (assuming that an element has been bound to a constraint, and that constraint is in a specific group).

Syntax

Syntax for regula.validate is:

regula.validate([options]);

Parameters

validate expects parameters in the form of an object literal. The attributes of the object literal are treated as parameters.

Name	Type	Required	Description
groups	Array	no	An array of Group values.
elementId	String	no	ID of the element against which you want to run validation. Ignored if the elements parameter is provided.
elements	Array	no	An array of DOM elements against which you want to run validation.
constraintType	Constraint	no	The constraint against which you want to validate the specified element. The constraint should have been bound to the element in markup.
independent	boolean	no	A flag that specifies the behavior of validation. Defaults to true. This flag comes into play when an array of groups is provided. Validation runs through the groups provided in order. If independent is false, validation will stop once it encounters a constraint violation in any group and will not proceed to the next validation group. The opposite takes place if independent is true (i.e., validation proceeds for all the groups provided regardless of constraint violations)

Validation Behavior

The following table describes the different kinds of validation behavior based on the combination of parameters sent (excluding independent):

groups	elementId/elements	constraintType	behavior
not provided	not provided	not provided	All bound constraints are validated. Note: A constraint is validated only once. That is, if a constraint belongs to multiple groups, it will only be validated the first time it is encountered and not for every group that it is in. Since every constraint automatically belongs to the Default group regardless of what other groups it may belong to, a call to validate without any parameters will result in all constraints in the Default group being validated, and other groups will not be considered.
not provided	not provided	provided	Validates any element that is bound to the constraint specified by constraintType. Groups don’t end up being considered in this case either. Since every element belongs to the Default group, this combination of parameters results in any constraint of constraintType in the Default group being validated.
not provided	provided	not provided	Validates all constraints bound to this particular element. Groups are not considered in this combination of constraints either, for reasons highlighted above.
not provided	provided	provided	Validates the constraint specified by constraintType to the element identified by elementId.
provided	not provided	not provided	For each group in the array of groups specified, validates all elements and their constraints in the specified group-order. If an element-constraint combination exists in more than one group, it is only validated the first time it is encountered.
provided	not provided	provided	For each group in the array of groups specified, validates elements that are bound to the constraint specified in the specified group-order. If an element-constraint combination exists in more than one group, it is only validated the first time it is encountered.
provided	provided	not provided	For each group in the array of groups specified validates the specified element.
provided	provided	provided	For each group in the arrays of group specified, validates the specified element-constraint combination.

Note: validate will throw an error if it is trying to validate an invalid combination of group, element id or constraint. For example, if the supplied parameters result in a situation where an element is not bound to a supplied constraint, or a situation where an element and constraint is not part of a supplied group, validate will throw an error. This is done to prevent false positives which could be misconstrued as a successful validation.

Return Values

validate returns an array of ConstraintViolation object-literals. Each ConstraintViolation object has the following properties:

Name	Type	Description
group	String	The validation group that this constraint was a part of when it failed validation.
constraintName	String	The name of the constraint that failed.
custom	boolean	A flag that denotes whether the constraint that failed was a custom constraint or not.
constraintParameters	Map	A map where the key is the parameter name. The value of each key is the value assigned to the parameter name in markup or programmatic binding.
failingElements	Array	Array of elements that failed the constraint. This array will only contain one element if the constraint that failed was not a form-specific constraint. Otherwise, the array can contain more than one element.
message	String	The error message from the constraint. This is what you probably want to display to the user.
composingConstraintViolations	Array	An array of ConstraintViolation object-literals. This is returned only if the constraint that failed is a compound constraint, and it had reportAsSingleViolation set to false.

Exceptions

validate will throw an exception if you specify a combination that it cannot find. For example, if you specify an array groups and an element, validate will throw an exception if the specified element cannot be found in any of the groups.

Examples

Validating everything

var constraintViolations = regula.validate();
var messages = "";

for(var index in constraintViolations) {
      var constraintViolation = constraintViolation[index];
      messages += constraintViolation.message + "\n";
}

if(messages != "") {
   alert(messages);
}

Validating a single element

var constraintViolations = regula.validate({elementId: "someElementId");
var messages = "";

for(var index in constraintViolations) {
      var constraintViolation = constraintViolations[index];
      messages += constraintViolation.message + "\n";
}

if(messages != "") {
   alert(messages);
}

Validating a single element against a single constraint

var constraintViolations = regula.validate({elementId: "someElementId", constraintType: regula.ConstraintType.NotEmpty});
var message = constraintViolations[0].message;

if(message != "") {
   alert(messages);
}

Validating a series of validation groups

var constraintViolations = regula.validate({groups: [regula.Group.FirstGroup, regula.Group.SecondGroup]});
var messages = "";

for(var index in constraintViolations) {
      var constraintViolation = constraintViolations[index];
      messages += constraintViolation.message + "\n";
}

if(messages != "") {
   alert(messages);
}

Note: It is also possible to validate against a custom constraint. Whenever you add a custom constraint, regula.Constraint is updated to contain your custom constraint. Therefore, if you had a custom constraint called MyCustomConstraint, you can do regula.Constraint.MyCustomConstraint.

Next: regula.Constraint
Previous: regula.override