The "qFormAPI" Object Properties qFormAPI.allowSubmitOnError 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. qFormAPI.autodetect The autodetect property is a boolean value which determines whether or not the qFormAPI should load the best version of JavaScript libraries based upon the client's browser. The default value for this is true. If set to false, then browser will load the default versions of the libraries—which are written to work with JavaScript v1.1. qFormAPI.containers 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. qFormAPI.customValidators 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. qFormAPI.errorColor 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". qFormAPI.jsver 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 containing the highest version of JavaScript support by the current browser. NOTE: _jsver is a global variable which indicates the highest level of JavaScript supported by the browser. The variable will contain a two-digit integer, where the value is the version of JS multipled by 10. (Example: "12" would be equal to JavaScript v1.2. qFormAPI.librarypath The librarypath property is a string value containing the path to the qForm extension libraries. This property is updated via the qFormAPI.setLibraryPath() method. qFormAPI.modules 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. qFormAPI.objects 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. qFormAPI.packages The packages property is read-only structure containing a list of external libraries that have already been initialized. This prevents multiple libraries from being loaded. qFormAPI.resetOnInit 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 is false. qFormAPI.showStatusMsgs 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 being registered. qFormAPI.styleAttribute 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". NOTE: This is an experimental property—use at your own risk. It is highly recommend to check the results in multiple browsers if you change this property. qFormAPI.useErrorColorCoding 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 feature—this feature does not work in Netscape v4.0 or lower. The default value for this property is true. qFormAPI.validateAll 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. Methods qFormAPI.dump() 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 being returned. 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 qFormAPI.module array. 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 qFormAPI.librarypath. The ver argument is an optional parameter which specifies the maximum version of JavaScript the request library has been written for. The qForms API allows you to write multiple versions of the same library to leverage newer versions of JavaScript. qFormAPI.getFields() 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 null—regardless 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. [< Back] [Index] [Next >]