• Home
• News
• FAQ
• Documentation
• Community
• About

Stevan Little - HTML.Form.Validator-0.01

  // inside an onSubmit handler
  var validator = new HTML.Form.Validator('my_form');
  validator.addElement(new HTML.Form.Validator.Element('my_element', 'This is my error message'));
  validator.addElement(new HTML.Form.Validator.Element('my_other_element', 'This is my other error message!'));
  validator.validate();

// set up the namespace
if (HTML      == undefined) var HTML      = function () {};
if (HTML.Form == undefined)     HTML.Form = function () {};

HTML.Form.Validator = function (form_name, success_handler) {
	this.form_name = form_name;
	this.success_handler = success_handler || function (formObj) { formObj.submit() };
	this.elements = [];	
}

HTML.Form.Validator.VERSION = '0.01';

HTML.Form.Validator.prototype.addElement = function (element) {
	this.elements[this.elements.length] = element;
}

HTML.Form.Validator.prototype.validate = function () {
	var form_object = document.forms[this.form_name];    
	for (var i = 0; i < this.elements.length; i++){
		if (!this.elements[i].validate(form_object)){
			return false;
		}
	}
	return this.success_handler(form_object);
}

/*

=pod

=head1 NAME

HTML.Form.Validator - A framework for HTML Form Validation

=head1 SYNOPSIS

  // inside an onSubmit handler
  var validator = new HTML.Form.Validator('my_form');
  validator.addElement(new HTML.Form.Validator.Element('my_element', 'This is my error message'));
  validator.addElement(new HTML.Form.Validator.Element('my_other_element', 'This is my other error message!'));
  validator.validate();

=head1 DESCRIPTION

This module is an object oriented framework for HTML form validation. It's design is very simple, with 
the goal of making complex form validations fairly easy to create using arbitrary combinations of 
highly reusable components. This framework already comes with a set of several validators which are
easily combined and re-used (see L<HTML.Form.Validator.Library> for more information).

At it's most basic, there is the C<HTML.Form.Validator> object, which takes a collection of 
C<HTML.Form.Validator.Element> objects. Each C<HTML.Form.Validator.Element> object represents a single form 
element to be validated. Once you have added all your Element object, you call C<HTML.Form.Validator.validate()>
and the validator will run through each element validating each one based on the details of the element. More 
complex validations can also be accomplished using the C<HTML.Form.Validator.CompoundElement> class, which 
allows for arbitrary combinations of multiple C<HTML.Form.Validator.Element> objects into a single validation
element.

Some nice features include; the ability to add both custom error messages as well as custom error handlers on a
per-elements basis, support for a success handler in the main validator, upon error and after the error handler 
the problem element is given focus in the browser. 

=head1 PROPERTIES

=over 4

=item B<form_name>

This is the name of the HTML form element which we are validating.

=item B<elements>

This is a collection of C<HTML.Form.Validator.Element> and C<HTML.Form.Validator.CompoundElement> objects
which the validator will run.

=item B<success_handler>

This is a function which will be called if the validation is successful. It will be passed a valid HTML Form
object as it's only arguement. If this value is not set, then a default is provided which looks like this:

  function (formObj) { formObj.submit() }

=back

=head1 METHODS

=over 4

=item B<new HTML.Form.Validator (form_name, success_handler)>

This will create a new HTML.Form.Validator, a C<form_name> should always be provided, however the 
C<success_handler> is optional.

=item B<addElement (element)>

This adds a given C<element> (which is a C<HTML.Form.Validator.Element> or C<HTML.Form.Validator.CompoundElement>
object instance) to be validated with later.

=item B<validate ()>

This will perform the validation on all the C<elements> and return false if it fails, or run the C<success_handler>
if it succeeds.

=back

=head1 TODO

=over 4

=item Write some tests for the C<HTML.Form.Validator.Library> classes.

=back

=head1 AUTHOR

stevan little, E<lt>stevan@iinteractive.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2005 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl. 

=cut

*/