JavaScript Bible, Gold Edition part 69 pptx

FORM Object For HTML element properties, methods, and event handlers, see Chapter 15.. References to form control elements For most client-side scripting, user interaction comes from the

syntax that is compatible with the earliest scriptable browsers Besides, the only significant additions to the defining points of the form object in newer browsers are those characteristics that all other HTML elements share The true scriptable heart

of the form object has been within the scripter’s reach since NN2

FORM Object

For HTML element properties, methods, and event handlers, see Chapter 15

elements encoding enctype length method name target

Syntax

Accessing FORM object properties or methods:

(All) [window.]document.formName property | method([parameters]) (All) [window.]document.forms[index] property | method([parameters]) (All) [window.]document.forms[“formName”] property | method([parameters]) (IE4+) [window.]document.all.elemID.property | method([parameters])

(IE5+/NN6) [window.]document.getElementById(“elemID”).property |

method([parameters])

About this object

Forms and their elements are the most common two-way gateways between users and JavaScript scripts A form control element provides the only way that users can enter textual information Form controls also provide somewhat stan-dardized and recognizable user interface elements for the user to make a selection from a predetermined set of choices Sometimes those choices appear in the form

of an on/off checkbox, in a set of mutually exclusive radio buttons, or as a selection from a list

As you have seen in many Web sites, the form is the avenue for the user to enter information that is sent to the server housing the Web files Just what the server

does with this information depends on the CGI (Common Gateway Interface)

programs running on the server If your Web site runs on a server directly under

your control (that is, it is in-house or hosted by a service), you have the freedom to

set up all kinds of data-gathering or database search programs to interact with the

user But with some of the more consumer-oriented Internet Service Providers (ISPs),

you may have no CGI support available — or, at best, a limited set of popular but

inflexible CGI programs available to all customers of the service Custom databases

or transactional services are rarely provided for this kind of Internet service

Regardless of your Internet server status, you can find plenty of uses for

JavaScript scripts in forms For instance, rather than using data exchanges (and

Internet bandwidth) to gather raw user input and report any errors, a

JavaScript-enhanced document can preprocess the information to make sure that it employs

the format that your back-end database or other programs most easily process All

corrective interaction takes place in the browser, without one extra bit flowing across

the Net I devote all of Chapter 43 to these kinds of form data-validation techniques

How you define a FORM element (independent of the user interface elements

described in subsequent chapters) depends a great deal on how you plan to use

the information from the form’s controls If you intend to use the form completely

for JavaScript purposes (that is, no queries or postings going to the server), you

do not need to use the ACTION, TARGET, and METHODattributes But if your Web

page will be feeding information or queries back to a server, you need to specify

at least the ACTIONand METHODattributes You need to also specify the TARGET

attribute if the resulting data from the server is to be displayed in a window other

than the calling window and the ENCTYPEattribute if your form’s scripts fashion

the server-bound data in a MIME type other than in a plain ASCII stream

References to form control elements

For most client-side scripting, user interaction comes from the elements within

a form; the FORM element object is merely a container for the various control

elements If your scripts perform any data validation checks on user entries prior

to submission or other calculations, many statements have the form object as part

of the reference to the element

A complex HTML document can have multiple FORM objects Each <FORM>

</FORM>tag pair defines one form You don’t receive any penalties (except for

potential confusion on the part of someone reading your script) if you reuse a name

for an element in each of a document’s forms For example, if each of three forms

has a grouping of radio buttons with the name “choice,” the object reference to

each button ensures that JavaScript doesn’t confuse them The reference to the

first button of each of those button groups is as follows:

document.forms[0].choice[0]

document.forms[1].choice[0]

document.forms[2].choice[0]

Remember, too, that you can create forms (or any HTML object for that matter)

on the fly when you assemble HTML strings for writing into other windows or

frames Therefore, you can determine various attributes of a form from settings in

an existing document

FORM

Passing forms and elements to functions

