Availability

JavaScript 1.0 Inherits from HTMLElement

Synopsis

document.form_name 
document.forms[form_number]

Properties

Form inherits properties from HTMLElement and defines or overrides the following:

action

A read/write string (read-only in IE 3) that specifies the URL to which the form data is sent when the form is submitted. The initial value of this property is specified by the action attribute of the <form> HTML tag. Usually, this URL specifies the address as a CGI script, although it can also be a mailto: or news: address.

elements[]

An array of input elements that appear in the form. Each element is a Button, Checkbox, Hidden, Password, Radio, Reset, Select, Submit, Text, or Textarea object. See the Form.elements[] reference page.

encoding

A read/write string (read-only in IE 3) that specifies how form data is encoded for transmission when the form is submitted. The initial value of this property is specified by the enctype attribute of the <form> tag. The default value is "application/x-www-form-urlencoded", which is sufficient for almost all purposes. Other values may sometimes be necessary. For example, a value of "text/plain" is convenient when the form is submitted by email to a mailto: URL. See CGI Programming on the World Wide Web, by Shishir Gundavaram (O'Reilly), for further information.

length

The number of elements in the form. Equivalent to elements.length.

method

A read/write string (read-only in IE 3) that specifies the method by which form data is submitted. The initial value of this property is specified by the method attribute of the <form> tag. The two legal values are get and post.

The get method is the default. It is usually used for form submissions such as database queries that do not have side effects. With this method, the encoded form data is appended to the URL specified by the Form.action property. The post method is appropriate for form submissions, such as additions to databases, that have side effects. With this method, encoded form data is sent in the body of the HTTP request.

name

Specifies the name of the form. The initial value of this read/write string property is the value of the name attribute of the <form> tag.

target

A read/write string that specifies the name of the frame or window in which the results of submitting a form should be displayed. Initially specified by the target attribute. The special names "_top", "_parent", "_self", and "_blank" are also supported for the target property and the target attribute. See the Form.target reference page.

Methods

Form inherits methods from HTMLElement and defines the following:

reset( )

Resets each of the input elements of the form to their default values.

submit( )

Submits the form.

Event Handlers

Form inherits event handlers from HTMLElement and defines the following:

onreset

Invoked just before the elements of the form are reset. Specified in HTML by the onreset attribute.

onsubmit

Invoked just before the form is submitted. Specified in HTML by the onsubmit attribute. This event handler allows form entries to be validated before being submitted.

HTML Syntax

A Form object is created with a standard HTML <form> tag. The form contains any input elements created with the <input>, <select>, and <textarea> tags between <form> and </form>:

<form
    [ name="form_name" ]       // Used to name the form in JavaScript
    [ target="window_name" ]   // The name of the window for responses
    [ action="url" ]           // The URL to which the form is submitted
    [ method=("get"|"post") ]  // The method of form submission
    [ enctype="encoding" ]     // How the form data is encoded
    [ onreset="handler" ]      // A handler invoked when form is reset
    [ onsubmit="handler" ]     // A handler invoked when form is submitted
>
// Form text and input elements go here
</form> 

Description

The Form object represents an HTML <form> in a document. Each form in a document is represented as an element of the Document.forms[] array. Named forms are also represented by the form_name property of their document, where form_name is the name specified in the name attribute of the <form> tag.

The elements of a form (buttons, input fields, checkboxes, and so on) are collected in the Form.elements[] array. Named elements, like named forms, can also be referenced directly by name -- the element name is used as a property name of the Form object. Thus, to refer to a Text object element named phone within a form named questionnaire, you might use the JavaScript expression:

document.questionnaire.phone

See Also

Button, Checkbox, FileUpload, Hidden, Input, Password, Radio, Reset, Select, Submit, Text, Textarea; Chapter 15; HTMLFormElement in the DOM reference section