"qForm" Objects

In the properties and methods below, obj is an abbreviation for the object name you specified when you called the qForm constructor. Arguments in bracket ("[ ]") are optional.

Properties

obj._allowSubmitOnError
The _allowSubmitOnError property determines whether or not a user should be given the choice to submit a form even if errors occurred. 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 the value of qFormAPI.allowSubmitOnError.
obj._fields
The fields property contains an array of all the form elements that have been initialized into the qForms JSAPI.
obj._form
The form property contains the string pointer to the current form object. (Example: "document.frmExample".)
obj._locked
The locked property is used to prevent a form from being edited. Valid values are true or false. When set to true, all elements on the form are locked and cannot be edited. When set to false, then the form is not locked.
obj._name
The name of the current form being edited. This would be equal to the FORM tag's "NAME" attribute.
obj._queue.errorFields
The errorFields queue is list containing all the fields that contained an error. When the obj.fieldName.throwError() method is called, this property is checked to make sure an error for the current field hasn't already been thrown. This ensures that only one error per field will be generated.
obj._queue.errors
The errors queue is an array of all the validation errors that have occurred from running the "validate"-style validation methods.
obj._queue.validation
The validation queue is an array of all the validation checks that need to be performed.
obj._parent
A string containing the DOM path to form object. If form object is not in a layer on another frame, then the parent object is null.
obj._pointers
The pointers property is an associative array (or structure) that can be used as a pointer to the actual Field objects in the form. The keys for this structure are stored in lower case.
obj._showAlerts
The _showAlerts property determines whether or not alerts should be displayed by default. If set to true, then when applicable, the user will see alert() boxes describing the error that occurred. When set to false, the user will not be alerted and the errors will simply be return when the function is called. The default value is true.
NOTE: When set to false, the form will get submitted even if there were validation errors. This means in order to account for the errors, you'll need to manually trap them. You can use the obj.onSubmit event to dump the array of errors into a hidden form, or even save the errors in a WDDX packet.
obj._skipValidation
The _skipValidation property determines whether or not the validation rules should be enforced. By default, this value is set to false, which means any validation rules are enforced as normal. If set to true, then all validation rules will be skipped. This is useful if you want to save the form without running the validation rules.
obj._status
The current status of form object. If the status equals "submitting" then the form object is already been submitted and can not be submitted again when calling the obj.submit() method.
obj.obj
The obj property contains a pointer to the physical form object. This can be used if you ever need to access unsupported methods or properties of the form object.


Methods

obj.addEvent(string event, string command, [boolean append])
The addEvent method will dynamically attach the specified command to the requested form event.

The event argument is the name of the event to attach the command to. This is a required parameter.

The command argument is JavaScript code to attach to the event.

The append argument is an optional argument that accepts either the value true or false. If true, then the command will be attached to the end of any existing instructions already in the specified event. If false, then the event will be attached in front of any other instructions. The default value is true.

obj.addField(string field)
The addField method will dynamically attach a field to qForm object. This is useful when creating forms field using DHTML.

The field argument is required and should be equal to the field name of a field within the qForms form.

obj.addMethod(string name, object function, [string type])
The addMethod method will dynamically create a new method that can be used with the qForms API.

The name argument is the name of the new method to create. This is a required parameter.

The function argument is either a pointer to an existing function, or a string to which will be converted into the new method.

The type argument is an optional argument that accepts either the value "form" or "field". If the value "form" is passed, then the method created will be attached at the form object level, if "field" is passed, then the method will be attached at the field object level. The default value is "form."

obj.addValidator(string name, object/string function)
The addValidator method will dynamically initialize a new validation routine. When a new validator is created, two new methods are created: a validateXXXX() and an isXXXX() method (where XXXX is equal to the name argument.) The "validate" methods are used to initialize validation on the form. These type of methods return no value. The "is" methods will return true if no error occurred, or false if an error did occur.

The name argument is the base name of the new validation procedure. This is a required parameter.

The function argument is either a pointer to an existing function, or a string to which will be converted into the new method.

obj.changedFields()
The changedFields method returns a structure of only the fields that have changed. This very useful when combined with WDDX, because you'll have the ability to pass only the fields whose values have changed back to the server for updating.
obj.checkForErrors()
The checkForErrors method checks to make sure that all required fields have been filled in and then runs all the validation rules that have been initialized for the form object.

When the checkForErrors method is run, it will clear the existing error queue, and place any errors within the error queue array.

obj.disabled([boolean status])
The disabled method will disable all the elements on the form. This will prevent the user from being able to change any elements on the form. If the browser supports the HTML 4 "disabled" property, then the form is set to disabled, otherwise the custom qForm "locked" property is used. This provides for a cross browser compatible method of disabling a form.

