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

John Beppu - Form.Validator-0.11

  <form name="stuff"
    action="process_stuff.mas"
    method="POST"
    onSubmit="return fv.validateAndAlert()">

    name: <input name="name" type="text"><br/>

    category:
    <select name="category_id">
      <option value="0">Select a category</option>
      <option value="1"> cat 1 </option>
      <option value="2"> cat 2 </option>
      <option value="3"> cat 3 </option>
    </select>
    <br/>

    <input type="submit" name="submit" value="Save" />
  </form>

  <script>
    fv = new Form.Validator(document.stuff);
    fv.set('name',        'notBlank', "The name field may not be blank.");
    fv.set('category_id', 'notZero',  "You need to pick a category.");
  </script>

  var fv = new Form.Validator(document.stuff);
  var fv2 = new Form.Validator(document.forms[0]);

  // using a built-in validator function
  fv.set('name', 'notBlank', "Name must be filled in.");

  // using a custom validator
  fv.set('category_id',
    function(fv, field) {
      if (fv.form[field].value == 3) {
        return false;
      } else {
        return true;
      }
    },
    "Problems always come in 3s.  Bad choice, my friend."
  );

  <form name="stuff"
    action="process_stuff.mas"
    method="POST"
    onSubmit="return fv.validateAndAlert()">

  Form.Validator.prototype.notOdd = function(fv, field) {
    var form = fv.form;
    if (form.field.value & 0x01) {
      return false;
    } else {
      return true;
    }
  };

if (Form == undefined) var Form = { };

Form.Validator = function(form) {
	this.form = form;
	this.list = new Array();
};

Form.Validator.VERSION = 0.11;

// Form.Validator Class
Form.Validator.prototype = {

	form:   null,

	list:   null,

	// define a constraint for a field
	set: function(field, constraintFunction, message) {
		var c     = new Object;
		c.field   = field;
		c.message = message;

		if (typeof(constraintFunction) == 'string') {
			// predefined validator
			c.constraint = this[constraintFunction];
		} else {
			// closure w/ you're own validator
			c.constraint = constraintFunction;
		}

		this.list.push(c);
	},

	// get contraint info for a field. (this can return more than 1 constraint)
	get: function(field) {
		var constraints = new Array();
		for (i in this.list) {
			var c = this.list[i];
			if (c.field == field) {
				constraints.push(c);
			}
		}
		return constraints;
	},

	// run all validation tests and return result as an array
	validate: function() {
		var status;
		var i, c;
		var rv = new Array();
		for (i in this.list) {
			c = this.list[i];
			// somehow, this.list is getting polluted w/ an extra element.
			if (typeof(c.constraint) != 'function') {
				continue;
			}
			status = c.constraint(this, c.field);
			rv.push(status);
		}
		return rv;
	},

	// like validate() but displays an alert box telling you what went wrong
	validateAndAlert: function() {
		var ok;
		var i, c;
		var messages = new Array();
		for (i in this.list) {
			c = this.list[i];

			// somehow, this.list is getting polluted w/ an extra element.
			if (typeof(c.constraint) != 'function') {
				continue;
			}

			ok = c.constraint(this, c.field);
			if (!ok) {
				messages.push(c.message);
			}
		}
		if (messages.length > 0) {
			alert(messages.join("\n"));
			return false;
		}
	},


	// VALIDATION FUNCTIONS

	// false means you messed up
	// true  means you're cool

	// Make sure a field's value is not blank
	notBlank: function(fv, field) {
		var blankness = new RegExp(/^\s*$/);
		if (blankness.test(fv.form[field].value)) {
			return false;
		} else {
			return true;
		}
	},
	// ...meaning, you can't be Blank; if you are, you messed up; else you're cool
 
	// Make sure a field's value is not 0
	notZero: function(fv, field) {
		if (fv.form[field].value == "0") {
			return false;
		} else {
			return true;
		}
	},

};

