The "qFormAPI" Object
The allowSubmitOnError property is a global property which determines whether or not a user
should be given the choice to submit a form even if errors occurred. This is used as the default
value for all initialized qForm objects. If set to true, the user be given the
choice to submit the data without correcting the errors. When set to false, the form
will not be submitted until all the errors are corrected. The default value is false.
The autodetect property is a boolean value which determines whether or not the qFormAPI
The default value for this is true. If set to false, then browser will
load the default versions of the librarieswhich are written to work with
The containers property is a read-only structure containing copies of the original options' array
of any select box declared as a container. When the setValue() method is called on a
container, then the original options array and all bound containers are parsed to finding
a matching key. If a match is found, then the array item is copied to that container.
The customValidators property is a read-only integer value containing the total number of custom
validators intialized with the current form. Custom validators are validators that have
been initalized using the validateExp() method.
The errorColor property is a string value containing the color to use when changing the
background style of form fields if an error occurs. The default value is "red".
The jsver property is a read-only object that is used by the API when loading
extension modules. By referencing qFormAPI.jsver[_jsver] you'll receive a string
NOTE: _jsver is a global variable which indicates the highest
integer, where the value is the version of JS multipled by 10. (Example: "12"
The librarypath property is a string value containing the path to the qForm extension
libraries. This property is updated via the qFormAPI.setLibraryPath() method.
The modules property is an array containing the default libraries to load when the
qFormAPI.include("*") method is called. By default this loads the "functions",
"field" and "validation" libraries.
The objects property is a read-only structure containing pointers to all of the
initialized qForm objects that have been created. This is used internall by the
qForms API when creating external events to the qForm objects.
The packages property is read-only structure containing a list of external libraries
that have already been initialized. This prevents multiple libraries from being
The resetOnInit property contains a boolean value which states whether or not the
forms on the page should have their values reset on page load. By default the value
The showStatusMsgs property is a boolean property which indicates whether
or not messages should be supplied to the status bar. By default, this
property is set to true. To disable messages from appearing in the
status bar, simply set this property to false when initializing
the qForms API. Disabling this property would prevent the initialization
messages from appearing in the status bar when a validation method is
The styleAttribute property is a string property which you can use
to define what single CSS style property should be changed when an
error is thrown to the field. The default value is "backgroundColor".
This is an experimental propertyuse at your own risk. It
is highly recommend to check the results in multiple browsers
if you change this property.
The useErrorColorCoding property contains a boolean value which determines whether
or not the background style should change when the validate() method determines
a validation rule has failed. Style changes will only work in browsers that support
this featurethis feature does not work in Netscape v4.0 or lower. The default
value for this property is true.
The validateAll property is a boolean value which states whether or not all qForm
objects should be validate when any single qForm object is submitted. You may wish
to set this value to true when dealing with forms on multiple layers, where
the value is copied to a single form, but the validation methods are set on the
individual form fields. The default value is false.
The dump method will display all the qForm object form field names and their values in an alert box.
This is useful for debugging your forms to makes sure that the values you're expecting are
- qFormAPI.include(string src, [string path], [string ver])
The include method allows you to load external library files. The include method is used
to load the validation methods and extension field methods.
The src argument is a required parameter which specifies which library you'd like to load.
The src parameter should be equal to the base file name of the extension library. For example,
to load the validation.js file, you'd pass in the string "validation". The src parameter also
takes a special string of "*" which will load all the default libraries stored in the
The path argument is an optional argument which specifies a path other then the default
path in which the library file is located. The default path is the value of
the request library has been written for. The qForms API allows you to write multiple versions
The getFields method will return a structure containing the form fields from all of the
qForm initialized objects. This is useful when dealing with multi-layered forms.
- qFormAPI.reset([boolean hardReset])
The reset method will reset all qForm object fields to their default values.
The hardReset argument is an optional boolean value which specifies whether or not
all values should be set to nullregardless of their default values. The default
value is false, which restore the fields to their default values.
- qFormAPI.setFields(object struct, [boolean resetDefault], [boolean resetAll])
The setFields method will populate all of the qForm objects based upon the structure passed to it.
The setFields method works well with WDDX, since you can easily deserialize a structure
and pass the variable to the setFields structure. Keys in the structure that have no corresponding
form fields will be ignored. The keys in the structure do not need to be in the same case as the
form field names.
The setFields method also takes an additional argument "resetDefault" which, when set to true,
resets the default values in the form to the given structure. The default value is false, which
simply changes the values of the fields found in the structure.
The "resetAll" arguement determines whether the field values should be reset before updating
their values in the structure. By default this value is true, which means
all the fields will be reset before updating their values from the structures. If set to
false, then only the fields specified in the structure will be changed.
- qFormAPI.setLibraryPath(string path)
The setLibraryPath method is used to set the correct path to the qForm extensions libraries.
The argument path is a required string parameter which contains the path to the
extension libraries subdirectory. This value is then checked for syntax and stored witin
the qFormAPI.librarypath property.
- qFormAPI.validate(string qForm)
The validate method is called automatically when the form's onsubmit event occurs. This
method actual calls individual form's validate() method.
The qForm argument is a string parameter containing the value of qForm's _name property.
This argument is used to run the validate method for that qForm object.
If the form's _allowSubmitOnError is false, then the user will be forced to correct
any errors before being allowed to submit the form. If the option is set to true, the
user will be given the choice of correcting their errors, or submitting the form as is.