Summary: A wrapper for form objects (the form itself and elements therein).

Function	Summary
FLStats	Constructor: Create a new FLStats with the provided form/form-element, form-FLStats, and previous-array-of-FLStats.
gtAFLSUsrErrs	Accumulate all user form error messages into a single, alert()-ready string.
gtAFLS	Get an array of FLStats representing the provided form. Call this at form submission to analyze the form and create the aFLStats array based upon it.
pb_useThisFLS	After calling the cnstr (which analyzes an element or form), call this function to determine if this analysis resulted in an FLStats that should be regarded or discarded.
pb_gtCd4Attr	Get the code for the provided attribute on this form/element.
pb_gtCdAttrNm	Get the code for [this element].[provided attribute].
pb_gtCdFLSNm	Get the code for this FLStats' name.
pb_gtAttrVRaw	Get the value of the attribute, whether or not it is actually associated to the element.
pb_isAttrAssc2Lmnt	Has a certain attribute actually been associated to this element?
pb_gtAttrV	Get the value of the attribute, whether or not it is actually associated to the element.
pb_isLmntVal1OrMore	Is the value of this element single- or multiple-valued?
pb_gtLmntValSnglr	Get the singular value for this element.
pb_gtLmntOptsTotal	Get the number of total options in this multiple-value element. May only be called when isLmntVal1OrMore() returns false.
pb_gtLmntOptsChosen	Get the number of total options in this multiple-valued form element.
pb_gtEvlCdLmntAttrNm	Get the name of this object-plus-the-provided-attribute, suitable for 'eval'uation.
pb_gtEvlCdObjNm	Get the name of this object, suitable for 'eval'uation.

fl_stats.js: Overview

A wrapper for form objects (the form itself and elements therein).

Using FLStats

This class is automatically used by validate_form.js, so you don't need to directly use this object at all.

To create an array of FLStats for your form, try the following:

Local and public FLStats variables

Except for sUsrErr, all these variables are to be treated as read-only. Changing their values will result in unpredictable behavior. Attributes or functions not listed in this documentation should not be accessed.

• this.sNm: The name of the form object. If this.sType equals 'form', then this is the 'name' of the form (if provided) or "f_orm" (if no name is provided). Will never be undefined or empty string.
• this.sType: The type of the form object. Will equal one of the following: 'form', 'text', 'password', 'textarea', 'radio', 'select-one', 'checkbox', 'select-multiple'
• this.obj: A reference to the form object itself.
• this.sAftrFrmNm: Will equal either '.' or '[''. See gtEvlCdLmntAttrNm() and gtEvlCdObjNm() for how its used.
• this.sAftrAttrNm: Will equal either '' (empty string) or '']'. See gtEvlCdLmntAttrNm() and gtEvlCdObjNm() for how its used.
• this.iTotOpts: The total number of options in this multi-valued element. Will equal undefined when this element is single-valued.
• this.flsFrm: A pointer to the FLStats object representing the form in which this form element exists.
• this.sUsrErr: After calling validate_form.getFormErrorMsgs(), this is set to the user error message, if any should the value of this form element be unacceptable. If the value is acceptable, or getFormErrorMsgs() has not been called, this is undefined. This is the one variable which you can alter freely. It is not used anywhere else in the code.

When this.sType equals 'form', the following attributes will all be undefined: this.sAftrFrmNm, this.sAftrAttrNm, this.iTotOpts , this.sUsrErr and this.flsFrm

Notes

• f_* functions are internal to FLStats. pb_* functions are intended for public use. pv_* are not intended for public use.
• All boolean string values that are equal to "false" are *undefined* at the end of the constructor.

TOP     fl_stats.FLStats()

Constructor: Create a new FLStats with the provided form/form-element, form-FLStats, and previous-array-of-FLStats.

PARAMETERS

