-
Notifications
You must be signed in to change notification settings - Fork 24
regula.bind
regula.bind inspects the DOM for form or input elements that have the data-constraints attribute. It then checks the data-constraints attribute to see whether any constraints have been defined for this element. If constraints have been defined, bind binds the defined constraints to the element. It is essential that bind be called before any validation is performed. The ideal location for the call to bind would be on page load.
Syntax for regula.bind is:
regula.bind([options]);If you’re providing options, bind expects them in the form of an object literal. The attributes of the object literal are treated as parameters:
| Name | Type | Required | Description |
|---|---|---|---|
element |
element | * yes | The element to which you want to bind the constraint(s). Ignored if elements is provided. |
elements |
Array | * yes | A list of elements to which you want to bind the constraint(s). |
constraints |
Array | yes | An array of object literals that define a constraint (see below for more details). |
*Only one of ‘element’ or ‘elements’ is required.
A constraint within the array of constraints is an object literal with the following properties:
| Name | Type | Required | Description |
|---|---|---|---|
constraintType |
Constraint | yes | The type of the constraint that you want to bind to this element. |
overwriteConstraint |
boolean | no | A flag that tells regula if you want to completely overwrite a constraint that was previously bound to this element (see Overwriting Behavior below, for more information). |
overwriteParameters |
boolean | no | A flag that tells regula if you want to overwrite the parameters of a constraint that was previously bound to this element (see Overwriting Behavior below, for more information). |
params |
Map | no | A map, or associative array of parameters that you want to pass to this constraint. For example {max: 5, min:10, message: "Needs to be between {max} and {min}", groups=[regula.Group.FirstGroup, regula.Group.SecondGroup, "NewGroup"]}. Pay special attention to the groups parameter. If you are specifying groups, you need to pass them as an array. Each element can either be a Group, or a String if you are specifying a new group. |
Overwriting comes into play only when dealing with constraints that have been previously bound to an element. Overwriting behavior depends on the values of overwriteConstraint and overwriteParameter. The overall behavior can be summarized by this truth table:
| overwiteConstraint | overwriteParameter | Behavior |
|---|---|---|
| false | false | Existing parameters are not overwritten. Parameters are combined constructively. If the user specifies a parameter that has been previously defined, the value is ignored and the old value remains in play. |
| false | true | Parameters are combined destructively. This means that if the user specifies a parameter that has been previously defined, the new value overwrite the old (previously defined) value. Overwiting is especially important when it involves groups. See Overwriting Groups for more information. |
| true | X | The constraint is completely written. When overwriteConstraint is true, the value of overwriteParameter is irrelevant. The behavior of regula.bind is now as if you were binding the constraint to element for the very first time. Of course, there are certain considerations to be made if groups are involved. See Overwriting Groups for more information. |
It is possible to overwrite groups in two cases. The first case is when overwriteParameter is true and you’re passing in a groups parameter that overwrites the previous value for the groups parameter. The second case is when overwriteConstraint is true and you’re also passing in a groups parameter. In this case you’re completely overwriting the old constraint and so the groups parameter will be overwritten for sure. In both these cases, assume that the new array of groups being sent in is different from the old one.
The things we have to consider when overwriting groups are very simple. There are two cases. The first case is that we are adding the constraint to a group that it did not belong to before, and the second case is that we are removing the constraint from a group that it belonged to before. Adding groups is trivial, but we have to be careful about removing from groups. It turns out that the groups we need to remove a constraint from can be figured out by a simple formula. Assume that the old set of groups is G o and the new set of groups is G n. Then G r, the groups that we need to remove, is given by the formula:
G r = (G o ∪ G n) – G n
So if the old set of groups was ["First", "Second", "Third"] and the new set of groups is ["Second", "Fourth", "Fifth"], the groups we need to remove are ["First", "Third"].
Note: You cannot remove a constraint from the Default group. All defined constraints belong to this group by default.
None
bind will throw an exception if it encountered any errors during binding. This includes invalid constraint definitions, malformed constraint definitions, and constraints attached to invalid elements.
jQuery(document).ready(function() {
regula.bind();
});Without jQuery, and assuming that there is code that binds the following function to the appropriate event:
function onDOMReadyHandler() {
regula.bind();
}regula.bind({
element: document.getElementById("age"),
constraints: [
{constraintType: regula.Constraint.Min,
params: {value: "18", message: "You must be at least {value} years old"}
},
{constraintType: regula.Constraint.NotEmpty,
params: {message: "{label} cannot be empty", label: "age", groups: [regula.Group.SomeGroup, "NewGroup"]}
}
]
});