Table of Contents | Previous | Next | Index

# Form

Lets users input text and make choices from `Form` elements such as checkboxes, radio buttons, and selection lists. You can also use a form to post data to a server.

Client-side object |
Implemented in | JavaScript 1.0 JavaScript 1.1: added `reset` method. JavaScript 1.2: added `handleEvent` method.

#### Created by

The HTML `FORM` tag. The JavaScript runtime engine creates a `Form` object for each `FORM` tag in the document. You access `FORM` objects through the `document.forms` property and through named properties of that object. To define a form, use standard HTML syntax with the addition of JavaScript event handlers. If you supply a value for the `NAME` attribute, you can use that value to index into the `forms` array. In addition, the associated `document` object has a named property for each named form.

#### Event handlers

- `onReset`
- `onSubmit`

#### Description

Each form in a document is a distinct object. You can refer to a form's elements in your code by using the element's name (from the `NAME` attribute) or the `Form.elements` array. The `elements` array contains an entry for each element (such as a `Checkbox`, `Radio`, or `Text` object) in a form. If multiple objects on the same form have the same `NAME` attribute, an array of the given name is created automatically. Each element in the array represents an individual `Form` object. Elements are indexed in source order starting at 0. For example, if two `Text` elements and a `Textarea` element on the same form have their `NAME` attribute set to `"myField"`, an array with the elements `myField[0]`, `myField[1]`, and `myField[2]` is created. You need to be aware of this situation in your code and know whether `myField` refers to a single element or to an array of elements.

#### Property Summary

Property | Description
--- | ---
    action
| Reflects the `ACTION` attribute.
    elements
| An array reflecting all the elements in a form.
    encoding
| Reflects the `ENCTYPE` attribute.
    length
| Reflects the number of elements on a form.
    method
| Reflects the `METHOD` attribute.
    name
| Reflects the `NAME` attribute.
    target
| Reflects the `TARGET` attribute.

#### Method Summary

Method | Description
--- | ---
    handleEvent
| Invokes the handler for the specified event.
    reset
| Simulates a mouse click on a reset button for the calling form.
    submit
| Submits a form.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### Examples

Example 1: Named form. The following example creates a form called `myForm` that contains text fields for first name and last name. The form also contains two buttons that change the names to all uppercase or all lowercase. The function `setCase` shows how to refer to the form by its name.

    <HTML>
    <HEAD>
    <TITLE>Form object example</TITLE>
    </HEAD>
    <SCRIPT>
    function setCase (caseSpec){
    if (caseSpec == "upper") {
       document.myForm.firstName.value=document.myForm.firstName.value.toUpperCase()
       document.myForm.lastName.value=document.myForm.lastName.value.toUpperCase()}
    else {
       document.myForm.firstName.value=document.myForm.firstName.value.toLowerCase()
       document.myForm.lastName.value=document.myForm.lastName.value.toLowerCase()}
    }
    </SCRIPT>

    <BODY>
    <FORM NAME="myForm">
    <B>First name:</B>
    <INPUT TYPE="text" NAME="firstName" SIZE=20>
    <BR><B>Last name:</B>
    <INPUT TYPE="text" NAME="lastName" SIZE=20>
    <P><INPUT TYPE="button" VALUE="Names to uppercase" NAME="upperButton"
       onClick="setCase('upper')">
    <INPUT TYPE="button" VALUE="Names to lowercase" NAME="lowerButton"
       onClick="setCase('lower')">
    </FORM>
    </BODY>
    </HTML>

Example 2: forms array. The `onLoad` event handler in the following example displays the name of the first form in an Alert dialog box.

    <BODY onLoad="alert('You are looking at the ' + document.forms[0] + ' form!')">

If the form name is `musicType`, the alert displays the following message:

    You are looking at the <object musicType> form!

