Mootools FormValidator – How to use (Part 1)

Tutorial Part 1 • Part 2 • Part 3 • Part 4 • Live demo

One of the nicest Mootools.more components is the FormValidator – but the documentation is incomplete and IMHO not very easy to comprehend.

After using the FormValidator a lot, I decided to begin writing a tutorial in several parts.

Overview

Note: MooTools more version 1.2.4+ is being used.

First have a look at the example: Form Validation Demo »

Each input-field in the form can have a list of validators. A validator checks one specific aspect, for example minimum length. There are a lot of pre-defined validators (see mootols/docs).

To make validation nearly automatic, we initialize an instance of FormValidator.Inline for the form.

FormValidator initialization

First we initialize the FormValidator.Inline-object. The first parameter is the CSS-id of the form, the second parameter are options:

stopOnFailure means this: If one validation fails, all other fields are temporarily ignored. This is more user-friendly – otherwise clicking through the fields would show one error message after another..

useTitles allows us to overwrite the error messages with the title-attribute, you can see this in the last field (“terms of service”) – where we show a custom message.

errorPrefix is a text that is shown before all error messages, defaults to “Error: “. But an error message is enough, no need to repeat that it’s an error, so I set to an empty string.

The onFormValidate method is called if everything is all right – in this case, we submit the form.

onElementValidate is called after each Validation. This is useful to handle some fields specifically – here for demonstration purposes: An annoying alert.

window.addEvent('domready', function() {
	myFormValidator = new Form.Validator.Inline($('register'), {
		stopOnFailure: true,
		useTitles: true,
		errorPrefix: "",
				
		onFormValidate: function(passed, form, event) {
			if (passed) {
				form.submit();
			}
		},

		onElementValidate: function(passed, element, validator, is_warn) {
			if (element.get('name') == 'agb' && !passed) {
				alert('Hey, the terms are really important!');
			}
		}
	});
});

Field validation

All validators for a field are simply listed as classes, here an example:

<input class="required validate-email emailUnique" type="text" name="profile[email]" />

Here three rules are applied:

required – The field can’t be empty
validate-email – The field has to contain a valid email
..and a custom validator – explained in Part 2

Length

<input type="text" class="minLength:2" name="profile[firstname]" />

The firstname should be at least 2 characters long. Note that “required” isn’t necessary anymore, since 2 characters already imply that something is filled in.

More length

<input type="text" class="validate-alphanum minLength:3 maxLength:30"  name="profile[username]" maxlength="30" />

A custom validator (explained in Part 2) called “alphaNumFix” and more restrictions: minimum 3, maximum 30 chars.

Checkboxes, custom error message

<input type="checkbox" class="validate-required-check" title="Please agree to the terms of service." name="terms"  value="1" />

The title is used as custom error message, validate-required-check does exactly what it sounds like…

Password repeat

<input type="password" class="required validate-match matchInput:'password' matchName:'Password'" name="profile[password2]" />

This is the “repeat your password”-field. validate-match is exactly for such cases.

Note the properties:

matchInput – CSS-id of the other field, which has to match
matchName – How the other field is called in the error message.

If we do not specify the matchName, this would be the error message:
“This field needs to match the profile[password] field”.
Now it’s clearer:
“This field needs to match the Password field”

Styling the output

These are the CSS classes used by the FormValidator:

.validation-passed { background-color: #99cc99 !important; }
  /* This style is applied to input fields after successful validation */

.validation-advice { background-color: #cc9999; color: white; margin: 3px; padding: 3px; } 
  /* This style is applied to the error messages */

.validation-failed { background-color: #cc9999; }
  /* This style is applied to input fields after validation failed */

Part 2 can be found here: How to use (Part 2) »