NAME
    Form.Validator - a class for form validation

SYNOPSIS
    Make a form with an "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>

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

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

METHODS
  new Form.Validator(form)
    This is the constructor. It takes a form object as its only parameter.

    Example:

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

  set('input_field', validationFunction, 'Error Message');
    This method associates a validation function and error message to an
    input field in the form.

    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."
      );

  get('input_field')
    This method returns a list of the validation settings for a given input
    field.

  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. "True" means it passed, and "false"
    means it failed.

  validateAndAlert()
    This function is intended to be used as an "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 "false" to prevent the form from being submitted.

    Example:

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

BUILT-IN VALIDATION TESTS
  notBlank
    Tests that the input is not blank. Note that inputs filled with only
    whitespace still count as being blank.

  notZero
    Tests that the input is not 0.

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 "fv.form".

    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 "notOdd" test, all Form.Validator objects
    instantiated since then can test to see whether a field has an odd value
    or not.

TO DO
    * Add more validation functions.
      "notBlank" and "notZero" alone can do a lot, but a few more validation
      functions would be nice to have.

    * 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.

AUTHOR
    John Beppu (john.beppu@gmail.com)