The Form object is an indexed array containing information about any forms present in the document. As a form is made up of distinct form elements, the Form element is the parent of those respective elements (i.e. buttons, checkboxes, text boxes etc.)
| Properties | Methods | Events |
| action, elements, encoding, FileUpload*, length, method, target | submit, reset | OnSubmit, OnReset |
NOTE : The following form objects are also properties of the larger Form object. For more details on the properties of these objects, see the Element Object : button, checkbox, hidden, password, radio, reset, select, submit, text, textarea.
Forms are generally accessed through the forms array (a property of the Document Object), but can also be accessed by any provided NAME attribute.
document.forms(0).property
document.egForm.property
document.form.property
would reference the first form (if there are more than one forms), the form named egForm and the only form (assuming there is only one). (Note that if a document contains only one form, then forms(0) and form are identical.)
Form Properties
action
The action property can be used to determine, or set the action of the form when it is submitted. As such it reflects any ACTION attribute settings in the <FORM> element. Typically, this would be a URL, giving some kind of server side script.
vAction=document.forms(1).action
would set the value of vAction to the ACTION of the documents second form.
elements
The elements property is actually an object containing an indexed array of all the forms elements (i.e. anything in the form included by standard form elements. Internet Explorer also includes any embedded <OBJECT>s within a form as elements). It has the properties length (to return the number of elements in the form) and name to return the name of a particular element, referrenced by its index in the elements array property. For example :
document.forms(0).elements.length
returns the number of elements in the documents first form, while :
vName=document.forms(0).elements(3).name
sets vName to the name of the first forms fourth element.
For more information on the particular form element properties and methods, see the Element Object
encoding
The encoding property can be used to determine, or set the value of the forms ENCTYPE attribute. This is normally set to the MIME type for the information that will be transmitted with the form (i.e. for text - 'text/plain', for HTML - 'text/html').
vEnc=document.forms(0).encoding
sets vEnc to the first form's ENCTYPE attribute.
FileUpload
This Netscape specific property is actually an object that is created, if a form is set for allowing file upload (i.e. <INPUT TYPE="file" NAME="name_for_file">). It has two properties, name and value reflecting the NAME attribute and the name of the uploaded file respectively. (all form elements are sent as a name/value pair, for processing). For example, assume a form contains :
<INPUT TYPE="file" VALUE="vUplFile">
vName=document.forms(0).vUplFile.name
vValue=document.forms(0).vUplFile.value
The variable vName will be set as the name (i.e. vUplFile) and vValue will be set to the value of the element (i.e. the path and name of the file to be uploaded).
length
The length property is a read-only property that reflects the number of forms in a document. I.e.
vNum=document.forms.length
Note that the length property is also a property of the elements property (and object) and could also be used to determine for example, the number of available options in a select box (see the Element Object for more information.)
method
The method property reflects, or can be used to set, the forms METHOD attribute. This determines the method of transmission for the form data. For more information, see the <FORM> element.
target
This property reflects (or sets) the TARGET attribute of the <FORM> element, which defines which frame or browser window, the results of the form processing (if any) will be displayed in.
document.forms(0).target="FormWindow"
would set the documents first form to display it's results in the window titled FormWindow.
Form Methods
Submit
The submit method forces submission of the form, sending all form data to the destination specified by the METHOD attribute of the <FORM> element (or method property of the form object). It is essentially identical to the user pressing the Submit button (assuming one is provided).
Reset
The reset method resets all the form data to the default values, as if it had been re-loaded. It is essentially identical to the user pressing the Reset button.
OnSubmit
The OnSubit event can be used to execute script functions prior to the form being submitted. Note that if you use this event, you must manually script submission of the form. It is useful for calling a form data validation function, to check the user has entered sensible data before transmitting the data for processing. (Note that the same effect can also be achieved by calling the same validation function using the submit buttons OnClick event). For example, assume you have a form named egForm
egForm.OnSubmit=validate_form()
would execute the script function validate_form() when the Submit button is pressed.
OnReset
The OnReset event can be used to execute a script function when the users presses the Reset button. Note that this can also be done by using the OnClick event with the reset button.