When a form or form element contains an event handler that calls a function defined elsewhere in the document, you can use a couple of shortcuts to simplify the task of addressing the objects while the function does its work Failure to grasp this concept not only causes you to write more code than you have to, but it also hopelessly loses you when you try to trace somebody else’s code in his or her JavaScripted document The watchword in event handler parameters is this

which represents a reference to the current object that contains the event handler attribute For example, consider the function and form definition in Listing 23-1 The entire user interface for this listing consists of form elements, as shown in Figure 23-1

Listing 23-1: Passing the Form Object as a Parameter

<HTML>

<HEAD>

<TITLE>Beatle Picker</TITLE>

<SCRIPT LANGUAGE=”JavaScript”>

function processData(form) { for (var i = 0; i < form.Beatles.length; i++) {

if (form.Beatles[i].checked) { break

} } var chosenBeatle = form.Beatles[i].value var chosenSong = form.song.value

alert(“Looking to see if “ + chosenSong + “ was written by “ + chosenBeatle + “ ”)

} function checkSong(songTitle) { var enteredSong = songTitle.value alert(“Making sure that “ + enteredSong + “ was recorded by the Beatles.”) }

</SCRIPT>

</HEAD>

<BODY>

<FORM NAME=”Abbey Road”>

Choose your favorite Beatle:

<INPUT TYPE=”radio” NAME=”Beatles” VALUE=”John Lennon” CHECKED=”true”>John

<INPUT TYPE=”radio” NAME=”Beatles” VALUE=”Paul McCartney”>Paul

<INPUT TYPE=”radio” NAME=”Beatles” VALUE=”George Harrison”>George

<INPUT TYPE=”radio” NAME=”Beatles” VALUE=”Ringo Starr”>Ringo<P>

Enter the name of your favorite Beatles song:<BR>

<INPUT TYPE=”text” NAME=”song” VALUE=”Eleanor Rigby”

onChange=”checkSong(this)”><P>

<INPUT TYPE=”button” NAME=”process” VALUE=”Process Request ”

onClick=”processData(this.form)”>

</BODY>

</HTML>

Figure 23-1: Controls pass different object references to functions in Listing 23-1.

The processData()function, which needs to read and write properties of

multiple form control elements, can reference the controls in two ways One way

is to have the onClickevent handler (in the button element at the bottom of the

document) call the processData()function and not pass any parameters Inside

the function, all references to objects (such as the radio buttons or the song field)

must be complete references, such as

document.forms[0].song.value

to retrieve the value entered into the songfield

A more efficient way is to send a reference to the FORM object as a parameter

with the call to the function (as shown in Listing 23-1) By specifying this.formas

the parameter, you tell JavaScript to send along everything it knows about the form

from which the function is called This works because formis a property of every

form control element; the property is a reference to the form that contains the

control Therefore, this.formpasses the value of the formproperty of the control

At the function, the reference to the FORM object is assigned to a variable name

(arbitrarily set to formhere) that appears in parentheses after the function name

I use the parameter variable name formhere because it represents an entire form

But you can use any valid variable name you like

FORM

The reference to the form contains everything the browser needs to know to find that form within the document Any statements in the function can therefore use the parameter value in place of the longer, more cumbersome reference to the form Thus, here I can use formto take the place of document.forms[0]in any address To get the value of the songfield, the reference is:

form.song.value Had I assigned the form object to a parameter variable called sylvester, the reference would have been:

sylvester.song.value When a function parameter is a reference to an object, statements in the function can retrieve or set properties of that object as well as invoke the object’s methods Another version of the thisparameter passing style simply uses the word this

as the parameter Unlike this.form, which passes a reference to the entire form connected to a particular element, thispasses a reference only to that one element

In Listing 23-1, you can add an event handler to the songfield to do some validation

of the entry (to make sure that the entry appears in a database array of Beatles’ songs created elsewhere in the document) Therefore, you want to send only the

fieldobject to the function for analysis:

<INPUT TYPE=”text” NAME=”song” onChange=”checkSong(this)”><P>

