VM Form Validator API Documentation

VMFormValidator is a JavaScript form validation script based on MooTools 1.3. It aims to provide simple, reliable validation for all form element types across all browsers in an unobtrusive manner. It is 100% styled by CSS and allows for custom validations and error messages. Error messages can be displayed above the form, above each input, or below each input. VMFormValidator should not be used as a replacement for server-side validation (using PHP, .NET, etc) because JavaScript can be disabled.

Docs

Class: VMFormValidator

This class is for validating forms.

Implements:

Notes:

  • According to the W3C, the 'for' attribute for a label should refer to a form element's id, not the element's name. A good practice is to give your form elements an id that matches their names. This will ensure that your markup validates, while also reducing any chances of confusion in regards to a naming schema.

VMFormValidator Method: constructor

VMFormValidator is completely unobtrusive and requires no changes to existing markup, provided the form has an id and uses labels.

Syntax:

var form = new VMFormValidator(formId[, options]);

Arguments:

  1. formId - (string) The id of the form on which validation should be performed.
  2. options - (object, optional) Any of the options below.

Options:

  • disableSubmit - (boolean, defaults to true) Disable the submit button on validation failure.
  • errorDisplay - (string, defaults to 'belowInput') Where the errors are displayed. Acceptable values are: 'aboveInput', 'belowInput', and 'aboveForm'.
  • errorDisplayMultiple - (boolean, defaults to false) Display multiple errors at a time per element
  • errorListClass - (string, defaults to 'errorList') Class for the error display list.
  • errorListItemClass - (string, defaults to 'errorListItem') Class for each error display list item.
  • errorElement - (string, defaults to 'errorElement') Class for the form element when an error is detected.
  • errorLabel - (string, defaults to 'errorLabel') Class for the form element label when an error is detected.
  • labelDisplay - (string, defaults to 'before') Where the label is in relation to the form element in the HTML: 'before', 'after'.
  • successElementClass - (string, defaults to 'successElement') Class for the input box when validation succeeds.
  • successLabelClass - (string, defaults to 'successLabel') Class for the input label when validation succeeds.
  • validateOnBlur - (boolean, defaults to 'true') Validate each form element on blur.
  • validateOnSubmit - (boolean, defaults to 'true') Validate each form element on submit.

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
});

Notes:

  • Any form using VMFormValidator must have an id and labels must be used for all form elements that are validated.
  • VMFormValidator must be placed within the 'domready' event.
  • For multiple forms, you must use multiple instances of the class.
  • When using multiple forms, take care that no form elements share the same name or the errors will not appear in the second form.

VMFormValidator Method: addFunction

Adds a custom function to the onBlur and onSubmit events, to be run with the rest of the validations.

Syntax:

form.addFunction(name, customFunction);

Arguments:

  1. name - (string) The name of the form element to which the custom function should be applied.
  2. customFunction - (string) The function which should be applied for both onBlur and onSubmit events (if they are enabled) for the form element. The customFunction must be in string format because it is later executed using eval.

Example:

var custom_function = function(){
	alert('This is a custom function');
}

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.addFunction('firstName', 'custom_function()');
});

Notes:

  • The custom function should be defined outside the 'domready' event.

VMFormValidator Method: alpha

Validates alphabetic characters.

Syntax:

form.alpha(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field may contain only letters."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.alpha('firstName'); //Default error
	form.alpha('lastName', 'Please enter only letters for your last name'); //Custom error
});

VMFormValidator Method: alphanumeric

Validates alphanumeric characters.

Syntax:

form.alphanumeric(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field may contain only letters or numbers."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.alphanumeric('code'); //Default error
	form.alphanumeric('code', 'Code can contain only letters or numbers.'); //Custom error
});

VMFormValidator Method: canadaPostal

Validates Canadian Postal codes.

Syntax:

form.canadaPostal(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid Canadian Postal Code."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.canadaPostal('postal'); //Default error
	form.canadaPostal('postal', 'You don't really live in Canada, do you?'); //Custom error
});

See also:

VMFormValidator Method: credit

Validates all major credit card types including Visa, Mastercard, American Express, and Discover.

Syntax:

