Regulate is a versatile form validation library (no longer maintained, PRs welcome).
- Underscore 1.0.0+
- jQuery 1.7.0+
Regulate intercepts the onSubmit event for your forms and validates them according to your requirements. It then reports back with the data if validation passed or with the errors if validation failed.
- Regulate does not submit the data, it merely validates it and reports back with a result.
- Regulate supports validations for fields that should match (like for passwords), but doesn't support fields whose validation requirements depend on the value of other fields.
Note: Any field that's referenced is required
by default. This means that validation
will fail if the field's associated value is a falsy type (null, "", undefined, etc.).
<form id='myForm'>
<input type='text' name='foo'/>
<p id='foo-error'></p>
<input type='text' name='bar'/>
<p id='bar-error'></p>
<input type='file' name='anImage'/>
<p id='anImage-error'></p>
<input type='submit'/>
</form>
The validation metrics for myForm
:
Regulate('myForm', [
{
name: "foo",
display_as: "Foo"
display_error: "#foo-error"
},
{
name: "bar",
min_length: 3,
max_length: 10,
display_as: "Bar"
display_error: "#bar-error"
},
{
name: "anImage",
max_length: 1024 * 1024, // in bytes
accepted_files: "jpeg|png",
display_as: "An image",
display_error: "#anImage-error"
}
]);
Register an onSubmit
callback that accepts error
& data
arguments:
Regulate.myForm.onSubmit(function (error, data) {
if (error) {
console.log('Validation failed! These are the error messages: ', error);
} else {
console.log('Validation passed! This is the data: ', data);
}
});
The data argument for the onSubmit callback is an array of objects. Each object
corresponds to its form element. This includes fields that were not validated
through Regulate. All data objects have name
and value
properties. They
can also contain additional information unique to the corresponding element type.
// The data array for the sample form above would look like this:
data => [
{
name: 'foo',
value: 'foosVal'
},
{
name: 'bar',
value: 'barsVal'
},
{
name: 'anImage',
value: 100, // the size in bytes
fileType: 'image/jpeg', // the media type
files: FileList // this is the FileList object for the element
}
]
By default, any field listed in the requirements for your form will be required. That is, the field will not pass validation if it's empty, unchecked, or unselected.
For more control, the following field rules are included with Regulate:
email
match_field
min_length
max_length
exact_length
min_checked
max_checked
exact_checked
min_selected
max_selected
exact_selected
max_size
accepted_files
As the included rules are rather sparse. If needed, you can register custom field rules by passing a test function with an arity of 3 (the field value, the field requirements, all of the field requirements). Here's an example:
Regulate.registerRule('unique', function (fieldValue, fieldReqs, fields) {
var isUnique = myFnThatChecksUniqueness(fieldValue);
return isUnique; // true or false.
});
All error messages are generated by functions that receive 2 arguments, the fieldName
(the name of the html element), and fieldReqs
(the requirements for the field to pass validation). You have the option of adding new messages generators or overriding existing ones. The following code adds a message generator for the unique
rule registered in the previous example.
// Adding a message generator for the 'unique' rule shown in the 'Custom Rules' sample code
Regulate.registerMessage('unique', function (fieldName, fieldReqs) {
return fieldName + " is already taken.";
});
As an alternative, you can also provide your error messages together with your validation metrics via the error
property. An example:
Regulate('registrationForm', [
{
name: "username",
min_length: 3,
max_length: 18,
display_as: "Username",
display_error: '#username-error',
error: {
required: "The username is required.",
min_length: "Your username should be atleast 3 characters long.",
max_length: "Your username should be no more than 18 characters. Create a shorter name.",
}
},
{
name: "userEmail"
email: true,
error: "Please provide a valid email address. We promise not to send you spam."
}
]);
Note that the error value can be an object
or string
data type. A string
value will override all error messages with a single error message (see userEmail
in the example above). An object
value will override the error messages for the rules that you specify. When providing an object
as the error value, you should map rule names to their corresponding error message.
By default, Regulate ships with its error messages in english. If you wish
to introduce other translations, you can do so via Regulate.addTranslation
.
A complete example in spanish is available in languages/regulate_es.js
. For the
sake of illustration, here's a quick example:
// A translation should map rule names to functions that return an error message.
var fooTranslation = {
required: function (fieldName, fieldReqs, formReqs) {
return "Yo, " + fieldName + " can't be blank.";
},
min_length: function (fieldName, fieldReqs, formReqs) {
return "Yo, min length for " + fieldName + " is " + fieldReqs.min_length;
},
max_length: function (fieldName, fieldReqs, formReqs) {
return "Yo, max length for " + fieldName + " is " + fieldReqs.max_length;
},
//...
};
// Add the translation...
Regulate.addTranslation('foo', fooTranslation);
Or if you're adding more than one translation...
Regulate.addTranslations({
foo: fooTranslation,
bar: barTranslation,
// ...
});
So this has added the foo
translation. Before we start using foo
we probably
want to translate the individual forms as well. This can be done via
Regulate.<yourForm>.addTranslation
.
// Make note of the display_as values which will be translated.
Regulate('myForm', [
{
name: 'firstName',
display_as: 'First name'
},
{
name: 'lastName',
display_as: 'Last name'
}
]);
// Add a translation for the display_as values.
Regulate.myForm.addTranslation('foo', {
firstName: "Yo, first name",
lastName: "Yo, last name"
});
If you're adding more than one translation to your form. You can leave out the
display_as
fields and declare here instead:
Regulate.myForm.addTranslations({
en: {
firstName: "First name", // alternative to display_as
lastName: "Last name"
},
foo: {
firstName: "Yo, first name",
lastName: "Yo, last name"
},
//...
});
To start using the foo
translation make a call to Regulate.useTranslation
.
// Use the foo translation
Regulate.useTranslation('foo');
This will present error messages using the foo
translation as well as the corresponding
translation for the individual forms.
Next
- Validations that trigger onChange.
Soon
- A cleaner way to add/override custom error messages.
- Partial form validations (request).
- Complete documentation.
- Moar rules.
I appreciate your feedback, feel free to report issues, suggestions, and PRs.