alid "requirement" strings are:
                  "required"    - field must be filled in
                  "digits_only" - field must contain digits only
                  "length=X"    - field has to be X characters long
                  "length=X-Y"  - field has to be between X and Y (inclusive)
                              characters long
                  "valid_email" - field has to be valid email address
                  "valid_date"  - field has to be a valid date
                            fieldname:  MONTH                 fieldname2: DAY
        fieldname3: YEAR
                            date_flag:  "later_date" / "any_date"
                  "same_as"     - fieldname is the same as fieldname2 (intended
                            for password comparison).
                  "range=X-Y"   - checks that a number has a value between
                            X and Y (inclusive).

    E.g. an area home phone number form field "<input type='text' name='homePhone_area' />" would be
    validated as follows:

      <cfset variables.fieldInfo = ArrayNew()>
      <cfset variables.fieldInfo[1] = "required,homePhone_area,Please enter area home phone">
      <cfset variables.fieldInfo[2] = "digits_only,homePhone_area,Home phone area must only contain digits">
      <cfset variables.fieldInfo[3] = "length=3,homePhone_area,Home phone area must be 3 digits long">

      <cfinvoke   
       component="#request.componentPath#.Error"
       method="validateFields">
        <cfinvokeargument name="pageAttributes" value="#attributes#">
        <cfinvokeargument name="fieldInfo" value="#variables.fieldInfo#">
      </cfinvoke>

    Notes:
    - The array position in which the error messages appear for a single form field IS important. If
    homePhone_area failed the first check (index 1), the function will NOT check the two following
    requirements (indexes 2 and 3). That way, the user won't get three error messages for one incorrectly
    filled in field.
    - Duplicate error messages are not returned.

    If any of the the form fields contain an error, the function redirects the user back to the original form
    and makes two new variables available in sessions in WDDX format:

      session.wddx_pageAttributes
      session.wddx_errorMessages

    So, form page should contain this code, where-ever you want the list of error messages to
    appear:
   
      <!--- if required, display form validation errors --->
      <cfif IsDefined("session.wddx_errorMessages")>
        <cfwddx action="wddx2cfml" input="#session.wddx_errorMessages#" output="variables.errMessages">
        <cfinvoke
         component="#request.componentPath#.Error"
         method="displayErrors">
          <cfinvokeargument name="errorMessages" value="#variables.errMessages#">
        </cfinvoke>
      </cfif>

    NOTES FOR UPGRADES:
      - consider adding "zip_canada", "zip_US", "zip_northAmerica" options.
      - I deliberately return a struct of "fieldname" => "error message", not just error messages,
        so you could use the fieldname data to HIGHLIGHT those fields that contain errors.
      - "is_alpha" requirement
      - add valid_date routine, which checks for valid dates - plus additional later_date,
        earlier_date options to check date being inputted is earlier or later than current date.
  ---------------------------------------------------------------------------------------------->
  <cffunction access="public" name="validateFields" output="true" displayName="validateFields"
    hint="Validates fields for any web form; returns a list of error messages">
    <cfargument name="pageAttributes" type="any" required="yes" displayname="pageAttributes">
    <cfargument name="fieldInfo" type="array" required="yes" default="" displayname="reqFieldInfo">

