Using The qForms API
Using the qForm API is very easy. As you've already seen, setting your forms for the API is quite simple. There are only a few key points you need to remember:
- You must load the qforms.js library file before trying to using the qForm() constructor
- You must specify the NAME attribute in your
<FORM>tags - You must call the qForm() constructor after the browser has parsed the
ending
</FORM> - The qFormAPI.include() methods must be processed befored trying to use any of the extended library methods
Remembering these simple points will avoid the most common problems developers experience when first trying to use the qForms API.
The Basics
Before you're able to use the methods of the qForms API, you'll have to initialize a new qForm's
object. You do this by using the qForm() constructor.
objForm = new qForm("frmExample");In the above example, we've creating a new global JavaScript object called "objForm." This
object can be accessed from anywhere within our document. Passing the string "frmExample"
indicates we have a <FORM> tag in our document that has the name
of "frmExample".
If the form was inside another layer, we'd have to specify the layer in which the form resided in—this is because Netscape v4.x considers layers as part of a new document. For example, if we had a form called "frmExample" inside a layer with the ID of "idForm", we'd initialize the form using the following syntax:
objForm = new qForm("frmExample", "document.idForm");After initializing the form, you'll be able to retrieve and set your form field variables using the getValue() and setValue() methods. For example, to display the value of a multi-select box named "MenuItem", you'd do the following:
alert(objForm.MenuItem.getValue());This would display the value of all the items selected within the MenuItem select box. If you needed to programmatically change the value of the select boxes, you can use the setValue() method. For example, if two of the values in the select box were "Home" and "Products", we could set the value of the MenuItems by simply calling:
objForm.MenuItem.setValue("Home,Products");This would make sure that both the "Home" and "Products" listings were selected in the select box.
For a complete listing of properties and methods, see the The Core API page. It's also recommend to review the Examples area for sample code.
Accessing Native Form Objects
Although the qForms API will replace almost every need to access individual form field
objects, you may still find circumstances where it's necessary. To accomplish this,
the API creates pointers to both the form and field objects. This special property is the
"obj" property. For example, from time to time you'll find you need to change the
page that the current form is posting to, depending on the value of a certain variable.
To do this, you'll need to update the form's "action" property. Using the qForm's "obj" property
of the form object, you'll have easy access to change the "action" property. For example:
if( objForm.Action.getValue() == "Edit" ){
objForm.obj.action = "edit.cgi";
} else if( objForm.Action.getValue() == "Delete" ){
objForm.obj.action = "delete.cgi";
}
This would check the value of the field "Action" and change the form's action statement—the page which the data will be posted to—based upon the value found in the field.
The "obj" property is created for both form objects and field objects. The syntax is as follows:
Form Properties
objForm.obj.action
objForm.obj.elements
objForm.obj.encoding
objForm.obj.length
objForm.obj.method
objForm.obj.target
Field Properties
objForm.fieldName.obj.checked
objForm.fieldName.obj.defaultChecked
objForm.fieldName.obj.defaultValue
objForm.fieldName.obj.length
objForm.fieldName.obj.name
objForm.fieldName.obj.options
objForm.fieldName.obj.selectedIndex
objForm.fieldName.obj.type
objForm.fieldName.obj.value
These properties will work exactly as they would if you called them using the document.form[x] syntax.