The status arguement is an optional argument which allows you to specify whether the form should be disabled (true) or enabled (false.) By default, if no argument is given the status of the form's disabled status is toggled.

obj.dump()
The dump method will display all the current 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.
obj.forceValidation(string fields, [boolean value])
The forceValidation method allows you to perform a bulk property change to a list of field's "validate" property.

The fields argument is a list of field's whose "validate" property you'd like to change. This is a required parameter.

The value argument is an optional argument that accepts either the value true or false. The field's "validate" property will be set to the value of the value argument. The default value is true.

obj.hasChanged()
The hasChanged method returns true if any values in the current form have changed from the default values, otherwise it returns false.
obj.getFields()
The getFields method will return all the current form fields and their values as an associative array (also referred to as "structures.") The keys will be equal to the field name (in the same case as entered in the form field element) and the value of the key, will be equal to getValue() method of the field.
obj.optional(string fields)
The optional method allows you to perform a bulk property change on to list of field's "required" property.

The fields argument is a list of field's whose "required" property you'd like to set to false. This is a required parameter.

obj.onSubmit()
The onSubmit method contains a copy of the form's original "onSubmit" event and is run any time the form's submit() method is called and no validation errors occur. If the onSubmit() method returns a boolean value, this value will be supplied to the onSubmit event. This means if the obj.onSubmit() method returns false, then the form will not be submitted. If it returns no boolean value or true, the form will be submitted to the server.

You can also initialize an event to be processed by setting the onSubmit() method to a function. For example:

obj.onSubmit = functionName;
- or -
obj.onSubmit = new Function("// insert your commands here");

If using the above method, you must initialize the onSubmit after the qForms object has been initialized or an error will occur.

obj.onValidate()
The onValidate method is run when the validate() method is called. You can use the onValidate() method to define additional custom validation rules that don't necessarily comply to the standard validation methods.

For example, you could check to make sure that at least one field in the form has been filled in or even to make sure that field_A or field_B, but not both are filled in. To alert the user to errors, use the obj.fieldName.throwError() method. Let's take a look at a quick example:

function _customValidation(){
  if( obj.field_A.getValue() == "" && obj.field_B.getValue() == "" ){
    obj.field_A.throwError("You must supply a value for either field_A or field_B");
  }
}
obj.onValidate = _customValidation;
obj.removeField(string field)
The removeField method will dynamically remove a field from a qForm object. This is useful when creating forms field using DHTML.

The field argument is required and should be equal to the field name of a field within the qForms form.

NOTE: The removeField() method only works in browsers that support JavaScript v1.2. However, this method is really only useful when adding/removing nodes using DHTML which would require a browser with at least support for JavaScript v1.2.
obj.required(string fields, [boolean value])
The required method allows you to perform a bulk property change on to list of field's "required" property.

The fields argument is a list of field's whose "required" property you'd like to change. This is a required parameter.

The value argument is an optional argument that accepts either the value true or false. The field's "required" property will be set to the value of the value argument. The default value is true.

obj.reset([boolean hardReset])
The reset method will reset the all of the form's field 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.

obj.setFields(object struct, [boolean resetDefault], [boolean resetAll])
The setFields method will populate the form based upon a structure passed to it. The setFields method works well with WDDX, since you can easily deserialize a structure (or associative array) 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 form's values should be reset before updating the the fields with the values in the structure. By default this value is true, which means all the fields will be reset before populating the form with the value of the structures. If set to false, then only the fields specified in the structure will be changed.

obj.submit()
The submit method will run submit the current form object. The submit() method will set the status of the form to "submitting"—which will prevent the form from being submitted more then once. This replace the normal submit() method of a form.
obj.submitCheck()
The submitCheck method is run automatically each time the submit() method is called. This is an internal method used by the qForms API to determine whether or not the form should be submitted to the server. The following tasks are performed:

  • Cancels additional submit requests. This prevents multiple form submissions.
  • Runs the validation rules. If errors occur, a warning will be displayed to the user and the submit request is cancelled.
  • Runs the onSubmit() method if the form is error-free.
  • The returned value of the onSubmit() event is then checked. If a boolean value is returned, then the returned value is used to determine whether or not to continue the form submission request, otherwise the form is submitted to the server
obj.validate()
The validate method is called automatically when the form's onsubmit event occurs. This method runs the obj.checkForErrors() method to check for any errors. If any errors have occurred, they will be displayed to the user and (by default) the submit event will be cancelled.

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 >]