Home

Regula: Javascript Form Validator

Overview

Regula is an annotation-based form-validation framework that aims to make form-validation flexible, easier, and more robust. Regula is also built to be easily extensible. Regula takes its inspiration from Hibernate Bean Validation annotations and uses HTML5 custom-attributes to accomplish validation. Validation in Regula centers around constraints. A constraint defines a set of rules that the value of an input element, or the input elements of a form, must abide by.

Before talking about the constraints themselves, it will be helpful to see them in action. Using Regula is very simple. You can create your form as your normally would, but this time you add constraints on fields that require them:

<input id = "myInput"
       class = "regula-validation"
       type = "text"
       data-constraints = '@NotEmpty @IsNumeric @Between(min=1, max=5)'>

This snippet of code defines a text-box that cannot be empty and that can only contain numeric values between 1 and 5 (both inclusive). Of course, simply adding the constraints is not enough. You actually have to start the validation and inspect the results. That is easily done in the following manner (example uses jQuery):

jQuery(document).ready(function() {
    // must call regula.binnd() first. The best place would be in an
    // onload handler. This function looks for elements with
    // a class name of "regula-validation" and binds the
    // appropriate constraints to the elements

    regula.bind(); 

    jQuery("#myForm").submit(function() {
        // this functions performs the actual validation
        var validationResults = regula.validate();

        for(var index in validationResults) {
             var validationResult = validationResults[index];
             alert(validationResult.message);
        }
    });
});

Don’t worry too much about the validationResults array or the validationResult object. That will be covered later. The above example simply demonstrates the use of the validation framework.

Constraints

As mentioned before, validation in Regula centers around constraints. Constraints take the following form (in general):

@constraint-name(
   param-1=value-1, 
   .., 
   param-n=value-n
   [, label=label-text]
   [, message=message-text]
);

As can be seen, the constraints take named parameters. They also take two optional parameters called label and message. The message parameter specifies the error message to display when the constraint fails. If this parameter is not provided, the default message is used. The value of the message parameter is a regular string, which can contain interpolated values. For example, assume you had message="{label} is lesser than {max}". In this case, the value of label is substituted for {label}, and the value of the parameter max is substituted for {max}. This lets you create customizable error messages.

Default Constraints

Regula comes with fourteen default constraints, out of which two are form-specific constraints. Form-specific constraints only apply to forms (as a whole) while the other constraints apply to input elements.

Input-element-specific Constraints

• @Checked – Enforces the constraint that a checkbox or a radio button must be checked.
• @Selected – Enforces the constraint that a select box must be selected.
• @Max – Enforces the constraint that a field can only hold a number lesser than or equal to a certain value.
• @Min – Enforces the constraint that a field can only hold a number that is greater than or equal to a certain value.
• @Range – Enforces the constraint that a field can only hold a number that is between two values (both inclusive).
• @Between – See Range
• @NotEmpty – Enforces the constraint that a field cannot be empty.
• @Empty – Enforces the constraint that a field must be empty.
• @Pattern – Enforces the constraint that a field must match the specified pattern.
• @Matches – See Matches
• @Email – Enforces the constraint that the field must contain a valid email.
• @IsAlpha – Enforces the constraint that the field can only contain letters.
• @IsNumeric – Enforces the constraint that the field can only contain numbers.
• @IsAlphaNumeric – Enforces the constraint that the field can only contain letters and numbers.

Form-specific constraints

• @CompletelyFilled – Enforces the form-specific constraint that all fields in the form must be filled.
• @PasswordsMatch – Enforces the constraint that the values of the password fields must match.

(to be continued)