/*

=head1 NAME

Form.Validator - a class for form validation

=head1 SYNOPSIS

Make a form with an C<onSubmit> handler:

  <form name="stuff"
    action="process_stuff.mas"
    method="POST"
    onSubmit="return fv.validateAndAlert()">

    name: <input name="name" type="text"><br/>

    category:
    <select name="category_id">
      <option value="0">Select a category</option>
      <option value="1"> cat 1 </option>
      <option value="2"> cat 2 </option>
      <option value="3"> cat 3 </option>
    </select>
    <br/>

    <input type="submit" name="submit" value="Save" />
  </form>

Add in JavaScript later on:

  <script>
    fv = new Form.Validator(document.stuff);
    fv.set('name',        'notBlank', "The name field may not be blank.");
    fv.set('category_id', 'notZero',  "You need to pick a category.");
  </script>

=head1 DESCRIPTION

This class provides a simple, object-oriented API for form validation.
After instantiating a new L<Form.Validator|Form.Validator> object, 
form validation is just a matter of setting up a list of constraints 
for your form inputs using the C<set()> method.  Then, in the onSubmit
handler for your form, C<return fv.validateAndAlert()>.

So far, only two validation functions are provided:  
B<notZero> and B<notBlank>.
It might not seem like much, but you can get surprisingly far with them.
See F<examples/payment_profile.mas.html> to see just how far.
Of course, you may use custom validation functions as well.
See L</WRITING YOUR OWN VALIDATION FUNCTIONS> to find out how.

=head1 METHODS

=head2 new Form.Validator(form)

This is the constructor.  It takes a form object as its only parameter.

B<Example>:

  var fv = new Form.Validator(document.stuff);
  var fv2 = new Form.Validator(document.forms[0]);

=head2 set('input_field', validationFunction, 'Error Message');

This method associates a validation function and error message to
an input field in the form.

B<Example>:

  // using a built-in validator function
  fv.set('name', 'notBlank', "Name must be filled in.");

  // using a custom validator
  fv.set('category_id',
    function(fv, field) {
      if (fv.form[field].value == 3) {
	return false;
      } else {
	return true;
      }
    },
    "Problems always come in 3s.  Bad choice, my friend."
  );

=head2 get('input_field')

This method returns a list of the validation settings for a given input field.

=head2 validate()

This method runs through the list of validation settings in the order they were
defined and returns an Array of boolean values which indicate whether the test
passed or not.  C<True> means it passed, and C<false> means it failed.

=head2 validateAndAlert()

This function is intended to be used as an C<onSubmit> handler on a form.  It
runs through the validation tests in the order they were defined and displays
an alert box if any of the validation tests failed.  Then it will return
C<false> to prevent the form from being submitted.

B<Example>:

  <form name="stuff"
    action="process_stuff.mas"
    method="POST"
    onSubmit="return fv.validateAndAlert()">

=head1 BUILT-IN VALIDATION TESTS

=head2 notBlank

Tests that the input is not blank.  Note that inputs filled with 
only whitespace still count as being blank.

=head2 notZero

Tests that the input is not 0.

=head1 WRITING YOUR OWN VALIDATION FUNCTIONS

If the provided validation tests are not enough to fulfill your needs, you may
add validation functions of your own.  They should expect to receive 2
parameters.  The first is the Form.Validator object (fv) and the second is the
name of the field that the function needs to test.  To get at the actual form,
access C<fv.form>.

B<Example>:

  Form.Validator.prototype.notOdd = function(fv, field) {
    var form = fv.form;
    if (form.field.value & 0x01) {
      return false;
    } else {
      return true;
    }
  };

Now that we've added the C<notOdd> test, all Form.Validator objects instantiated
since then can test to see whether a field has an odd value or not.

=head1 TO DO

=over 2

=item * Add more validation functions.

C<notBlank> and C<notZero> alone can do a lot, but a few
more validation functions would be nice to have.

=item * Add hooks for post validation actions.

I think these might be helpful to those who want to do fancy AJAX-ish
things along with validation.

=back

=head1 AUTHOR

John Beppu (john.beppu@gmail.com)

=cut

*/