form_validations.js

ABSTRACT:
This file contains a library of general-purpose javascript form
validation functions.  It is intended to provide a consistant set of
rules and methods for form validation.

NOTE: Do not copy this file into your project.  The latest version
of this file should always be available on all LAF servers as:
  /LAFcommon/form_validations.js
It can be included into any HTML or ASP file with the following lines:
  <SCRIPT LANGUAGE="Javascript" SRC="/LAFcommon/form_validations.js">
  </SCRIPT>
If your project is to be hosted somewhere other than LAF, please
verify that the LAFcommon library will _not_ be installed on the
server before making a copy of this file in your project directory.

NOTE: No functions from this library should be called directly except
the four detailed below.

USAGE:
For every form field on your page that you want to validate, call the
following function once:
  validate_addelement(form_element, element_type, format_fail,
    required_flag, required_fail)
The parameters have the following meanings:
  form_element: The Javascript object of your form element, usually
    something like document.form_name.object_name.  Be careful when
    using DHTML tags like LAYER, ILAYER, SPAN and DIV -- they create
    sub-"document" objects that contain their content.  In those cases
    you should call validate_addelement() from within the DHTML block.
    NOTE: Do not surround this parameter with quotes -- the object
    reference is required, not the name of the object as a string.
  element_type: A string representing the type of data your form element
    contains.  See below for acceptable values and what they expect.
  format_fail: The string to print when the data in the field is not
    of the correct type.  See below for how the string is seen.
  required_flag: A boolean indicating if data is required in the field
    -- validation will not be performed if the field is empty.  This
    parameter is ignored for some field types (see below).
  required_fail: The text to print when data is required in the field
    but none was supplied.  See below for how the string is seen.

If you want to change the way a field is validated after
validate_addelement() has been called, call the following function:
  validate_addelement(form_element, element_type, format_fail,
    required_flag, required_fail)
The parameters have the same meanings as those for validate_addelement(),
above.  Unlike above, validate_updateelement() will update the stored
information for an already-added element but will not add the element if
it has not been previously added.  This is useful for changing an
element's required status, etc.

If you want validation to take place as the user is working, call the
following function from the form element's onChange handler:
  validate_checkone(form_element, noisy_flag, select_flag)
The parameters have the following meanings:
  form_element: The Javascript object of the form element that was
    given in the validate_addelement() call.  From within an element's
    onChange handler, the keyword "this" refers to the object.
  noisy_flag: A boolean value indicating that if the element fails
    validation, an alert box should appear containing the corresponding
    message from the validate_addelement() call.
  no_select_flag: OPTIONAL (default: false).  A boolean value indicating
    that if the element fails validation, the input element is not to be
    selected after the alert message is displayed to the user.  If
    noisy_flag is false, this parameter has no effect.
Note that validate_checkone() returns a true or false value to indicate
the outcome of the validation regardless of the value of the noisy_flag
parameter.

To check all of the elements at once, call the following function:
  validate_checkall(noisy_flag, form_object, select_flag)
The parameter has the following meaning:
  noisy_flag: A boolean value indicating that if an element fails
    validation, an alert box should appear containing the corresponding
    message(s) from the validate_addelement() call(s).
  form_object: OPTIONAL.  The form object that contains the elements to
    be validated.  This is really only necessary if the page contains
    multiple, unrelated forms that need to be validated.  If this
    parameter is given, ONLY the elements belonging to the given form
    object will be validated -- all others will be ignored.  NOTE: If
    validate_checkall() is being called from the form's onSubmit handler,
    the keyword "this" (without the quotes) will reference the form
    object.  If validate_checkall() is being called from the submit
    button's onClick handler, the expression "this.form" (without the
    quotes) will reference the form object.
  no_select_flag: OPTIONAL (default: false).  A boolean value indicating
    that if an element fails validation, the input element is not to be
    selected after the alert message is displayed to the user.  If
    noisy_flag is false, this parameter has no effect.
validate_checkall() is typically called just before the form is
submitted, either from the form's onSubmit handler or the submit
button's onClick handler.  Note that validate_checkall() returns a true
or false value to indicate the outcome of the validation regardless of
the value of the noisy_flag parameter.