You then have to create a function to catch this call:

function checkSong(songTitle) { var enteredSong = songTitle.value alert(“Making sure that “ + enteredSong + “ was recorded by the Beatles.”) }

Within this function, you can go straight to the heart — the valueproperty of the field element without a long reference

One further extension of this methodology passes only a single property of a form control element as a parameter In the last example, the checkSong()function needs only the valueproperty of the field, so the event handler can pass this valueas a parameter Because thisrefers to the very object in which the event handler appears, the this.propertyNamesyntax enables you to extract and pass along a single property:

<INPUT TYPE=”text” NAME=”song” onChange=”checkSong(this.value)”><P>

A benefit of this way of passing form element data is that the function doesn’t have

to do as much work:

function checkSong(songTitle) { alert(“Making sure that “ + songTitle + “ was recorded by the Beatles.”) }

Unlike passing object references (like the form and text field objects above), when you pass a property value (for example, this.value), the property’s value is passed with no reference to the object from which it came This suffices when the function just needs the value to do its job However, if part of that job is to modify the object’s property (for example, converting all text from a field to uppercase and redisplaying the converted text), the value passed to the function does not maintain

a “live” connection with its object To modify a property of the object that invokes

an event handler function, you need to pass some object reference so that the

function knows where to go to work on the object

Many programmers with experience in other languages expect parameters to be

passed either by reference or by value, but not both ways The rule of thumb in

JavaScript, however, is fairly simple: object references are passed by reference;

property values are passed by value

Here are some guidelines to follow when deciding what kind of value to pass to

an event handler function:

✦ Pass the entire form control object (this) when the function needs to make

subsequent access to that same element (perhaps reading an object’s value

property, converting the value to all uppercase letters, and then writing the

result back to the same object’s valueproperty)

✦ Pass only one property (this.propertyName) when the function needs

read-only access to that property

✦ Pass the entire FORM element object (this.form) for the function to access

multiple elements inside a form (for example, a button click means that the

function must retrieve a field’s content)

Also be aware that you can submit multiple parameters (for example,

onClick=”someFunction (this.form, this.name)”) or even an entirely

different object from the same form (for example, onClick=”someFunction

(this.form.emailAddr.value)”) Simply adjust your function’s incoming

parameters accordingly (See Chapter 41 for more details about custom functions.)

E-mailing forms

A common request among scripters is how to send a form via e-mail to the page’s

author This includes the occasional desire to send “secret” e-mail to the author

whenever someone visits the Web site Let me address the privacy issue first

A site visitor’s e-mail address is valuable personal information that you should

not retrieve without the visitor’s permission or knowledge That’s one reason why

Netscape plugged a privacy hole in Navigator 2 that allowed submitting a form to

amailto:URL without requesting permission from the user You can use some

workarounds for this in Navigator 3, but I do not condone surreptitiously lifting

e-mail addresses and therefore choose not to publicize those workarounds here

Besides, as more users gravitate to newer browser versions, the workarounds fail

anyway

Microsoft, on the other hand, went too far in preventing forms e-mailing in the

earliest browser versions While Netscape’s browsers reveal to the user in an alert

that an e-mail message bearing the user’s e-mail address (as stored in the browser’s

preferences) will be sent upon approval, Internet Explorer 3 does not send form

content via e-mail at all Internet Explorer 4 sends form content as an attachment

through Microsoft Outlook, but only after displaying a mail composition window

to the user Starting with IE5, the process is much more fluid, but the action works

best when Outlook is the default e-mail client on the computer

Tip

FORM

Many ISPs that host Web sites provide standard CGIs for forwarding forms to an e-mail address of your choice This manner of capturing form data, however, does not also capture the visitor’s e-mail address unless your form has a field where the visitor voluntarily enters that information

Under no circumstances is a form submitted via the mailto: URL a secure docu-ment The form data is embedded within a plain e-mail message that goes through the same Internet routes and servers as any e-mail message