Example 3: onSubmit event handler. The following example shows an `onSubmit` event handler that determines whether to submit a form. The form contains one `Text` object where the user enters three characters. `onSubmit` calls a function, `checkData`, that returns true if there are 3 characters; otherwise, it returns false. Notice that the form's `onSubmit` event handler, not the submit button's `onClick` event handler, calls the `checkData` function. Also, the `onSubmit` handler contains a `return` statement that returns the value obtained with the function call; this prevents the form from being submitted if invalid data is specified. See `onSubmit` for more information.

    <HTML>
    <HEAD>
    <TITLE>Form object/onSubmit event handler example</TITLE>
    <TITLE>Form object example</TITLE>
    </HEAD>
    <SCRIPT>
    var dataOK=false
    function checkData (){
    if (document.myForm.threeChar.value.length == 3) {
       return true}
       else {
          alert("Enter exactly three characters. " + document.myForm.threeChar.value +
             " is not valid.")
          return false}
    }
    </SCRIPT>
    <BODY>
    <FORM NAME="myForm" onSubmit="return checkData()">
    <B>Enter 3 characters:</B>
    <INPUT TYPE="text" NAME="threeChar" SIZE=3>
    <P><INPUT TYPE="submit" VALUE="Done" NAME="submit1"
    onClick="document.myForm.threeChar.value=document.myForm.threeChar.value.toUpperCase()">
    </FORM>
    </BODY>
    </HTML>

Example 4: submit method. The following example is similar to the previous one, except it submits the form using the `submit` method instead of a `Submit` object. The form's `onSubmit` event handler does not prevent the form from being submitted. The form uses a button's `onClick` event handler to call the `checkData` function. If the value is valid, the `checkData` function submits the form by calling the form's `submit` method.

    <HTML>
    <HEAD>
    <TITLE>Form object/submit method example</TITLE>
    </HEAD>
    <SCRIPT>
    var dataOK=false
    function checkData (){
    if (document.myForm.threeChar.value.length == 3) {
       document.myForm.submit()}
       else {
          alert("Enter exactly three characters. " + document.myForm.threeChar.value +
             " is not valid.")
          return false}
    }
    </SCRIPT>
    <BODY>
    <FORM NAME="myForm" onSubmit="alert('Form is being submitted.')">
    <B>Enter 3 characters:</B>
    <INPUT TYPE="text" NAME="threeChar" SIZE=3>
    <P><INPUT TYPE="button" VALUE="Done" NAME="button1"
       onClick="checkData()">
    </FORM>
    </BODY>
    </HTML>

#### See also

`Button`, `Checkbox`, `FileUpload`, `Hidden`, `Password`, `Radio`, `Reset`, `Select`, `Submit`, `Text`, `Textarea`.

## action

A string specifying a destination URL for form data that is submitted

Property of | `Form`
Implemented in | JavaScript 1.0

#### Security

Submitting a form to a `mailto:` or `news:` URL requires the `UniversalSendMail` privilege. For information on security, see the Client-Side JavaScript Guide. JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `action` property is a reflection of the `ACTION` attribute of the `FORM` tag. Each section of a URL contains different information. See `Location` for a description of the URL components.

#### Examples

The following example sets the `action` property of the `musicForm` form to the value of the variable `urlName:`

    document.musicForm.action=urlName

#### See also

`Form.encoding`, `Form.method`, `Form.target`

## elements

An array of objects corresponding to form elements (such as `checkbox`, `radio`, and `Text` objects) in source order.

Property of | `Form`
Read-only |
Implemented in | JavaScript 1.0

#### Description

You can refer to a form's elements in your code by using the `elements` array. This array contains an entry for each object (`Button`, `Checkbox`, `FileUpload`, `Hidden`, `Password`, `Radio`, `Reset`, `Select`, `Submit`, `Text`, or `Textarea` object) in a form in source order. Each radio button in a `Radio` object appears as a separate element in the `elements` array. For example, if a form called `myForm` has a text field and two checkboxes, you can refer to these elements `myForm.elements[0]`, `myForm.elements[1]`, and `myForm.elements[2]`. Although you can also refer to a form's elements by using the element's name (from the `NAME` attribute), the `elements` array provides a way to refer to `Form` objects programmatically without using their names. For example, if the first object on the `userInfo` form is the `userName` `Text` object, you can evaluate it in either of the following ways:

    userInfo.userName.value
    userInfo.elements[0].value

The value of each element in the `elements` array is the full HTML statement for the object. To obtain the number of elements in a form, use the `length` property: `myForm.elements.length`.

#### Examples

See the examples for `window`.

## encoding

A string specifying the MIME encoding of the form.

Property of | `Form`
Implemented in | JavaScript 1.0

#### Description

The `encoding` property initially reflects the `ENCTYPE` attribute of the `FORM` tag; however, setting `encoding` overrides the `ENCTYPE` attribute.

#### Examples

The following function returns the value of the `encoding` property of `musicForm`:

    function getEncoding() {
       return document.musicForm.encoding
    }

#### See also