NOTE: The element types below dealing with credit card account numbers
only validate that (1) the account number is the correct length, (2) the
account number passes the LUHN formula and (3) the number falls within
a range allocated for the given account provider.  They do not verify
that the account actually exists.

The valid element type strings are as follows:
  "americanexpress": A TEXT or TEXTAREA that contains a valid American
    Express account number with no spaces or dashes.
  "candianzip": A TEXT or TEXTAREA that contains a Canadian ZIP code
    (three alphanumeric characters, a space and three more alphanumeric
    characters).
  "cdate": A "date" that is representable in C's 32-bit time_t datatype
    (i.e. between 1/1/1970 and 1/18/2038, inclusive).
  "cdatetime": A "datetime" that is representable in C's 32-bit time_t
    datatype (i.e. between 1/1/1970 00:00:00 and 1/18/2038 21:14:07,
    inclusive).
  "checkbox": A CHECKBOX.  No validation is done on checkboxes at
    all -- it is only included for completeness.
  "creditcard": An "americanexpress", "dinersclub", "discover", "jcb",
    "mastercard" or "visa"
  "date": A TEXT or TEXTAREA that contains a date.  Must be in
    numeric notation and can use either dashes or slashes as
    separators.  Four digit years must be used.
  "datetime": A TEXT or TEXTAREA that contains a date followed by a
    time.  The date is validated as above for "date".  The time can be
    in either civilian (12-hour) format or military (24-hour) format.
    Seconds can be given.
  "dinersclub": A TEXT or TEXTAREA that contains a valid Diner's Club
    account number with no spaces or dashes.
  "discover": A TEXT or TEXTAREA that contains a valid Discover
    account number with no spaces or dashes.
  "email": A TEXT or TEXTAREA that contains an email address: one or
    more characters followed by a '@', followed by one or more
    characters that contain at least one period.
  "float": A TEXT or TEXTAREA that contains a real number.  Can use
    scientific notation.
  "integer": A TEXT or TEXTAREA that contains an integer number.
    Can use scientific notation.
  "jcb": A TEXT or TEXTAREA that contains a valid JCB account number
    with no spaces or dashes.
  "mastercard": A TEXT or TEXTAREA that contains a valid MasterCard
    account number with no spaces or dashes.
  "money": A TEXT or TEXTAREA that contains a number preceded by a
    dollar sign ('$'), exactly two decimal places and optional commas
    every third digit.
  "mssqldate": A "date" that MS SQL Server will accept (i.e.
    1/1/1753 or later).
  "mssqldatetime": A "datetime" that MS SQL Server will accept (i.e.
    1/1/1753 12:00 AM or later).
  "number": A number, either an "integer" or a "float".
  "phone": A TEXT or TEXTAREA that contains a phone number.  It will
    take a large number of inputs.  Basically, a phone number is a
    collection of seven or more numbers.  The first three numbers can
    be separated from the others by a dash, a comma or a period and one
    or more spaces.  If an area code is given, it must be three digits
    long.  It may be surrounded by parenthesis and separated from the
    rest of the numbers by a dash, a comma or a period and one or more
    spaces.  An extension, if provided, can be up to six digits and can
    be separated from the rest of the numbers by an 'x', an 'X', a dash,
    a comma, a period, "ext" with any capitalization and optionally
    followed by a period.
  "radio": A RADIO.  No format validation is done on radio buttons,
    but they can be checked to see if a choice has been made.
  "select": A SELECT.  No format validation is done on select fields,
    but they can be checked to see that both a value has been selected
    and that value is not zero-length.
  "text": A TEXT or TEXTAREA.  No format validation is done on text
    fields.
  "uszip": A TEXT or TEXTAREA that contains a U.S. ZIP code (a five
    digit number optionally followed by a dash and four more digits).
  "visa": A TEXT or TEXTAREA that contains a valid Visa account number
    with no spaces or dashes.
  "zip": A "uszip" or a "canadianzip".