• frm_frmLmnt: The form or form element object to 'wrap'. REQUIRED and frm_frmLmnt.name must be both defined and at least one character in length.. If fls_frm is undefined, then this must be the form itself. When fls_frm is defined, this must be a form_element within that form. All form objects provided to this constructor may not have a name equal to any other form on the same page. Forms not provided to this constructor are not required to have a name--however, those having a name must have one not equal to any other provided to this constructor.
• a_prevFLS: The array of FLStats already analyzed in this form. Must be an array of FLStats where there is at least one element, and none are undefined. When fls_frm is undefined, this must also be undefined.

  This array may only include FLStats for form elements (no element may be the form itself). The purpose of providing this array is to ensure that checkbox sets and radio sets are analyzed as a whole, and not for each checkbox/radio element therein. This is required for validate_form.js to work properly.

DISCARED OR USE?

After using this cnstr, useThisFLS() must be called to determines if this FLStats is worthy of keeping, or should be discarded.

validate_form.js only handles certain types of form elements. For example, it does not handle hidden, button, submit or reset elements. Also, each checkbox/radio set (set of checkbox or radio elements) has a single FLStats, representing it as a whole. The second and subsequent checkbox/radio must be discarded for validate_form.js to work properly.

NOTE

• Any boolean string validate_form.js attributes (such as 'bsTrimSpaces') values set to 'false' are automatically reset (by this cnstr) to undefined. A 'false' boolean string attribue might as well not be defined at all. This simplifies the validate_form.js source code.

SIGNATURE

FLStats(frm_frmLmnt, fls_frm, a_prevFLS)

TOP     fl_stats.gtAFLSUsrErrs()

Accumulate all user form error messages into a single, alert()-ready string.

PARAMETERS

• All s_* parameters are REQUIRED, but may be empty string.
• a_flStats: The array of FLStats potentially containing user error messages (in sUsrErr). REQUIRED, must be a valid FLStats array, and at least one element must have a defined value for sUsrErr.
• s_header: The text to put at the top of the alert box.
• s_linePre: The text to put before each error line.
• s_footer: The text to put at the bottom of the alert box.

SIGNATURE

gtAFLSUsrErrs(a_flStats, s_header, s_linePre, s_footer)

TOP     fl_stats.gtAFLS()

Get an array of FLStats representing the provided form. Call this at form submission to analyze the form and create the aFLStats array based upon it.

PARAMETERS

• f_orm: The form to analyze. REQUIRED.

RETURNS

• An array of FLStats: This is in the same order as the elements are declared in your form. The form is at element zero. Checkbox sets and radio sets are represented as a single object, located in this array, at the point of the first first element in the set.

SIGNATURE

gtAFLS(f_orm)

TOP     fl_stats.pb_useThisFLS()

After calling the cnstr (which analyzes an element or form), call this function to determine if this analysis resulted in an FLStats that should be regarded or discarded.

If this returns true, then use the object you just created via the cnstr, otherwise discared it.

   var os = new FLStats(f_orm[i]);
      if(os.useThisFLS())  {
         //os should be kept.
      }  else  {
         //os should be discarded.
      }

Elements that should be discarded include:

• The second or subsequent element in a radio set or checkbox set.
• An element not recognized by validate_form.js: "button", "submit", "reset", "hidden", ...

NOTE: This function can only be called once per object.

SIGNATURE

useThisFLS()

TOP     fl_stats.pb_gtCd4Attr()

Get the code for the provided attribute on this form/element.

PARAMETERS

• s_attrNm: The name of the attribute whose code you want. Provided directly to both gtCdAttrNm() and gtAttrV().

RETURNS

• this.gtCdAttrNm(s_attrNm) + " = " + [util_string.]gtCd4V(this.gtAttrV(s_attrNm)) + ";\n"

SIGNATURE

gtCd4Attr(s_attrNm)

TOP     fl_stats.pb_gtCdAttrNm()

Get the code for [this element].[provided attribute].

To get the code for the value, call [util_string.]gtCd4V(this.gtAttrV(s_attrNm)).

PARAMETERS

• s_attrNm: The name of the attribute you want the code for. REQUIRED

RETURNS

• this.sNm + "." + s_attrNm when this.sType equals 'form'.
• this.flsFrm.sNm + this.sAftrFrmNm + this.sNm + "." + s_attrNm + this.sAftrAttrNm if otherwise.

SIGNATURE

gtCdAttrNm(s_attrNm)

TOP     fl_stats.pb_gtCdFLSNm()

