Summary: The heart of the validate_form.js project, and the only file you need to import (via <SCRIPT SRC="...).

Function	Summary
loadVF	Starts the validate_form.js loading procedure, as completed by completeVFLoad().
completeVFLoad	Completes the validate_form.js loading procedure, as begun by the call to loadVF()
configVF	Configure the behavior of validate_form.js for a single form, to define the default cibc and debugging behavior.
configVFPD	Configure Permanent VF-Diagnostics, for when you choose to 'activate' it.
getFormErrorMsgs	Analyzes the values in the form for validity and returns the user error message in a format appropriate for an alert().
wrtVFPDToolbar	Activates Permanent VF-Diagnostics by displaying the vfpd-toolbar.
stAFLSvf	Provide an alternative array of FLStats to validate_form.getFormErrorMsgs().
gtAFLSvf	Get the FLStats array, for this form, currently used by getFormErrorMsgs() and dbgVF(), for analysis.
gtDUrl	Get the current url, perhaps with the vfp-diagnostics and cibc url parameters.
doSubmitOnSuccess	Should the form be submitted on success?

validate_form.js: Overview

The heart of the validate_form.js project, and the only file you need to import (via <SCRIPT SRC="...).

See the tutorials for implementation details.

TOP     validate_form.loadVF()

Starts the validate_form.js loading procedure, as completed by completeVFLoad().

Calling rules/sequence: This function must be called before any other functions in the validate_form.js project, and may only be called once. It must be accompanied by a call to completeVFLoad(), in the value of the body.onLoad attribute. After calling this function, you may then call configVF() and configVFPD().

PARAMETERS

Required parameters are detoned by '*'.

Name	Description	Values
s_jsDirUrl*	The base/relative url to the directory containing all validate_form.js code, including the final slash ('/'). This must be exactly the same as the path to validate_form.js, which is manually imported.	For example, if the webpage is at    http://www.mywebsite.com/webpages/mywebpage.html and the validate_form.js directory is    http://www.mywebsite.com/validate_form_js-___RPLC___ vfjs.version ___RPLCZ___ then this parameter should equal    ../validate form js-___RPLC___ vfjs.version ___RPLCZ___/
s_sifCfgUrl	The base/relative url from this webpage, to your SIFmt configuration file, defining your sif-attributes. If you have no sif-attributes, set this to undefined.	See s_jsDirUrl for a url example.
b_dbgJSLoads	Pop an alert() box for each JavaScript file loaded by the client? This can give you a sense of how much client download there is, depending on the validate_form.js features you use.	true: An alert box is launched each time a JavaScript file is loaded to memory. false: File loading is silent. When not provided, it defaults to false.

SIGNATURE

loadVF(s_jsDirUrl, s_sifCfgUrl, b_dbgJSLoads)

TOP     validate_form.completeVFLoad()

Completes the validate_form.js loading procedure, as begun by the call to loadVF()

Calling rules/sequence: It is required to call loadVF() and configVF() and this, in that order. completeVFLoad() may only be called once, and must be done in the value of the body.onLoad attribute (or at least, as the very last JavaScript line in your page).

SIGNATURE

completeVFLoad()

TOP     validate_form.configVF()

Configure the behavior of validate_form.js for a single form, to define the default cibc and debugging behavior.

Calling rules/sequence: The call to this function is required, must be after the call to loadVF(), and before the (optional) call to configVFPD(). configVF may only be called once per form.

PARAMETERS

Required parameters are detoned by '*'.

Name	Description	Values
sb_cibcOnOff*	Crash if bad vf-configuration? This value is the default used when Permanent VF-Diagnostics are off.	Value VF-Config Analyzed? Advantage Disadvantage CIBC_ON Yes In development, this is critical for diagnostics and sanity-confirmation. Larger client-download, as both vf_cibVFCfg.js and vf_obj_dgnstcs.js must be loaded. When "cibc" is on, you may notice a hesitation when submitting forms having more-than-a-few elements. Both vf_cibVFCfg.js and vf_dbgVF.js depend on vf_obj_dgnstcs.js. CIBC_OFF No In production, when you are positive there are no errors in your vf-configuration, you can minimize client-download, and maximize speed of response. If there are any problems with your vf-configuration, vf_gtUsrErrCnt.gtUsrErrCnt() will behave unpredictably.
i_dbgPerScreen*	The default value for the vf_dbgVF.dbgVF() parameter i_dbgPerScreen This value is the default used when Permanent VF-Diagnostics are off.	Must be a legal value as defined by vf_dbgVF.dbgVF(), although no error will be detected until this function is actually called. When this equals -1, debugging is not on, and vf_dbgVF.js and vf_obj_dgnstcs.js are not loaded, lowering your client download. Both vf_cibVFCfg.js and vf_dbgVF.js depend on vf_obj_dgnstcs.js.
s_formName	When provided, this is the name of the form to which this configuration refers.	When provided, this must be the name of an actually-existing form (starting with something other than 'form_vfpd__'). When this function is called multiple times, for multiple forms, it is required that this parameter be provided (defined), must be the name of an actually-existing form, and each call to configVF() must have a unique value for s_formName. In other words, this function, at a maximum, may only be called once per form.

SIGNATURE

configVF(sb_cibcOnOff, i_dfltDbgPerScr, s_formName)

TOP     validate_form.configVFPD()

Configure Permanent VF-Diagnostics, for when you choose to 'activate' it.

'Activating' pvf-diagnostics is done by calling wrtVFPDToolbar(). This must be called before wrtVFPDToolbar(). It is assumed, but not enforced, that wrtVFPDToolbar() is called somewhere in the body of your page.

Calling rules/sequence: The call to configVFPD() must come after the mandatory call to loadVF(), and after the optional call to configVF(). configVFPD() may only be called once per form.

Unless sb_on equals 'ON', calling this function does not load anything into memory. The call to both this function, as well as to wrtVFPDToolbar(), should remain in your web pages after production launch. This function is intended to be called right after loadVF(), to keep all validate_form.js configuration in one place, at the top of your HTML file.

Other notes...

Parameters

Required is denoted by '*'.

Name	Description	Values
sb_on*	Should pvf-diagnostics be on by default?	ON: The pvf-diagnostics toolbar is displayed immediately on page load Passing in the url parameter 'vfpd' turns pvf-diagnostics off. OFF: pvf-diagnostics are not displayed until the parameter 'vfpd' is passed into the url.
sb_cibcOnOff*	When vfp-diagnostics is on (displayed), crash if bad vf-configuration? This value is the default used when Permanent VF-Diagnostics are on. See the configVF() parameter of the same name, for details, legal values, and for cibc behavior when vfp-diagnostics are off.
sb_onLink*	When vfp-diagnostics are off, should a trivial 'on' link be displayed in its place? This is a convenience tool to pass the parameter 'vfpd' is passed into the url	ON_LNK: A turn-on-vfpd link is displayed when vfp-diagnostics are off. NO_ON_LNK: Nothing is displayed when vfp-diagnostics are off, which is necessary in production.
sb_offLink*	When vfp-diagnostics are on, should the 'off' link be displayed? This link hides the vfp-diagnostics toolbar.	OFF_LNK: The off link is displayed in the vfp-diagnostics are on. NO_OFF_LNK: The off link is not displayed.
sb_resetLink*	When vfp-diagnostics are on, should the 'reset' link be displayed? This link allows you to reset all vfp-diagnostic settings to their default values.	RESET_LNK: A turn-on-vfpd link is displayed when vfp-diagnostics are off. NO_RESET_LNK: Nothing is displayed when vfp-diagnostics are off, which is necessary in production.
sb_successDDB*	When vfp-diagnostics are on, should the 'on-successful-submit-action' drop-down be displayed? This drop-down allows you to decide if, upon successful submission, the form should be actually submitted, or if only an alert box should be displayed.	SUCCESS_DDB: The success ddb is displayed. NO_SUCCESS_DDB: The success ddb is not displayed. Recommended in production, to prevent bogus submissions.
sb_cibcSection*	When vfp-diagnostics are on, should the 'cibc' section be displayed? This section allows you to activate and deactivate vf_cibVFCfg.cibVFCfg(), to compare behavior.	CIBC_SCTN: The cibc section is displayed. NO_CIBC_SCTN: The cibc section is not displayed.
sb_cibcCrshDdb*	When vfp-diagnostics are on and the CIBC-Section is displayed, should the 'cibc-crash' drop-down be displayed? This allows you to change how a crash behaves (alert box? redisplay?).	CIBC_CRSH_DDB: The cibc-crash section is displayed. NO_CIBC_CRSH_DDB: The cibc-crash section is not displayed, and previously-existing values for utility.bCRSH_ALRT, bCRSH_DGNSTCS and bCRSH_THROW are used.
ai_dbgPerScrDDB	When defined, a drop-down box of these debugging-per-screen values is presented. The selected value is automatically--behind the scenes--communicated to vf_dbgVF.dbgVF().	Must be an array greater than zero elements in length, where all elements are defined and integers. Note that illegal values (such as -203) are okay, and will cause the expected 'vf.dvfjs1' developer error. Duplicate values are not illegal, but are not recommended. For example:   [6, 1, 2, 5, 7, 10, 20, 50] Note that the value of loadVF()-s parameter i_dbgPerScrDefault is always the first value and is SELECTED.
as_tstVFuncPosts	The postfix of the demo function names. Each demo function should set values for the entire form, although this is not a requirement. Each of the values in this array are the display names for the buttons.	Must be an array greater than zero elements in length, and every value must represent a function that actually exists ('vfpdtf__' + as_tstVFuncPosts[i] + '()') before wrtVFPDToolbar() is called. See the VFPD-dev tutorial for an example.
s_formName	When provided, this is the name of the form to which this configuration refers.	When provided, this must be the name of an actually-existing form (starting with something other than 'form_vfpd__'). When this function is called multiple times, for multiple forms, it is required that this parameter be provided (defined), must be the name of an actually-existing form, and each call to configVF() must have a unique value for s_formName (except for sDDB_DIVIDER, documented at the top of this page, which is ignored). In other words, this function, at a maximum, may only be called once per form.

BACK    Other notes regarding configVFPD()

• Recommended usage
  • In development::

       configVFPD("OFF", "CIBC_OFF", "ON_LINK", "OFF_LINK", "RESET_LINK", "SUCCESS_DDB", "NO_CIBC_SCTN", [appropriate_dbg_values], [appropriate_test_func_names]);

  • In production::

       configVFPD("OFF", "CIBC_OFF", "NO_ON_LINK", "OFF_LINK", "RESET_LINK", "NO_SUCCESS_DDB", "NO_CIBC_SCTN", [appropriate_dbg_values], [appropriate_test_func_names]);

• The prefix of the vfp-diagnostics form name (within the toolbar) is 'form_vfpd__'. The name of the form it is diagnosing is thet postfix. No form of yours (that is passed to the FLStats constructor) may start with this.
• window.location:
  • If the url (window.location.search) of the web page contains 'vfpd', then the value of sb_on is reversed (if originally 'ON', now 'OFF', and vice-versa).
  • If the url (window.location.search) of the web page contains 'load_cibc', then the value of sb_cibcOnOff is reversed (if originally 'CIBC_ON', now 'CIBC_OFF', and vice-versa).
• The prefix for demo-value function names is 'vfpdtf__'

SIGNATURE

configVFPD(sb_on, sb_cibcOnOff, sb_onLink, sb_offLink, sb_resetLink, sb_successDDB, sb_cibcSection, ai_dbgPerScrDDB, as_tstVFuncPosts, s_formName)

TOP     validate_form.getFormErrorMsgs()

Analyzes the values in the form for validity and returns the user error message in a format appropriate for an alert().

PARAMETERS

• f_orm: A reference to the form to be analyzed. REQUIRED.
• s_userErrPre: The text snippet to precede every user-error message line. For example, ' -- '. REQUIRED although it can be empty string. This is provided directly to [FLStats.]gtAFLSUsrErrs(), as the s_linePre parameter.
• b_crshAlert: In the case of an error (and only when crash_if.js is downloaded), should the crsh be displayed in an alert box? When provided, and when VFP-Diagnostics is on, this parameter overrides the value selected in the 'CRSH' drop down.
• b_crshDgnstcs: In the case of an error (and only when crash_if.js is downloaded), should the crsh be displayed in a 'redirect' page? When provided, and when VFP-Diagnostics is on, this parameter overrides the value selected in the 'CRSH' drop down.
• b_crshThrow: In the case of an error (and only when crash_if.js is downloaded), should the crsh be thrown to the JavaScirpt console? When provided, and when VFP-Diagnostics is on, this parameter overrides the value selected in the 'CRSH' drop down.

What this function does

1. If your f_orm's vf-configuration has not yet been analyzed, analyze it (compile it into an array of FLStats). Analysis occurs when either of these conditions are met:
   • gtAFLSvf() equals undefined.
   • The name of f_orm is different than the one previously analyzed. Specifically, (new FLStats(f_orm)).sNm != aFLStats[0].sNm)
2. Analyze the form's vf-configuration, and crash if any errors are detected. This is done with cibVFCfg(). This is only done when your the FLStats array is created.
3. Debug the form via alert() boxes, when i_dbgPerScreen (as provided to loadVF()) is defined and greater than zero.
4. Analyze the validity of your form's values, as provided by your form's users, and return all the errors in a formatted string, appropriate for alert()-ing. This is done with gtUsrErrCnt() and [FLStats.]gtAFLSUsrErrs().

SIGNATURE

getFormErrorMsgs(f_orm, s_userErrPre)

TOP     validate_form.wrtVFPDToolbar()

Activates Permanent VF-Diagnostics by displaying the vfpd-toolbar.

It is required that you call configVFPD() before calling this function, and that this call be outside of the form that you are diagnosing.

Note that the demo functions (the postfixes of which are represented by the configVFPD() parameter as_tstVFuncPosts) must actually exist by the point this function is called.

PARAMETERS

• s_nameLink: The 'name' link. When provided, this is the value returned after the hash ('#') in the 'OFF', 'RESET' and 'Load CIBC' links. When undefined, no name link is put in any url.
• s_formName: The name of the form to print the vfp-diagnostics toolbar for. If undefined, it is expected that configVF() and configVFPD() were called only once, and with no s_formName parameter.

SIGNATURE

wrtVFPDToolbar(s_nameLink, s_formName)

TOP     validate_form.stAFLSvf()

Provide an alternative array of FLStats to validate_form.getFormErrorMsgs().

Get with gtAFLSvf()

Normally, when gtAFLSvf('FORM_NAME') is undefined, validate_form.getFormErrorMsgs() analyzes your form, and generates an array of FLStats from it. When gtAFLSvf('FORM_NAME') is defined, then the array returned by it is used instead.

When    initVF() is called, it calls this function, for every existing form:

   stAFLSvf(undefined, 'FORM_NAME');

PARAMETERS

• a_flStats: The array of FLStats for validate_form.js to use. When defined, getFormErrorMsgs() uses it instead of analyzing the form. When undefined, getFormErrorMsgs() analyzes your form and generates an array of FLStats for itself.
• s_formName: The name of the form whose FLStats array you wish to get. If only one form exists on the page, this is ignored. Otherwise, this is required, and must be the name of an existing form.

SIGNATURE

stAFLSvf(a_flStats, s_formName)

TOP     validate_form.gtAFLSvf()

Get the FLStats array, for this form, currently used by getFormErrorMsgs() and dbgVF(), for analysis.

Set with stAFLSvf()

The postfix 'vf' is at the end of this function's name, to not confuse it with [fl_stats.]gtAFLS().

If this function returns undefined, then getFormErrorMsgs() analyzes the form, generates an array of FLStats from it, and sets that array into stAFLSvf().

PARAMETERS

• s_formName: The name of the form whose FLStats array you wish to get. If only one form exists on the page, this is ignored. Otherwise, this is required, and must be the name of an existing form. Use this function carefully, as it is not verified for validity.

RETURNS

• a_siFmt Exactly as provided to stAFLSvf().

SIGNATURE

gtAFLSvf(s_formName)

TOP     validate_form.gtDUrl()

Get the current url, perhaps with the vfp-diagnostics and cibc url parameters.

PARAMETERS

• b_vfpdP: Should the url parameter 'vfpd' be in the returned url? If true, then this parameter is preserved if already in window.location.search, and added if not. If false, then this parameter is deleted from window.location.search, should it be there.
• b_cibcP: Should the url parameter 'load_cibc' be in the returned url?
• b_resetLink: Is this the reset link? If true, then a random parameter is added to the url, to force a reload. Otherwise the link does nothing. If false, there is no parameter added.

RETURNS

Note that this returns a random extra parameter (starting with 'vfrndp_' and ending in four random numbers) in order to force a reload. Also, the hash (#name) is always returned.

For example... ([nothing] means false)

Original url	b_vfpdP	b_cibcP	Returned url
http://www.x.com/mypage.html			http://www.x.com/mypage.html
	true		http://www.x.com/mypage.html?vfpd
		true	http://www.x.com/mypage.html?load_cibc
	true	true	http://www.x.com/mypage.html?vfpd&load_cibc
http://www.x.com/mypage.html?vfpd			http://www.x.com/mypage.html
	true		http://www.x.com/mypage.html?vfpd
		true	http://www.x.com/mypage.html?load_cibc
	true	true	http://www.x.com/mypage.html?vfpd&load_cibc
http://www.x.com/mypage.html?load_cibc			http://www.x.com/mypage.html
	true		http://www.x.com/mypage.html?vfpd
		true	http://www.x.com/mypage.html?load_cibc
	true	true	http://www.x.com/mypage.html?load_cibc&vfpd
http://www.x.com/mypage.html?x=1&vfpd			http://www.x.com/mypage.html?x=1
	true		http://www.x.com/mypage.html?x=1&vfpd
		true	http://www.x.com/mypage.html?x=1&load_cibc
	true	true	http://www.x.com/mypage.html?x=1&vfpd&load_cibc
http://www.x.com/mypage.html?load_cibc&x=1			http://www.x.com/mypage.html?x=1
	true		http://www.x.com/mypage.html?x=1&vfpd
		true	http://www.x.com/mypage.html?load_cibc&x=1
	true	true	http://www.x.com/mypage.html?load_cibc&x=1&vfpd

SIGNATURE

gtDUrl(b_vfpdP, b_cibcP, b_resetLink)

TOP     validate_form.doSubmitOnSuccess()

Should the form be submitted on success?

'Success' is defined as when all values in the form are deemed proper, according to your vf-configuration.

PARAMETERS

• f_orm: The form that may or may not need to be submitted. REQUIRED

RETURNS

• true: when the form should be submitted. The form should be submitted when either of the following conditions are met:
  • VFP-Diagnostics are off
  • VFP-Diagnostics are on, and 'SBMT' is selected in the 'SUCCESS' drop-down.
• false: if VFP-Diagnostics are on, and 'alert' is selected in the 'SUCCESS' drop-down.

SIGNATURE