Table of Contents | Previous | Next | Index

# Submit

A submit button on an HTML form. A submit button causes a form to be submitted.

Client-side object |
Implemented in | JavaScript 1.0 JavaScript 1.1: added `type` property; added onBlur and onFocus event handlers; added `blur` and `focus` methods JavaScript 1.2: added `handleEvent` method

#### Created by

The HTML `INPUT` tag, with `"submit"` as the value of the `TYPE` attribute. For a given form, the JavaScript runtime engine creates an appropriate `Submit` object and puts it in the `elements` array of the corresponding `Form` object. You access a `Submit` object by indexing this array. You can index the array either by number or, if supplied, by using the value of the `NAME` attribute.

#### Event handlers

- `onBlur`
- `onClick`
- `onFocus`

#### Security

Submitting a form to a `mailto:` or `news:` URL requires the `UniversalSendMail` privilege. For information on security, see the Client-Side JavaScript Guide.

#### Description

A `Submit` object on a form looks as follows:

A `Submit` object is a form element and must be defined within a `FORM` tag. Clicking a submit button submits a form to the URL specified by the form's `action` property. This action always loads a new page into the client; it may be the same as the current page, if the action so specifies or is not specified. The submit button's `onClick` event handler cannot prevent a form from being submitted; instead, use the form's `onSubmit` event handler or use the `submit` method instead of a `Submit` object. See the examples for the `Form` object.

#### Property Summary

Property | Description
--- | ---
    form
| Specifies the form containing the `Submit` object.
    name
| Reflects the `NAME` attribute.
    type
| Reflects the `TYPE` attribute.
    value
| Reflects the `VALUE` attribute.

#### Method Summary

Method | Description
--- | ---
    blur
| Removes focus from the submit button.
    click
| Simulates a mouse-click on the submit button.
    focus
| Gives focus to the submit button.
    handleEvent
| Invokes the handler for the specified event.

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

#### Examples

The following example creates a `Submit` object called `submitButton`. The text "Done" is displayed on the face of the button.

    <INPUT TYPE="submit" NAME="submitButton" VALUE="Done">

See also the examples for the `Form`.

#### See also

`Button`, `Form`, `Reset`, `Form.submit`, `onSubmit`

## blur

Removes focus from the submit button.

Method of | `Submit`
Implemented in | JavaScript 1.0

#### Syntax

    blur()

#### Parameters

None

#### See also

`Submit.focus`

## click

Simulates a mouse-click on the submit button, but does not trigger an object's `onClick` event handler.

Method of | `Submit`
Implemented in | JavaScript 1.0

#### Syntax

    click()

#### Parameters

None

## focus

Navigates to the submit button and gives it focus.

Method of | `Submit`
Implemented in | JavaScript 1.0

#### Syntax

    focus()

#### Parameters

None

#### See also

`Submit.blur`

## form

An object reference specifying the form containing the submit button.

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

#### Description

Each form element has a `form` property that is a reference to the element's parent form. This property is especially useful in event handlers, where you might need to refer to another element on the current form.

#### Examples

The following example shows a form with several elements. When the user clicks `button2`, the function `showElements` displays an alert dialog box containing the names of each element on the form `myForm`.

    <SCRIPT>
    function showElements(theForm) {
       str = "Form Elements of form " + theForm.name + ": \n "
       for (i = 0; i < theForm.length; i++)
          str += theForm.elements[i].name + "\n"
       alert(str)
    }
    </SCRIPT>
    <FORM NAME="myForm">
    Form name:<INPUT TYPE="text" NAME="text1" VALUE="Beluga">
    <P>
    <INPUT NAME="button1" TYPE="button" VALUE="Show Form Name"
       onClick="this.form.text1.value=this.form.name">
    <INPUT NAME="button2" TYPE="submit" VALUE="Show Form Elements"
       onClick="showElements(this.form)">
    </FORM>

The alert dialog box displays the following text:

    Form Elements of form myForm:
    text1
    button1
    button2

#### See also

`Form`

## handleEvent

Invokes the handler for the specified event.

Method of | `Submit`
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.

## name

A string specifying the submit button's name.

Property of | `Submit`
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. Do not confuse the `name` property with the label displayed on the `Submit` button. The `value` property specifies the label for this button. The `name` property is not displayed on the screen; it is used to refer programmatically to the button. 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 `Submit` 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.

#### 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>")
       }
    }

#### See also

`Submit.value`

## type

For all `Submit` objects, the value of the `type` property is `"submit"`. This property specifies the form element's type.

Property of | `Submit`
Read-only |
Implemented in | JavaScript 1.1

#### Examples

The following example writes the value of the `type` property for every element on a form.

    for (var i = 0; i < document.form1.elements.length; i++) {
       document.writeln("<BR>type is " + document.form1.elements[i].type)
    }

## value

A string that reflects the submit button's `VALUE` attribute.

Property of | `Submit`
Read-only |
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

When a `VALUE` attribute is specified in HTML, the `value` property is that string and is displayed on the face of the button. When a `VALUE` attribute is not specified in HTML, the `value` property for the button is the string "Submit Query." Do not confuse the `value` property with the `name` property. The `name` property is not displayed on the screen; it is used to refer programmatically to the button.

#### Examples

The following function evaluates the `value` property of a group of buttons and displays it in the `msgWindow` window:

    function valueGetter() {
       var msgWindow=window.open("")
       msgWindow.document.write("submitButton.value is " +
          document.valueTest.submitButton.value + "<BR>")
       msgWindow.document.write("resetButton.value is " +
          document.valueTest.resetButton.value + "<BR>")
       msgWindow.document.write("helpButton.value is " +
          document.valueTest.helpButton.value + "<BR>")
       msgWindow.document.close()
    }

This example displays the following values:

    Query Submit
    Reset
    Help

The previous example assumes the buttons have been defined as follows:

    <INPUT TYPE="submit" NAME="submitButton">
    <INPUT TYPE="reset" NAME="resetButton">
    <INPUT TYPE="button" NAME="helpButton" VALUE="Help">

#### See also

`Submit.name`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 12:00:39

Copyright (c) 1999 Netscape Communications Corporation