Regula: An annotation-based form-validator written in Javascript

by vivin

This may all seem like a bit too much, but trust me. It’s pretty simple! I designed the framework so that it performs all the validation and provides the result, but leaves the handling of the errors to the developer. Currently, the framework supports 13 14 built-in constraints, which are:

  • @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. Right now, it checks for this by looking at the selectedIndex property. If it is zero, it assumes that the box is unselected. The reason I’ve done this is because in most cases select boxes have a “Please select a value” option at the very top. I’m open to suggestions if anyone thinks this is not a good idea.
  • @Max(max=n) – Enforces the constraint that a field (technically speaking, the value of a field) can only hold a number that is less than or equal to n.
  • @Min(min=n) – Enforces the constraint that a field (technically speaking, the value of a field) can only hold a number that is greater than or equal to n.
  • @Range(max=n, min=m) or @Between(max=n, min=m) – Enforces the constraint that a field (technically speaking, the value of a field) can only hold a number that is less than or equal to n and greater than or equal to m.
  • @NotEmpty – Enforces the constraint that a field cannot be empty.
  • @Empty – Enforces the constraint that a field must be empty.
  • @Pattern(pattern=/regexp/) or @Matches(pattern=/regexp/) – Enforces the constraint that a field must match the the regular expression regexp.
  • @Email – Enforces the constraint that the field must contain a valid email.
  • @IsAlpha – Enforces the constraint that the field can only contain letters (A-Z and a-z).
  • @IsNumeric – Enforces the constraint that the field can only contain numbers (0-9).
  • @IsAlphaNumeric – Enforces the constraint that the field can only contain letters and numbers (A-Z, a-z, and 0-9).
  • @CompletelyFilled – Enforces the form-specific constraint that all fields in the form must be filled.
  • @PasswordsMatch(field1=”id_of_first_password_field”, field2=”id_of_second_password_field”) – Enforces the constraint that the values of the password fields specified, must match.

As you can see, some constraints take parameters. In addition to those parameters that have been defined (or have not been defined – for constraints that don’t take any) there are two optional parameters called msg or message, and name label. These attributes let you specify custom error message. Without these attributes, the validation framework will return generic error message. For example, let us say that you wanted to ensure that a person’s age is greater than 21. You could do something like this:

Age: <input type="text" 
                 id="age" 
                 name="age" 
                 class="regula-validation"
                 data-constraints = '@Min(min=21, message="You need to older than 21!"') /> 

If you do this, the error message returned from the validation will say You need to be older than 21! rather than returning a generic message like The field value needs to be greater than 21. Now what about the name label parameter? Well, that lets you customize the message even further. The example I provide may seem a bit contrived, but that’s because I’m using the built-in validators. They make more sense when applied to custom validators (coming up later!):

Age: <input type="text" 
                 id="age" 
                 name="age" 
                 class="regula-validation"
                 data-constraints = '@Min(min=21, name="Your cat" message="{label} needs to be older than {min}!"') /> 

In this example, the error message will say Your cat needs to be older than 21!. Also notice that I didn’t explicitly say “21” either. When you enclose something in curly braces, the validator will try to interpolate or substitute the value using a parameter value that you have provided. Like I said, this makes a bit more sense in custom validators!

Note: It occurred to me while writing this that I should probably change name to label because that better describes what I’m trying to do. I’ll update my code to reflect that.