Get the code for this FLStats' name.

PARAMETERS

• s_attrNm: The name of the attribute you want the name-code for. REQUIRED

RETURNS

• this.sNm when this.sType equals 'form'.
• this.flsFrm.sNm + this.sAftrFrmNm + this.sNm + this.sAftrAttrNm if otherwise.

SIGNATURE

gtCdFLSNm()

TOP     fl_stats.pb_gtAttrVRaw()

Get the value of the attribute, whether or not it is actually associated to the element.

PARAMETERS

• s_attrNm: The name of the attribute whose value you want. REQUIRED

RETURNS

• eval(this.gtEvlCdLmntAttrNm(s_attrNm))

SIGNATURE

gtAttrVRaw(s_attrNm)

TOP     fl_stats.pb_isAttrAssc2Lmnt()

Has a certain attribute actually been associated to this element?

PARAMETERS

• s_attrNm: The name of the attribute to analyze for. REQUIRED

RETURNS

• [utility.]df(this.gtAttrVRaw(s_attrNm))

SIGNATURE

isAttrAssc2Lmnt(s_attrNm)

TOP     fl_stats.pb_gtAttrV()

Get the value of the attribute, whether or not it is actually associated to the element.

PARAMETERS

• s_attrNm: The name of the attribute whose value you want. REQUIRED and this attribute must be (a) actually be associated to this element, and (b) be one of the following :
  • sMsgFmt*
  • sMsgRequired
  • sMsgTxtDec
    • dDecMin
    • dDecMax
  • sMsgTxtEmail
  • sMsgTxtInt
    • iIntMin
    • iIntMax
  • sMsgBadLength
    • iMinLength
    • iMaxLength
  • sMsgMCRange
    • iMCMin
    • iMCMax
  • asGlobalBadSubStrs
  • bsNoBadSubStrs
  • asBadSubStrs
  • sMsgBadSubStr
  • bsGlobalTrimSpaces
  • bsDontTrimSpaces
  • bsTrimSpaces
  • The standard HTML MAXLENGTH text attribute.

RETURNS

• this.gtAttrVRaw(s_attrNm)

SIGNATURE

gtAttrV(s_attrNm)

TOP     fl_stats.pb_isLmntVal1OrMore()

Is the value of this element single- or multiple-valued?

RETURNS

• (![util_string.]df(this.iTotOpts))

SIGNATURE

isLmntVal1OrMore()

TOP     fl_stats.pb_gtLmntValSnglr()

Get the singular value for this element.

Always use this function to get the value, although you must set the value manually, via the object, obj.

May only be called when isLmntVal1OrMore() returns true.

SIGNATURE

gtLmntValSnglr()

TOP     fl_stats.pb_gtLmntOptsTotal()

Get the number of total options in this multiple-value element. May only be called when isLmntVal1OrMore() returns false.

SIGNATURE

gtLmntOptsTotal()

TOP     fl_stats.pb_gtLmntOptsChosen()

Get the number of total options in this multiple-valued form element.

This may only be called when this.sType equals something other than 'form', and isLmntVal1OrMore() is false.

SIGNATURE

gtLmntOptsChosen()

TOP     fl_stats.pb_gtEvlCdLmntAttrNm()

Get the name of this object-plus-the-provided-attribute, suitable for 'eval'uation.

PARAMETERS

• s_attrNm: The name of the attribute whose eval-code you want. REQUIRED and must be associated to this element.

RETURNS

• 'document.' + this.sNm + '.' + s_attrNm when this.sType equals 'form'
• 'document.' + this.flsFrm.sNm + this.sAftrFrmNm + this.sNm + '.' + s_attrNm + this.sAftrAttrNm if otherwise.

SIGNATURE

gtEvlCdLmntAttrNm(s_attrNm)

TOP     fl_stats.pb_gtEvlCdObjNm()

Get the name of this object, suitable for 'eval'uation.

RETURNS

• 'document.' + this.sNm when this.sType equals 'form'
• 'document.' + this.flsFrm.sNm + this.sAftrFrmNm + this.sNm + this.sAftrAttrNm if otherwise.

SIGNATURE

gtEvlCdObjNm()