The remaining discussion about mailing forms focuses primarily on NN2+ and IE5+ browsers You should be aware that mailing forms in the following ways is controversial in some Web standards circles As of this writing, the W3C HTML specification does not endorse these techniques specifically However, the latest browsers do support them nonetheless Use these facilities judiciously and only after extensive testing on the client browsers you intend to support

If you want to have forms submitted as e-mail messages, you must attend to three

<FORM>tag attributes The first is the METHODattribute You must set it to POST Next comes ENCTYPE If you omit this attribute, the e-mail client sends the form data as an attachment consisting of escaped name-value pairs, as in this example:

name=Danny+Goodman&rank=Scripter+First+Class&serialNumber=042 But if you set the ENCTYPEattribute to text/plain, the form name-value pairs are placed in the body of the mail message in a more human-readable format:

name=Danny Goodman rank=Scripter First Class serialNumber=042

The last attribute of note is the ACTIONattribute, which is normally the spot to place a URL to another file or server CGI Substitute the URL with the special

mailto:URL followed by an optional parameter for the subject Here is an example: ACTION=”mailto:prez@whitehouse.gov?subject=Opinion%20Poll”

To sum up, the following example shows the complete <FORM>tag for e-mailing the form in Navigator

<FORM NAME=”entry”

METHOD=POST ENCTYPE=”text/plain”

ACTION=”mailto:prez@whitehouse.gov?subject=Opinion Poll”>

None of this requires any JavaScript at all But seeing how you can use the attributes — and the fact that these attributes are exposed as properties of the FORM element object — you might see some extended possibilities for script control over forms

Changing form attributes

With the exception of IE3 (whose FORM object properties are read-only), all scriptable browsers expose FORM element attributes as modifiable properties Therefore, you can change, say, the action of a form via a script in response to user interaction on your page For example, you can have two different CGI programs invoked on your server depending on whether a form’s checkbox is checked

Note

The best opportunity to change the properties of a FORM element object is in a

function invoked by the form’s onSubmit event handler The modifications are

performed at the last instant prior to actual submission, leaving no room for

user-induced glitches to get in the way

Buttons in forms

A common mistake that newcomers to scripting make is defining all clickable

but-tons as the submit type of inputobject (<INPUT TYPE=”submit”>) The Submit

button does exactly what it says — it submits the form If you don’t set any METHOD

or ACTIONattributes of the <FORM>tag, the browser inserts its default values for

you: METHOD=GETand ACTION=pageURL When you submit a form with these

attributes, the page reloads itself and resets all field values to their initial values

Use a Submit button only when you want the button to actually submit the

form If you want a button for other types of action, use the button style (<INPUT

TYPE=”button”>) A regular button can invoke a function that performs some

internal actions and then invokes the FORM element object’s submit()method

to submit the form under script control

Redirection after submission

Undoubtedly, you have submitted a form to a site and seen a “Thank You” page

come back from the server to verify that your submission was accepted This is warm

and fuzzy, if not logical, feedback for the submission action It is not surprising that

you would want to recreate that effect even if the submission is to a mailto:URL

Unfortunately, a problem gets in the way

A common sense approach to the situation calls for a script to perform the

submission (via the form.submit()method) and then navigate to another page

that does the “Thank You.” Here is such a scenario from inside a function triggered

by a click of a link surrounding a nice, graphical Submit button:

function doSubmit() {

document.forms[0].submit()

location.href = “thanks.html”

}

The problem is that when another statement executes immediately after the

form.submit()method, the submission is canceled In other words, the script

does not wait for the submission to complete itself and verify to the browser that

all is well (even though the browser appears to know how to track that information

given the statusbar feedback during submission) The point is, because JavaScript

does not provide an event that is triggered by a successful submission, there is no

sure-fire way to display your own “Thank You” page

Don’t be tempted by the window.setTimeout()method to change the location

after some number of milliseconds following the form.submit()method You

cannot predict how fast the network and/or server is for every visitor If the

submission does not complete before the timeout ends, then the submission is

