In the properties and methods below, obj is an abbreviation for
the object name you specified when you called the qForm constructor.
fieldName signifies the form field element that you want
to perform the action on. Arguments in bracket ("[ ]") are optional.
The dependencies property is an array containing all of the dependency events that need
to be processed. Dependencies are used to create a relationship between fields. (For
objForm.LastName.createDependencyTo("FirstName") says that the
field LastName is only required if the field FirstName is populated with a value.)
The validation property is an array containing all of the validation events that need
to be processed during the onBlur event if the validate property is set to true. The
validation queue is generated automatically when the validate-style method is called.
The container property is special property for use with select box elements. If the
container property is set to true then all items in the select box are consider part
of the valuenot just the selected items, which is the default behavior for a form
field. If set to false then the select box is treated like a normal select box and
only the selected items are used to determine the value. The default value is false.
The defaultValue property is default value of the selected form field element.
The description property holds a description for the current field. By default the description
is equal to the lower case value of the field name. The description property can be set any
time after the qForms object has been initialized. This property is used to describe the
current form field for when the user has to be notified about an error.
The name property is name of the current form field element.
The lastValue property contains the previous value of the current form field element. If
the value has never been changed, then it will be equal to the defaultValue property.
The locked property is used to prevent a form field from being edited. Valid values
are true or false. When set to true, the elements is locked and cannot be edited.
When set to false, then the field is not locked.
The obj property contains a pointer to the physical form field element. This can be
used if you ever need to access unsupported methods or properties of the form field element.
The path property is a string representing the path to the current form field
element. (For example:
The pointer property is a string containing the qFormAPI pointer.
The qForm property is a pointer to the qForm that the current Field object
current belongs too.
The required property defines whether or not a field is required in order for the form to
This allows you to override the default message that's presented
when a field is required (normally: "The " + obj.fieldName.description + " field is required.")
NOTE: To insert quotes in the string, you must use
\\\". This will properly escape the
quote for use in the string; otherwise a JS error may occur.
obj.fieldName.requiredMessage = "This is a \\\"required\\\" message with quotes.";
This would display as:
This is a "required" message with quotes.
The type property defines the selected field element's type.
The validate property defines whether or not a field should be validate when the focus
is removed from the form field element. This property is only used when the validation
methods are initialized, so this is a runtime only property. Once the validation method
has been initialized, the value of this property is no longer referenced.
- obj.fieldName.addEvent(string event, string command, [boolean append])
The addEvent method will dynamically attach the specified command to the requested
The event argument is the name of the event to attach the command to. This is a
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.
The allowFocus method is run each time a form field receives focus. This method handles
several things. If the style on the form field has been changed due to a validation
error, the style change is undone. It also check to see if the field is locked, if
so, then an error message is displayed and focus is removed from the form field.
If the field receives focus, then the obj.fieldName.onFocus() method is invoke,
along with any other commands attached to the event handler.
The blur method will put the remove focus from the selected form field element.
- obj.fieldName.checkIfLocked([boolean showMsg])
The checkIfLocked method is called each time a form field receives focus. If the field is
locked, then by default a message is displayed to the user and focus is removed from the form
If parameter showMsg is optional and when set to true a message alerting the user to the
fact that field is disabled will appear and the focus will be removed from the form field.
If set to false, then no message will be displayed and false will be returned if the field
is locked and true will be returned if the field is unlocked. The default value is true.
The checkForErrors method is called each time a form field loses focus. If the field's
validate property is set to true, then any validation methods queued will be executed.
The first error that occurs will be thrown to the screen and the focus will be returned
to the form element. If no errors occur then onBlur event will continue normally.
The click method will call the field's onclick event.
- obj.fieldName.disabled([boolean status])
The disabled method will disable the selected form element. This will prevent the user from
being able to change the value of the element. If the browser supports the HTML 4 "disabled"
property, then the field is set to disabled, otherwise the custom qForm "locked" property is
used. This provides for a cross browser compatible method of disabling a form field.
The status arguement is an optional argument which allows you to specify whether the
field should be disabled (true) or enabled (false.) By default, if no argument is given
the status of the form field's disabled status is toggled.
The focus method will put the focus on the selected form field element.
The getValue method will return the current value for the selected form field element.
The getValue method will return the current value of any form field element. If the
selected element can have multiple items selected or checked, then multiple values will
be comma delimitedjust as they would appear when submitted to the server.
The isDisabled method returns true if the current field's "disabled" property or if the
form's "disabled" property is set to true, otherwise the method returns false.
The isLocked method returns true if the current field's "locked" property or if the
form's "locked" property is set to true, otherwise the method returns false.
The onFocus method is run each time the obj.fieldName.allowFocus() method is true.
You can attach your own function to this event which will be processed each time
a field receives focus.
The onSetValue method is run each time the obj.fieldName.setValue() method is run. Use
this function to define a custom function to run for a specific field when the setValue
method is run.
The reset method will reset the value of the current form field to its default value.
The select method will select the text in a text or textarea form field.
- obj.fieldName.setValue(string value, [boolean reset], [boolean doEvents])
The setValue method will set the selected form field's value equal to that of the
"value" argument. If you wish to completely wipe any value from the selected form field,
pass the value null. The setValue method will also trigger the onChange event
for the form field if the value was changed. The setValue method works for any form field element.
NOTE: The setValue() simply configures each form field so that when
the information is sent back to the server, the value the server sees is equal to
"value" argument. For example, if you have series of checkboxes that share the same
name attribute, then qForms will compare the value attribute of each input tag
and set the "checked" property of the field to true if the value is the list
of values passed to the setValue() method.
If the optional argument "reset" is set to true, then the current value will be
erased, and the value of the field will be replaced with the provided value. If set
to false, then the provided value will be appended to the current value. This works
only on form elements that can have multiple options selected or checked. The default
value is true.
If the optional argument "doEvents" is set to true, then after the value for the
field is updated, the field's "onblur" and "onchange" event handlers will be executed. If set
to false the event will not be executed. The default value is true.
- obj.fieldName.throwError(string error)
The throwError method is used to generated a validation error when the form is submitted.
If the error parameter is a valid string, then that message will be added to the
obj._queue.error array, which is displayed if any errors occurred when the obj.validate()
- obj.fieldName.triggerEvent(string event)
The triggerEvent method is used to trigger one of the form fields event. The string
argument is required and should be equal a valid event for the field.
- obj.fieldName.validateExp(string expression, [string error], [string command])
The validateExp method is used to create simple expression validation. You can use the
validateExp() method easily verify that a particular field is equal to a certain value,
or to make sure that a field contains at least X number of characters. The validateExp()
behaves just like all "validate" style validation methods.
The expression argument is a required parameter and is the expression used to determine
whether or not to throw an error. An expression is any valid string that when evaluated
returns true or false. If the expression returns true an error
will be thrown. For example, the expression "
this.getValue().length > 4" when
evaluate would return true if the value of the field was greater then 4 and false if was
less then or equal to 4.
The error argument is the message to be displayed should the expression return true.
By default a generic message is displayed that tells you what field the error occurred in.
The command argument is an optional parameter used to specify a command to append to
the validation method when it is called. This can be used to call another function or to
simply set the value of a variable.