form.credit(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid credit card number."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.credit('credit'); //Default error
	form.credit('credit', 'That must have been your library card number. Try again.'); //Custom error
});

VMFormValidator Method: dateMDY

Validates a date in Month/Day/Year format. Accepts spaces, hyphens, forward slashes, or periods as seperators.

Syntax:

form.dateMDY(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid date in M/D/Y format."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.dateMDY('date'); //Default error
	form.dateMDY('date', 'Not a prune. A date.'); //Custom error
});

VMFormValidator Method: dateYMD

Validates a date in Year/Month/Day format. Accepts spaces, hyphens, forward slashes, or periods as seperators.

Syntax:

form.dateYMD(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid date in Y/M/D format."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.dateYMD('date'); //Default error
	form.dateYMD('date', 'If I have to pay, it isn't a real date.'); //Custom error
});

VMFormValidator Method: email

Validates most email addresses.

Syntax:

form.email(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid email address."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.email('email'); //Default error
	form.email('email', 'Did you want me to guess your email address?.'); //Custom error
});

See also:

VMFormValidator Method: excludes

Will return an error if any of the array values are present.

Syntax:

form.excludes(name, arrayCheck[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. arrayCheck - (array) Values that should return an error if they are present.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field cannot contain any of the following values: arrayCheck[]."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.excludes('spam', ['get rich quick', 'affiliate', 'millions']); //Default error
	form.excludes('spam', ['lottery', 'Nigeria', 'dead relative'], 'So sorry, we already made our millions.'); //Custom error
});

See also:

VMFormValidator Method: imageFile

Validate a file upload input to see if the file is an image.

Syntax:

form.imageFile(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please upload a valid image file. Valid files end with one of the following extensions: .jpg, .jpeg, .bmp, .gif, .png."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.imageFile('photo'); //Default error
	form.imageFile('photo', 'Photos only, please. With a signature, they're only $10 apiece.'); //Custom error
});

VMFormValidator Method: includes

Will return an error if any of the array values are not present.

Syntax:

form.includes(name, arrayCheck[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. arrayCheck - (array) Values that should return an error if one or more are not present.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field did not contain any of the following values: arrayCheck[]."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.includes('comments', ['I love Virtuosi Media', 'thank you', 'biggest fan']); //Default error
	form.includes('comments', ['I love Virtuosi Media', 'thank you', 'biggest fan'], 'Don't you love us?'); //Custom error
});

See also:

VMFormValidator Method: matches

Compares the values of two fields and returns an error if they do not match. Useful for confirming a password.

Syntax:

form.matches(name, compareName[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. compareName - (string) The name of the form element which name should match.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field does not match the compareName field."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.matches('password', 'confirmPassword'); //Default error
	form.matches('password', 'confirmPassword', 'Forget already? Not a good sign...'); //Custom error
});

See also:

VMFormValidator Method: maxLength

Sets a maximum length for a field.

Syntax:

form.maxLength(name, maxLength[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. maxLength - (integer) The maximum number of characters to be entered into the form element.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field may contain no more than maxLength characters."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.maxLength('name', 50); //Default error
	form.maxLength('name', 50, 'Helloooo Hemingway.'); //Custom error
});

See also:

VMFormValidator Method: minLength

Sets a minimum length for a field.

Syntax:

form.minLength(name, minLength[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. minLength - (integer) The minimum number of characters to be entered into the form element.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field must contain at least minLength characters."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.minLength('name', 4); //Default error
	form.minLength('name', 4, "Stingy, aren't we? Type at least four characters, please."); //Custom error
});

See also:

VMFormValidator Method: noMatches

Compares the values of two fields and returns an error if they match. Useful making sure a password doesn't match a username.

Syntax:

form.noMatches(name, compareName[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. compareName - (string) The name of the form element which name cannot match.
  3. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field cannot match the compareName field."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.noMatches('password', 'username'); //Default error
	form.noMatches('password', 'username', "That's like asking to be hacked."); //Custom error
});

See also:

VMFormValidator Method: numeric

Validate if a form element's value is numeric.

Syntax:

form.numeric(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field may contain only numbers."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.numeric('page'); //Default error
	form.numeric('page', "I can always count on you to type something you're not supposed to. Please enter only numbers."); //Custom error
});