`Form.action`, `Form.method`, `Form.target`

## handleEvent

Invokes the handler for the specified event.

Method of | `Form`
Implemented in | JavaScript 1.2

#### Syntax

    handleEvent(event)

#### Parameters

    event
| The name of an event for which the specified object has an event handler.

#### Description

For information on handling events, see the Client-Side JavaScript Guide.

## length

The number of elements in the form.

Property of | `Form`
Read-only |
Implemented in | JavaScript 1.0

#### Description

The `form.length` property tells you how many elements are in the form. You can get the same information using `form.elements.length`.

## method

A string specifying how form field input information is sent to the server.

Property of | `Form`
Implemented in | JavaScript 1.0

#### Description

The `method` property is a reflection of the `METHOD` attribute of the `FORM` tag. The `method` property should evaluate to either `"get"` or `"post"`.

#### Examples

The following function returns the value of the `musicForm` `method` property:

    function getMethod() {
       return document.musicForm.method
    }

#### See also

`Form.action`, `Form.encoding`, `Form.target`

## name

A string specifying the name of the form.

Property of | `Form`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `name` property initially reflects the value of the `NAME` attribute. Changing the `name` property overrides this setting.

#### Examples

In the following example, the `valueGetter` function uses a `for` loop to iterate over the array of elements on the `valueTest` form. The `msgWindow` window displays the names of all the elements on the form:

    newWindow=window.open("http://home.netscape.com")

    function valueGetter() {
       var msgWindow=window.open("")
       for (var i = 0; i < newWindow.document.valueTest.elements.length; i++) {
          msgWindow.document.write(newWindow.document.valueTest.elements[i].name + "<BR>")
       }
    }

## reset

Simulates a mouse click on a reset button for the calling form.

Method of | `Form`
Implemented in | JavaScript 1.1

#### Syntax

    reset()

#### Parameters

None

#### Description

The `reset` method restores a form element's default values. A reset button does not need to be defined for the form.

#### Examples

The following example displays a `Text` object in which the user is to type "CA" or "AZ". The `Text` object's `onChange` event handler calls a function that executes the form's `reset` method if the user provides incorrect input. When the `reset` method executes, defaults are restored and the form's `onReset` event handler displays a message.

    <SCRIPT>
    function verifyInput(textObject) {
       if (textObject.value == 'CA' || textObject.value == 'AZ') {
          alert('Nice input')
       }
       else { document.myForm.reset() }
    }
    </SCRIPT>

    <FORM NAME="myForm" onReset="alert('Please enter CA or AZ.')">
    Enter CA or AZ:
    <INPUT TYPE="text" NAME="state" SIZE="2" onChange=verifyInput(this)><P>
    </FORM>

#### See also

`onReset`, `Reset`

## submit

Submits a form.

Method of | `Form`
Implemented in | JavaScript 1.0

#### Syntax

    submit()

#### Parameters

None

#### Security

Submitting a form to a `mailto:` or `news:` URL requires the `UniversalSendMail` privilege. For information on security, see the Client-Side JavaScript Guide. JavaScript 1.1: The `submit` method fails without notice if the form's `action` is a `mailto:`, `news:`, or `snews:` URL. Users can submit forms with such URLs by clicking a submit button, but a confirming dialog will tell them that they are about to give away private or sensitive information.

#### Description

The `submit` method submits the specified form. It performs the same action as a submit button. Use the submit method to send data back to an HTTP server. The `submit` method returns the data using either "get" or "post," as specified in `Form.method`.

#### Examples

The following example submits a form called `musicChoice`:

    document.musicChoice.submit()

If `musicChoice` is the first form created, you also can submit it as follows:

    document.forms[0].submit()

See also the example for `Form`.

#### See also

`Submit`, `onSubmit`

## target

A string specifying the name of the window that responses go to after a form has been submitted.

Property of | `Form`
Implemented in | JavaScript 1.0

#### Description

The `target` property initially reflects the `TARGET` attribute of the`A`, `AREA`, and `FORM` tags; however, setting `target` overrides these attributes. You can set `target` using a string, if the string represents a window name. The `target` property cannot be assigned the value of a JavaScript expression or variable.

#### Examples

The following example specifies that responses to the `musicInfo` form are displayed in the `msgWindow` window:

    document.musicInfo.target="msgWindow"

#### See also

`Form.action`, `Form.encoding`, `Form.method`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 11:59:27

Copyright (c) 1999 Netscape Communications Corporation