<!--- this stores a LIST of errors found. (An array of lists of form: 'fieldName,error message' --->
    <cfset variables.errors = ArrayNew(1)>    <!--- stores all errors --->

    <cfloop from="1" to="#ArrayLen(arguments.fieldInfo)#" index="i">

      <!--- split the required field information into its component parts --->
      <cfset variables.requirement  = ListFirst(arguments.fieldInfo[i], ",")>
      <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>
      <cfset variables.fieldName    = ListFirst(arguments.fieldInfo[i], ",")>
      <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>

      <!--- if we're doing a "same_as" validation, there's a second fieldname listed --->
      <cfif variables.requirement EQ "same_as">     
        <cfset variables.fieldName2   = ListFirst(arguments.fieldInfo[i], ",")>
        <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>

      <!--- if we're doing a "valid_date" validation, extract extra fields --->
      <cfelseif variables.requirement EQ "valid_date">
        <cfset variables.fieldName2   = ListFirst(arguments.fieldInfo[i], ",")>
        <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>
        <cfset variables.fieldName3   = ListFirst(arguments.fieldInfo[i], ",")>
        <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>
        <cfset variables.date_flag    = ListFirst(arguments.fieldInfo[i], ",")>
        <cfset arguments.fieldInfo[i] = ListDeleteAt(arguments.fieldInfo[i], 1, ",")>       
      </cfif>

      <!--- at this point, the error messsage is all that's left --->
      <cfset variables.errorMessage    = arguments.fieldInfo[i]>

     
      <!--- IF this field doesn't have an error already associated with it, error-check it --->
      <cfset variables.errorFound = false>
      <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
        <cfif ListContains(variables.errors[i], fieldName)>
          <cfset variables.errorFound = true>
        </cfif>
      </cfloop>

      <cfif NOT errorFound>
        <!--- if the requirement is LENGTH, rename requirement to "length" for switch statement --->
        <cfif Find("length=", variables.requirement)>
          <cfset variables.lengthRequirements = variables.requirement>
          <cfset variables.requirement = "length">
        </cfif>
       
        <!--- if the requirement is RANGE, rename requirement to "range" for switch statement --->
        <cfif Find("range=", variables.requirement)>
          <cfset variables.rangeRequirements = variables.requirement>
          <cfset variables.requirement = "range">
        </cfif>

       
        <!--- verify the field passes the required test --->
        <cfswitch expression="#variables.requirement#">

          <cfcase value="required">
            <cfif NOT StructKeyExists(arguments.pageAttributes, variables.fieldName) OR
              arguments.pageAttributes[variables.fieldName] EQ "">

              <!--- if this error message isn't already contained in "errors", add it --->
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                  <cfset variables.errorAlreadyExists = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>

            </cfif>
          </cfcase>

          <cfcase value="digits_only">
            <cfif REFind("[^[:digit:]]", arguments.pageAttributes[variables.fieldName])>
             
              <!--- if this error message isn't already contained in "errors", add it --->
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage)>
                  <cfset variables.errorAlreadyExists = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>

            </cfif>
          </cfcase>

          <cfcase value="length">
            <cfset variables.lengthRequirements = Replace(variables.lengthRequirements, "length=", "")>
            <cfset variables.lengths            = ListToArray(variables.lengthRequirements, "-")>
   
            <cfif ArrayLen(variables.lengths) IS 2>

              <!--- check field length is between specified length range --->
              <cfif (Len(arguments.pageAttributes[variables.fieldName]) LT variables.lengths[1]) OR
                  (Len(arguments.pageAttributes[variables.fieldName]) GT variables.lengths[2])>

                <!--- if this error message isn't already contained in "errors", add it --->
                <cfset variables.errorAlreadyExists = false>
                <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                  <cfif ListContains(variables.errors[i], variables.errorMessage)>
                    <cfset variables.errorAlreadyExists = true>
                  </cfif>
                </cfloop>
                <cfif NOT variables.errorAlreadyExists>
                  <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
                </cfif>
 
              </cfif>
           
            <cfelse>
              <!--- otherwise, the user wants the field contents to be a specific length --->
              <cfif Len(arguments.pageAttributes[fieldName]) NEQ variables.lengths[1]>

                <!--- if this error message isn't already contained in "errors", add it --->
                <cfset variables.errorAlreadyExists = false>
                <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                  <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                    <cfset variables.errorAlreadyExists = true>
                  </cfif>
                </cfloop>
                <cfif NOT variables.errorAlreadyExists>
                  <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
                </cfif>

              </cfif>             
            </cfif>
          </cfcase>
         
          <cfcase value="valid_email">
            <cfif NOT REFindNoCase("^['_a-z0-9-]+(\.['_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*\.(([a-z]{2,3})|(aero|coop|info|museum|name))$", arguments.pageAttributes[fieldName])>

              <!--- if this error message isn't already contained in "errors", add it --->
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                  <cfset variables.errorAlreadyExists = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>

            </cfif>
          </cfcase>

          <cfcase value="valid_date">
         
            <!--- included for future extensibility --->
            <cfif variables.date_flag EQ "later_date">
              <cfset variables.isLaterDate = true>
            <cfelse>
              <cfset variables.isLaterDate = false>             
            </cfif>

            <cfinvoke
             component="#request.componentPath#.Error"
             method="isValidDate"
             returnvariable="variables.isValid">
              <cfinvokeargument name="date_month" value="#arguments.pageAttributes[variables.fieldName]#"/>
              <cfinvokeargument name="date_day" value="#arguments.pageAttributes[variables.fieldName2]#"/>
              <cfinvokeargument name="date_year" value="#arguments.pageAttributes[variables.fieldName3]#"/>
              <cfinvokeargument name="isLaterDate" value="#variables.isLaterDate#"/>
            </cfinvoke>

            <!--- if this error message isn't already contained in "errors", add it --->
            <cfif NOT variables.isValid>
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                  <cfset variables.errorAlreadyExists = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>
            </cfif>
          </cfcase>

          <cfcase value="same_as">
            <cfif arguments.pageAttributes[fieldName] NEQ arguments.pageAttributes[fieldName2]>

              <!--- if this error message isn't already contained in "errors", add it --->
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                  <cfset variables.errorAlreadyExists = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>

            </cfif>
          </cfcase>

          <cfcase value="range">
            <cfset variables.rangeRequirements  = Replace(variables.rangeRequirements, "range=", "")>
            <cfset variables.range              = ListToArray(variables.rangeRequirements, "-")>   

            <!--- check field value is between specified number range ---> 
            <cfif (arguments.pageAttributes[variables.fieldName] LT variables.range[1]) OR
                (arguments.pageAttributes[variables.fieldName] GT variables.range[2])>

              <!--- if this error message isn't already contained in "errors", add it --->
              <cfset variables.errorAlreadyExists = false>
              <cfloop from="1" to="#ArrayLen(variables.errors)#" index="i">
                <cfif ListContains(variables.errors[i], variables.errorMessage) NEQ 0>
                  <cfset variables.errorFound = true>
                </cfif>
              </cfloop>
              <cfif NOT variables.errorAlreadyExists>
                <cfset ArrayAppend(variables.errors, variables.fieldName & "," & variables.errorMessage)>
              </cfif>

            </cfif>
          </cfcase>

          <cfdefaultcase>
            Unknown requirement in Error.validateFields: <b>#variables.requirement#</b>
            <cfabort>
          </cfdefaultcase>
        </cfswitch>

      </cfif>
    </cfloop>

    <!--- if there are validation errors, return attribute contents and error messages to referer page --->
    <cfif NOT ArrayIsEmpty(variables.errors)>

      <!--- convert the error message array into a wddx string in order to send it to form page --->
      <cfwddx action="cfml2wddx" input="#variables.errors#" output="variables.wddx_errorMessages" usetimezoneinfo="no">
      <cfwddx action="cfml2wddx" input="#arguments.pageAttributes#" output="variables.wddx_pageAttributes" usetimezoneinfo="no">

      <!--- store this information in a (temporary) session, then redirect. Note:
            this session info is destroyed once the user fills in the form correctly. --->     
      <cflock scope="session" type="Exclusive" timeout="20" throwontimeout="yes">
        <cfset session.wddx_errorMessages  = variables.wddx_errorMessages>
        <cfset session.wddx_pageAttributes = variables.wddx_pageAttributes>
      </cflock>

      <cflocation url="#CGI.HTTP_REFERER#" addtoken="no">
    </cfif>
  </cffunction>