15.1 The Form Object

The JavaScript Form object represents an HTML form. Forms are always found as elements of the forms[] array, which is a property of the Document object. Forms appear in this array in the order in which they appear within the document. Thus, document.forms[0] refers to the first form in a document. You can refer to the last form in a document with the following:

document.forms[document.forms.length-1]

The most interesting property of the Form object is the elements[] array, which contains JavaScript objects (of various types) that represent the various input elements of the form. Again, elements appear in this array in the same order they appear in the document. So you can refer to the third element of the second form in the document of the current window like this:

document.forms[1].elements[2]

The remaining properties of the Form object are of less importance. The action , encoding, method, and target properties correspond directly to the action, encoding, method, and target attributes of the <form> tag. These properties and attributes are all used to control how form data is submitted to the web server and where the results are displayed; they are therefore useful only when the form is actually submitted to a server-side program. See the client-side reference section for an explanation of the properties, or see a book on HTML or CGI programming^[2] for a thorough discussion of the attributes. What is worth noting here is that these Form properties are all read/write strings, so a JavaScript program can dynamically set their values in order to change the way the form is submitted.

^[2] Such as CGI Programming on the World Wide Web, by Shishir Gundavaram (O'Reilly).

In the days before JavaScript, a form was submitted with a special-purpose Submit button, and form elements had their values reset with a special-purpose Reset button. The JavaScript Form object supports two methods, submit( ) and (as of JavaScript 1.1) reset( ), that serve the same purpose. Invoking the submit( ) method of a Form submits the form, and invoking reset( ) resets the form elements.

To accompany the submit( ) and reset( ) methods, the Form object provides the onsubmit event handler to detect form submission and (as of JavaScript 1.1) the onreset event handler to detect form resets. The onsubmit handler is invoked just before the form is submitted; it can cancel the submission by returning false. This provides an opportunity for a JavaScript program to check the user's input for errors in order to avoid submitting incomplete or invalid data over the network to a server-side program. We'll see an example of such error checking at the end of this chapter. Note that the onsubmit handler is triggered only by a genuine click on a Submit button. Calling the submit( ) method of a form does not trigger the onsubmit handler.

The onreset event handler is similar to the onsubmit handler. It is invoked just before the form is reset, and it can prevent the form elements from being reset by returning false. This allows a JavaScript program to ask for confirmation of the reset, which can be a good idea when the form is long or detailed. You might request this sort of confirmation with an event handler like the following:

<form...
    onreset="return confirm('Really erase ALL data and start over?')"
> 

Like the onsubmit handler, onreset is triggered only by a genuine Reset button. Calling the reset( ) method of a form does not trigger onreset.