Data.FormValidator

 Get Data.FormValidator at SourceForge.net. Fast, secure and Free Open Source software downloads
Project Page JSAN listing Demo Download

DESCRIPTION

Data.FormValidator's aim is to bring all the benefits of the perl module Data::FormValidator over to javascript, using the same input profiles (they can be dumped into javascript objects using the perl module Data::JavaScript.

Data.FormValidator lets you define profiles which declare the required and optional fields and any constraints they might have.

The results are provided as an object which makes it easy to handle missing and invalid results, return error messages about which constraints failed, or process the resulting valid data.

IMPORTANT NOTE: JavaScript form validation is NOT a replacement for data validation in your backend scripts. This is the primary reason this module was written... so that it would be easy to share the same validation profile for both the frontend (via Data.FormValidator.js) and backend (via Data::FormValidator.pm).

SYNOPSIS 
<FORM onSubmit="return myValidate(this);">
First Name<INPUT TYPE="text" name="firstname">
Last Name<INPUT TYPE="text" name="lastname">
Age<INPUT TYPE="text" name="age">
<INPUT TYPE="submit">
</FORM>
<SCRIPT LANGUAGE="javascript" type="text/javascript" src="lib/Data/FormValidator.js">
<SCRIPT LANGUAGE="javascript"><!--
    function myValidate (frmObj) {
        var myProfile = new Object;
        profile.required = new Array('firstname', 'lastname');
        profile.optional = new Array('age');
        var passed = Data.FormValidator.check_and_report(frmObj, profile, goodColor, badColor);
        return passed;
    }
// --></SCRIPT>
USAGE
PROFILE

With this validator, the meat of it is in what we refer to as the "profile".

The validator "profile" defines all the rules for what is valid in your form. For example, required fields, fields which are required only if some other field is filled out, fields that must only contain numbers, etc.

The profile may be built by hand, if you like, but I find it far easier to generate the profile from perl (where this validator has its roots).

A very simple profile in javascript might look something like this: 

var myProfile = new Object;
profile.required = new Array('firstname', 'lastname', 'date_of_birth');
The above would simply require that those three fields be filled in.

Here's a bit more complex (though still simple) profile in perl:
(NOTE: The profile below may be translated into javascript using the Data::JavaScript perl module.) 

my $profile = {
    optional => [qw( company age fax country )],
    required => [qw( fullname phone email address )],
    constraints => {
        email => { name => "valid_email",
                   constraint => "/^(([a-z0-9_\\.\\+\\-\\=\\?\\^\\#]){1,64}\\@(([a-z0-9\\-]){1,251}\\.){1,252}[a-z0-9]{2,4})$/i" },
        age => { name => "valid_age",
                 constraint => "/^1?\d?\d$/" },
    },
    msgs => {
        constraints => {
            valid_email => "Invalid e-mail address format",
            valid_age   => "Age entered must be between 0 and 199",
        }
    },
};
The "optional" and "required" are probably self explainitory. Constraints add all the cool stuff.

In the above, the form field "email" must be filled in, AND it must match that awfully long regular expression that looks like line noise (that was borrowed from a built in constraint in the perl module Data::FormValidator).
If, and only if, the "age" field, it must match the constrint in it, which is a regular expression that would mean it has to be between 0 and 199.
The "name" keys in the constraints allow you to tie in the "msgs" hash, which is used for error reporting.

Your constraints may also be quite a lot simpler. For example, if you just want to make sure something is a whole number, the following is sufficient: "/^\d+$/".

The profile defined above would be specified as the following in javascript: 

var profile = new Object;
profile.optional = new Array( 'company', 'age', 'fax', 'country' );
profile.required = new Array( 'fullname', 'phone', 'email', 'address' );
profile.constraints = new Object;
profile.constraints.email = new Object;
profile.constraints.email.name = 'valid_email';
profile.constraints.email.constraint = '\/\^\(\(\[a\-z0\-9_\\\.\\\+\\\-\\\=\\\?\\\^\\\#\]\)\{1\,64\}\\\@\(\(\[a\-z0\-9\\\-\]\)\{1\,251\}\\\.\)\{1\,252\}\[a\-z0\-9\]\{2\,4\}\)\012i';
profile.constraints.age = new Object;
profile.constraints.age.name = 'valid_email';
profile.constraints.age.constraint = '\/\^1\?\\d\?\\d\012';
profile.msgs = new Object;
profile.msgs.constraints = new Object;
profile.msgs.constraints.valid_email = 'Invalid e\-mail address format';
profile.msgs.constraints.valid_age = 'Age entered must be between 0 and 199';

EASY VALIDATION

Once you've got your profile, You'll need to:

That's it. Your form now has data validation!

CUSTOM VALIDATION

The "check_and_report()" method is just a convenient wrapper around the workings of Data.FormValidator.js. It provides you with a default, and very easy, way to report on validation failures, should there be any. However, you're not required to use it by any means.

Data.FormValidator.js is an object oriented validation library. It can give you a TON of information about how the validation worked out, which you can use to report on its success/failure in any way you like. The docs included with the distribution cover this much better than I will here. Below is an example of how you could roll your own wrapper method (this was the source to "check_and_report()" at one time). 

function myValidate (frmObj) {
    var goodColor = "#FFFFFF";
    var badColor  = "#FFFF99";

    var profile = new Object;
    // define profile ...
    var results = Data.FormValidator.check(frmObj, profile);
    // clean up colors from form
    results.cleanForm(frmObj, goodColor);
    if (! results.success()) {
        var error_text = "";
        var msgs = results.msgs();
        for (field in results.missing_required) {
            results.changeStyle(frmObj, field, badColor);
            error_text += "Field ["+field+"] is required.\n";
        }
        for (field in results.missing_dependency) {
            for (i in results.missing_dependency[field]) {
                var dep = results.missing_dependency[field][i];
                results.changeStyle(frmObj, dep, badColor);
                error_text += "Marking field ["+field+"] requires field ["+dep+"] also be filled in.\n";
            }
        }
        for (group in results.missing_depgroup) {
            var completed  = results.missing_depgroup[group]['completed'];
            var incomplete = results.missing_depgroup[group]['incomplete'];
            for (i in incomplete) {
                results.changeStyle(frmObj, incomplete[i], badColor);
            }
            error_text += "Marking field(s) ["+completed.join(', ')+"] requires field(s) ["+incomplete.join(', ')+"] also be filled in.\n";
        }
        for (field in results.invalid) {
            results.changeStyle(frmObj, field, badColor);
            error_text += (msgs[field]) ? "Field ["+field+"] : "+msgs[field] :
                                          "Improperly formatted data in field ["+field+"].";
            error_text += "\n";
        }

        alert("There is a problem with your form.\n\n"+error_text);
        return false;

    } else {
        // do something with results.valid ?
        return true;
    } 
};
FURTHER READING

To get a better idea of what this module is capable of, please see its documentation at JSAN.

Because this module was based on the Data::FormValidator perl module, reading its thorough documentation can also be of great benefit.


GB (this link is just for some fun I'm having)