still canceled — even if it is partially complete

It’s too bad we don’t have this power at our disposal yet Perhaps a future

version of the document object model will provide an event that enables us to

do something only after a successful submission

Tip

FORM

Form element arrays

Starting with NN2 and IE4, document object models provide a feature that is beneficial to a lot of scripters If you create a series of like-named objects, they automatically become an array of objects accessible via array syntax (see Chapter 7) This is particularly helpful when you create forms with columns and rows of fields, such as in an order form By assigning the same name to all fields in a column, you can employ forloops to cycle through each row using the loop index as an array index

As an example, the following code shows a typical function that calculates the total for an order form row (and calls another custom function to format the value): function extendRows(form) {

for (var i = 0; i < Qty.length; i++) { var rowSum = form.Qty[i].value * form.Price[i].value form.Total[i].value = formatNum(rowSum,2)

} } All fields in the Qty column are named Qty The item in the first row has an array index value of zero and is addressed as form.Qty[i]

Unfortunately, Internet Explorer 3 does not turn like-named fields into an array of references But you can still script repetitive moves through an organized set of fields The key is to assign names to the fields that include their index numbers:

Qty0, Qty1, Qty2, and so on You can even assign these names in a forloop that generates the table:

for (var i = 0; i <= rowcount; i++) {

document.write(“<INPUT TYPE=’text’ NAME=’Qty” + i + “‘>”)

} Later, when it comes time to work with the fields, you can use the indexing scheme to address the fields:

for (var i = 0; i < Qty.length; i++) { var rowSum = form.elements[“Qty” + i].value * form.elements[“Price” + i].value

form[“Total” + i].value = formatNum(rowSum,2) }

In other words, construct names for each item, and use those names as array index names This solution is backward- and forward-compatible

About < INPUT > element objects

While this chapter focuses strictly on the FORM element as a container of con-trols, the next three chapters discuss different types of controls that nest inside a form Many of these controls share the same HTML tag: <INPUT> Only theTYPE

attribute of the <INPUT>tag determines whether the browser shows you a clickable button, a checkbox, a text field, or so on The fact that one element has so many guises makes the system seem illogical at times to scripters

An INPUT element has some attributes (and corresponding scriptable object properties) that simply don’t apply to every type of form control For example,

while the maxLengthproperty of a text box makes perfect sense in limiting the

number of characters that a user can type into it, the property has no bearing

whatsoever on form controls that act as clickable buttons Similarly, you can

switch a radio button or checkbox on or off by adjusting the checkedproperty;

however, that property simply doesn’t apply to a text box

As the document object models have evolved, they have done so in an increasingly

object-oriented way The result in this form-oriented corner of the model is that all

elements created via the <INPUT>tag have a long list of characteristics that they all

share by virtue of being types of INPUT elements — they inherit the properties and

methods that are defined for any INPUT element To try to limit the confusion, I

divide the chapters in this book that deal with INPUT elements along functional lines

(clickable buttons in one chapter, text fields in the other), and only list and discuss

those INPUT element properties and methods that apply to the specific control type

In the meantime, this chapter continues with details of the FORM element object

Properties

acceptCharset

The acceptCharsetproperty represents the ACCEPTCHARSETattribute of the

FORM element in HTML 4.0 The value is a list of one or more recognized character

sets that the server receiving the form must support For a list of registered

character set names, see ftp://ftp.isi.edu/in-notes/iana/assignments/

character-sets

Related Items: None.

action

The actionproperty (along with the methodand targetproperties) primarily

functions for HTML authors whose pages communicate with server-based CGI

scripts This property is the same as the value you assign to the ACTIONattribute

of a <FORM>tag The value is typically a URL on the server where queries or postings

are sent for submission

User input may affect how you want your page to access a server For example,

a checked box in your document may set a form’s actionproperty so that a CGI

script on one server handles all the input, whereas an unchecked box means the

form data goes to a different CGI script or a CGI script on an entirely different server

FORM.action