Notes:

  • numeric checks only for numbers; periods and commas will cause an error.

See also:

VMFormValidator Method: password

Validates a password of at least one lowercase letter, one uppercase letter, and one number. The password must be at least 6 characters long.

Syntax:

form.password(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Your password must contain one lowercase letter, one uppercase letter, one number, and be at least 6 characters long."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.password('password'); //Default error
	form.password('password', "That's probably your cat's name, isn't it? Try something a little harder to crack."); //Custom error
});

VMFormValidator Method: phone

Validates a North American phone number, with the area code required. Allows for optional spaces, hyphens, or periods as separators and parentheses for the area code. A leading one or zero is also optional.

Syntax:

form.phone(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid phone number including area code."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.phone('phone'); //Default error
	form.phone('phone', "Please? We promise we won't call."); //Custom error
});

VMFormValidator Method: range

Sets a minimum length for a field.

Syntax:

form.range(name, minLength, maxLength[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. minLength - (integer) The minimum number of characters to be entered into the form element.
  3. maxLength - (integer) The maximum number of characters to be entered into the form element.
  4. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field must contain at least minLength and no more than maxLength characters."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.range('password', 4, 10); //Default error
	form.range('password', 4, 10, "Let's compromise. Not too long. Not too short."); //Custom error
});

See also:

VMFormValidator Method: required

Makes any form element required.

Syntax:

form.required(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "This field is required."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.required('creditCard'); //Default error
	form.required('creditCard', "Payment is required."); //Custom error
});

Notes:

  • Radio buttons are a special case in form validation because the tab index works differently across browsers. Internet Explorer, Safari, and Google Chrome will tab through only the first radio in a series, while Firefox and Opera will tab through each radio. VMFormValidator handles the cross browser validation for radios, ensuring that no false errors will be produced when the tab index hasn't finished cycling through a radio series in Firefox and Opera.

VMFormValidator Method: swearFilter

Triggers an error if a common swear word is present in a form element.

Syntax:

form.swearFilter(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please refrain from using profanity."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.swearFilter('comments'); //Default error
	form.swearFilter('comments', "That wasn't a very nice thing to say."); //Custom error
});

Notes:

  • For a more comprehensive swear filter, use the excludes method to define your own set of words.

See also:

VMFormValidator Method: url

Validates most URLs.

Syntax:

form.url(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid URL."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.url('website'); //Default error
	form.url('website', "What part of 404 don't you understand?"); //Custom error
});

See also:

VMFormValidator Method: usZip

Validates US ZIP codes. The four digit ZIP code extension is optional.

Syntax:

form.usZip(name[, error]);

Arguments:

  1. name - (string) The name of the form element to which the validation should be applied.
  2. error - (string, optional) The error message to be displayed on validation failure. Default message: "Please enter a valid US ZIP Code."

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.usZip('zip'); //Default error
	form.usZip('zip', 'Bonus points if you can enter a correct ZIP code AND tell me what ZIP stands for.'); //Custom error
});

See also:

VMFormValidator Method: validateRegEx

Validates a custom regular expression.

Syntax:

form.validateRegEx(regex, name, error);

Arguments:

  1. regex - (string) A regex to evaluated.
  2. name - (string) The name of the form element to which the validation should be applied.
  3. error - (string) The error message to be displayed on validation failure. There is no default message.

Example:

window.addEvent('domready', function(){
	var form = new VMFormValidator('exampleForm');
	form.validateRegEx('mootools', 'favorite', "You must type 'MooTools.'"); 
});

Further JavaScript Regular Expression Resources:

Tags

  • Benjamin Kuker

    Benjamin Kuker

    Benjamin Kuker is the co-founder of Virtuosi Media and is married to his beautiful wife, Johanna. He is responsible for the design and maintenance of this website. He enjoys reading, writing, programming, business, sports, and traveling.

    View Benjamin's Bio

Help us spread the word.

Your Comments Are Valuable - Join The Discussion!

 

Copyright 2011 Virtuosi Media Inc.