regula

by vivin

vivin /regula

Regula: An annotation-based form-validation framework in Javascript

128 Stars 21 Forks Last release: over 5 years ago (v1.3.4) 258 Commits 11 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Regula Build Status  Coverage Status

Regula: An annotation-based form-validator for client-side validation

Why?

You might be wondering why the world needs another client-side validation-framework. After all, there are already different validation-frameworks like jQuery's Validation Plugin, Validator from jQuery tools, and so many more. Furthermore, browsers are starting to implement HTML5 validation constraints, so what makes Regula so special?

Small, Easy, and Powerful

Regula is small. It's around 220Kb un-compressed, and 64Kb minified. Regula also doesn't depend on any other external libraries, so you don't have any other dependencies.

As far as ease-of-use goes, I would say that Regula is the easiest Javascript client-side validation-framework to use; on par with using HTML5 constraint-validation. Why is that? Well, let's take a look at how you'd mark an element for validation in Regula:


That's it. Now compare that to HTML5:


Not that different, right? Now how about other frameworks? While also useful, binding constraints to elements in other frameworks is somewhat verbose because all constraint-binding is done in Javascript. This has two problems: verbosity (as I mentioned earlier), and lack of context. Part of the appeal of HTML5 constraint validation is that one can immediately tell what restrictions apply to an input field simply by looking at the code. When using other validation-frameworks which rely solely on Javascript for constraint binding, you cannot easily identify the restrictions that apply to a specific element. If the constraints are defined in

 tag (hopefully adjacent to the element), it's a little easier but if the constraints are defined in another file you need to go find that file first.

Since Regula's constraints are directly attached to the element, you can easily tell what restrictions apply to that element. Also, it's remarkably trivial to add more constraints:


The above example attaches the following conditions to the text field:

  • It is a required field.
  • It can only accept numbers.
  • The value must at least be 21.

That's the easy part. What makes Regula so powerful? Well, one of the hardest things to do well in form-validation is validating against a custom constraint. Usually this involves a little bit of complex logic, for example conditional validation of a field based on the value or state of another field, or validation according to some specific rule. Regula makes this very easy to do with custom constraints. There are two main advantages to the way Regula handles custom constraints: reuse and encapsulation. Once you define a custom constraint in Javascript, you can use it on any input element. Second, all your validation logic is conveniently encapsulated in one place. Here's a simple example:

regula.custom({
   name: "MustBe42",
   defaultMessage: "The answer must be equal to 42",
   validator: function() {
      return this.value == 42;
   }
});

And its use:


Here's another example. This one involves parameters to your custom constraint:

regula.custom({
   name: "DivisibleBy",
   defaultMessage: "{label} must be divisible by {divisor}",
   params: ["divisor"],
   validator: function(params) {
      var divisor = params["divisor"];
      return (this.value % divisor) == 0;
   }
});

And usage:


Earlier I mentioned HTML5 constraints. Regula will detect and incorporate HTML5 validation constraints into its validation cycle. This way, you can still use HTML5 validation constraints with Regula. Regula also offers "wrapped" versions of HTML5 constraints (for example

@HTML5Required
for
required
), which means that you are able to take advantage of other features of Regula like custom failure-messages, labels, validation groups, and compound constraints. Here are some examples for HTML5 constraints:

In the above example, you can see that it isn't any different from using regular HTML5 constraints. The advantage you have is that you can use Regula to validate these constraints now. You can also use the "wrapped" versions:


Asynchronous constraints are another feature that is supported by Regula. You can define and use custom, asynchronous constraints alongside regular constraints. Here is an example of a custom, asynchronous constraint:

regula.custom({
    name: "MyAsyncContraint",
    async: true,
    defaultMessage: "The asynchronous constraint failed.",
    validator: function(params, validator, callback) {
        //Using jQuery as an example
        jQuery.ajax({
            url: myUrl,
            dataType: "jsonp",
            success: function(data) {
                //Use the callback to pass the result of validation back to
                //regula.
                callback(data.success)
            }
        });
    }
});

Asynchronous constraints can be used inside compound constraints too. There is no explicit syntax to make a compound-constraint asynchronous. Any compound constraint that contains at least one asynchronous constraint, is implicitly asynchronous.

Note: As of version 1.3.3, the callback syntax isn't limited to asynchronous constraints. While normally you simply look at the return value from

regula.validate()
when dealing with synchronous constraints, you can also use the callback syntax even if all you have are synchronous constraints. The reason this feature was added is that in some cases you cannot know if the set of constraints you are validating are synchronous or asynchronous. Previously, Regula would only call the callback if there was at least one asynchronous constraint.

But that's not all! Regula supports other features in addition to custom constraints:

  • Validation groups (i.e., selective validation of specific elements).
  • Compound constraints (constraints that contain one or more other constraints).
  • Form-specific constraints (i.e., constraints that apply to the form as a whole).
  • A simple, yet powerful API.

That's all well and good. But how exactly do you enforce these constraints prior to submitting your form? That part is easy as well. Here's a simple example (using jQuery):

jQuery(document).ready(function() {
    // Must call regula.bind() first. The best place would be in an
    // onload handler. This function looks for elements with an
    // attribute called "data-constraints" and binds the defined
    // constraints to the elements

regula.bind(); 

jQuery("#myForm").submit(function() {
    // this function performs the actual validation and returns an array
    // of constraint violations
    var validationResults = regula.validate();

    for(var i = 0; i < validationResults.length; i++) {
         var validationResult = validationResults[i];
         alert(validationResult.message);
    }

    return validationResults.length === 0;
});

});

In the above example, we first call

regula.bind()
to bind all our constraints to the elements they have been defined on. Then, we call
regula.validate()
that performs all the validation. This function returns an array of constraint violations, that you can then examine to see which elements failed validation. That's all there is to it!

To validate using asynchronous constraints, you need to use a callback with

regula.validate()
:
regula.validate(function(constraintViolations) {
    ...
});

You can still supply options to

regula.validate
while supplying a callback:
regula.validate(options, function(constraintViolations) {
    ...
});

There is a lot more I haven't gone over, but I hope that these simple examples show you how powerful Regula is, and also how easy it is to use. I hope you give it a chance and try it out; 1.3.3 is the latest version. Suggestions and comments are always welcome! For more information, you can take a look at the wiki.

Documentation

Documentation is available here. It is still a work in progress since I am migrating stuff over from the old wiki into the new GitHub page.

Ok, where can I get it?

You can download the latest version of Regula on the releases page. The latest release is 1.3.3.

I want to contribute!

That's awesome! Take a look at devreadme.txt for information regarding contribution (I only accept changes into specific branches and not directly into master since I want master to reflect production-ready code; see here for more information) and how to set up your development environment. I'm still fleshing it out, but if you have any questions, don't hesitate to ask. Once you're done making your changes, send me a pull-request and we can go from there!

Going forward

I'm not done with Regula yet! Going forward, I'm considering the following features: - Global parameter definitions (specify a parameter to be used by all constraints). - Constraint expressions (combine constraints into logical expressions).

This is by no means an exhaustive list. I honestly believe that Regula is a good alternative to existing client-side validation-frameworks and I will be constantly improving and enhancing Regula. I take the quality of my code seriously and will do my best to release bug-free code. Currently JSCoverage reports 97% coverage (effective coverage is pretty much 100%) established through over 2,300 assertions.

Questions?

Check out the mailing list!

Licensing

Regula is licensed under the BSD License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.