 |  |
| |
This part of the book is a reference section that documents the classes, methods, properties, and event handlers defined by web browsers that support client-side JavaScript. These classes, methods, and properties form the de facto standard called the DOM Level 0 API. Beginning scripters and programmers writing with backward compatibility in mind will use this reference section in conjunction with the core JavaScript reference of Part III. The introduction and sample reference page explain how to use and get the most out of this reference section. Take the time to read this material carefully, and you will find it easier to locate and use the information you need!
This reference section is arranged alphabetically. The reference pages for the methods and properties of classes are alphabetized by their full names, which include the names of the classes that define them. For example, if you want to read about the submit( ) method of the Form class, you would look under "Form.submit," not just "submit."
To save space in this enlarged fourth edition of the book, most properties in this reference section do not have reference pages of their own (all methods and event handlers do have their own reference pages, however). Instead, simple properties are completely documented in the reference page for the class that defines them. For example, you can read about the images[] property of the Document class in the "Document" reference page. Nontrivial properties that require substantial explanation do have reference pages of their own, and you'll find a cross-reference to these pages within the reference page of the class or interface that defines the properties. For example, when you look up the cookie property in the "Document" reference page or the status property in the "Window" reference page, you'll find a short description of the property and a reference to pages named "Document.cookie" and "Window.status."
Client-side JavaScript has a number of global properties and functions, such as window, history, and alert( ). In client-side JavaScript, a Window object serves as the global object, and the "global" properties and functions of client-side JavaScript are actually properties of the Window class. Therefore, in this client-side reference section, global properties and functions are documented in the "Window" reference page or under names such as "Window.alert( )."
Sometimes you may find that you don't know the name of the class or interface that defines the method or property you want to look up, or you may not be sure which of the three reference sections to look up a class or interface in. Part VI of this book is a special index designed to help with these situations. Look up the name of a class, method, or property, and it will tell you which reference section to look in and which class to look under in that section. For example, if you look up "Button," it will tell you that the Button class is documented in this client-side reference section. And if you look up the name "alert," it will tell you that alert( ) is a method of the client-side Window class.
Once you've found the reference page you're looking for, you shouldn't have much difficulty finding the information you need. Still, you'll be able to make better use of this reference section if you understand how the reference pages are written and organized. What follows is a sample reference page titled "Sample Entry" that demonstrates the structure of each reference page and tells you where to find various types of information within the pages. Take the time to read this page before diving into the rest of the reference material.
| Sample Entry | how to read client-side reference pages |
Availability
Inherits from
Every reference entry begins with a title block like that above. The entries are alphabetized by title. The short description, shown next to the title, gives you a quick summary of the item documented in the entry; it can help you quickly decide if you're interested in reading the rest of the page.
The information in this section tells you when a class, method, or event handler was introduced. For some less portable items, this section specifies which versions of Netscape and Internet Explorer support it. If the item is well supported by web browsers and support was added by Netscape and IE within the same browser generation, this section specifies its availability in terms of a version of core JavaScript. You can use the tables in Chapter 1 to determine the particular releases of Netscape and Internet Explorer to which these versions correspond. Of course, since most properties do not have their own reference pages, they do not have availability information. If the availability of a property is different from the availability of the class that defines it, however, this fact is noted in the description of the property.
If a class inherits from a superclass, that information is shown in the "Inherits from" section. As described in Chapter 8, JavaScript classes can inherit properties and methods from other classes. For example, the Button class inherits from Input, which in turn inherits from HTMLElement. When you see this inheritance information, you may also want to look up the listed superclasses.
Every reference page has a "Synopsis" section that shows how you might use the class, method, or event handler in your code. For example, the synopsis for the Form class is:
document.form_name document.forms[form_number]
This synopsis shows two different ways of referring to a Form object. Text in this font must be typed exactly as shown. The italic font indicates text that is to be replaced with something else. form_name should be replaced with the name of a form, and form_number should be replaced with the index of the form in the forms[] array. Similarly, document should be replaced in these synopses with a reference to a Document object. By looking at the "Synopsis" section of the "Document" reference page, we discover that it also has two forms:
document window.document
That is, you can replace document with the literal document or with window.document. If you choose the latter, you'll need to look up the synopsis of the Window class to find out how to refer to a Window -- that is, what to replace window with.
If a reference page documents a method, the "Synopsis" section is followed by an "Arguments" subsection that describes the arguments to the method. If the method has no arguments, this subsection is simply omitted.
This section explains the method's return value. If the method does not return a value, this subsection is omitted.
If the reference page documents a class that has a constructor method, this section shows you how to use the constructor method to create instances of the class. Since constructors are a type of method, the "Constructor" section looks a lot like the "Synopsis" section of a method's reference page and has an "Arguments" subsection as well.
If the reference page documents a class, the "Properties" section lists and documents the properties defined by that class. In this client-side reference section, only particularly complex properties have reference pages of their own.
The reference page for a class that defines methods includes a "Methods" section that lists the names of the methods and provides a short description of each. Full documentation for each method is found in a separate reference page.
The reference page for a class that defines event handlers includes an "Event Handlers" section that lists the names of the handlers and provides a short description of each. Full documentation for each event handler is found in a separate reference page.
A number of client-side JavaScript classes have analogs in HTML. The reference pages for these classes include a section that shows the annotated HTML syntax used to create an HTML element that corresponds to a JavaScript object.
Most reference pages contain a "Description" section, which is the basic description of the class, method, or event handler that is being documented. This is the heart of the reference page. If you are learning about a class, method, or handler for the first time, you may want to skip directly to this section and then go back and look at previous sections such as "Arguments," "Properties," and "Methods." If you are already familiar with an item, you probably won't need to read this section and instead will just want to quickly look up some specific bit of information (for example, from the "Arguments" or "Properties" sections).
In some entries, this section is no more than a short paragraph. In others, it may occupy a page or more. For some simple methods, the "Arguments" and "Returns" sections document the method sufficiently by themselves, so the "Description" section is omitted.
A few pages include an example that shows typical usage. Most pages do not contain examples, however -- you'll find those in first half of this book.
When an item doesn't work quite right, this section describes the bugs. Note, however, that this book does not attempt to catalog every bug in every version and implementation of client-side JavaScript.
Many reference pages conclude with cross-references to related reference pages that may be of interest. Most of these cross references are to other reference pages in this client-side reference section. Some are to individual property descriptions contained within a class reference page, however, and others are to related reference pages in the DOM reference section or to chapters in the first two parts of the book.
| Anchor | the target of a hypertext link |
JavaScript 1.2
Inherits from HTMLElement
document.anchors[i] document.anchors.length
Anchor inherits properties from HTMLElement and defines or overrides the following:
HTMLElement.innerText provides the IE 4 equivalent of this Netscape-specific property.
An Anchor object is created by any standard HTML <a> tag that contains a name attribute:
<a name="name" // Links may refer to this anchor by this name > text </a>
An anchor is a named location within an HTML document. Anchors are created with an <a> tag that has a name attribute specified. The Document object has an anchors[] array property that contains Anchor objects that represent each of the anchors in the document. This anchors[] array has existed since JavaScript 1.0, but the Anchor object was not implemented until JavaScript 1.2. Therefore, the elements of anchors[] were null until JavaScript 1.2.
Note that the <a> tag used to create anchors is also used to create hypertext links. Although hypertext links are often called anchors in HTML parlance, they are represented in JavaScript with the Link object, not with the Anchor object. In the DOM reference section of this book, however, both anchors and links are documented under HTMLAnchorElement.
anchors[] property of the Document object, Link; HTMLAnchorElement in the DOM reference section
| Applet | an applet embedded in a web page Applet object |
JavaScript 1.1
document.applets[i] document.appletName
The properties of an Applet object are the same as the public fields of the Java applet it represents.
The methods of an Applet object are the same as the public methods of the Java applet it represents.
The Applet object represents a Java applet embedded in an HTML document. The properties of the Applet object represent the public fields of the applet, and the methods of the Applet object represent the public methods of the applet. LiveConnect technology in Netscape and ActiveX technology in Internet Explorer allow JavaScript programs to use the Applet object to read and write the fields and invoke the methods of the corresponding Java applet. See Chapter 22 for details.
Remember that Java is a strongly typed language. This means that each field of an applet has been declared to have a specific data type, and setting it to a value of some other type causes a runtime error. The same is true of applet methods: each argument has a specific type, and arguments cannot be omitted as they can be in JavaScript.
| Area | see Link |
| Button | a graphical push buttonButton object |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.button_name form.elements[i]
Button inherits properties from Input and HTMLElement and defines or overrides the following:
Button inherits methods from Input and HTMLElement.
Button inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Button element is created with a standard HTML <input> tag:
<form>
...
<input
type="button" // Specifies that this is a button
value="label" // The text that is to appear within the button
// Specifies the value property
[ name="name" ] // A name you can use later to refer to the button
// Specifies the name property
[ onclick="handler" ] // JavaScript statements to be executed when the button
// is clicked
>
...
</form>Button objects can also be created with the HTML 4 <button> tag:
<button id="name"
onclick="handler">
label
</button>The Button element represents a graphical push button in a form within an HTML document. The value property contains the text displayed by the button. The name property is the name the button may be referred to as. The onclick event handler is invoked when the user clicks on the button.
Use a Button element whenever you want to allow the user to trigger some action on your web page. You can sometimes use a Link object for the same purpose, but unless the desired action is to follow a hypertext link, a Button is a better choice than a Link, because it makes it more explicit to the user that there is something to be triggered.
Note that the Submit and Reset elements are types of Buttons that submit a form and reset a form's values. Often these default actions are sufficient for a form, and you do not need to create any other types of buttons.
<form name="form1">
<input type="button"
name="press_me_button"
value="Press Me"
onclick="username = prompt('What is your name?',")"
>
</form>Form, HTMLElement, Input, Reset, Submit; HTMLInputElement in the DOM reference section
| Button.onclick | the handler invoked when a Button is clicked |
<input type="button" value="button-text" onclick="handler"> button.onclick
The onclick property of a Button object refers to an event handler function that is invoked when the user clicks on the button. See HTMLElement.onclick for complete details. Note, however, that Button.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Checkbox | a graphical checkbox |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
A single Checkbox element with a unique name may be referenced in either of these ways:
form.checkbox_name form.elements[i]
When a form contains a group of checkboxes with the same name, they are placed in an array and may be referenced as follows:
form.checkbox_name[j] form.checkbox_name.length
Checkbox inherits properties from Input and HTMLElement and defines or overrides the following:
If you set checked to true, the checkbox appears checked. Similarly, if you set this property to false, the checkbox appears unchecked. Note that setting the checked property does not cause the Checkbox element's onclick event handler to be invoked.
Note that the value field does not specify whether the checkbox is selected; the checked property specifies the current state of the checkbox. When defining a group of related checkboxes that share the same name in a form that is submitted to the server, it is important that each be given a distinct value attribute.
Checkbox inherits the methods of Input and HTMLElement.
Checkbox inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Checkbox element is created with a standard HTML <input> tag. Multiple Checkbox elements are often created in groups by specifying multiple <input> tags that have the same name attribute.
<form>
...
<input
type="checkbox" // Specifies that this is a checkbox
[ name="name" ] // A name you can use later to refer to this checkbox
// or to the group of checkboxes with this name
// Specifies the name property
[ value="value" ] // The value returned when this checkbox is selected
// Specifies the value property
[ checked ] // Specifies that the checkbox is initially checked
// Specifies the defaultChecked property
[ onclick="handler" ] // JavaScript statements to be executed
> // when the checkbox is clicked
label // The HTML text that should appear next to the checkbox
...
</form>The Checkbox element represents a single graphical checkbox in an HTML form. Note that the text that appears next to the checkbox is not part of the Checkbox element itself and must be specified externally to the Checkbox's HTML <input> tag.
The onclick event handler allows you to specify JavaScript code to be executed when the checkbox is checked or unchecked. You can examine the checked property to determine the state of the checkbox and set this property to check or uncheck the checkbox. Note that setting checked changes the graphical appearance of the checkbox but does not invoke the onclick event handler.
It is good programming style to specify the name attribute for a checkbox; this is mandatory if the checkbox is part of a form that submits data to a CGI script running on a web server. Specifying a name attribute sets the name property and allows you to refer to the checkbox by name (instead of as a member of the form elements array) in your JavaScript code, which makes the code more modular and portable.
For example, if the name attribute of a checkbox in form f is "opts", f.opts refers to the Checkbox element. Checkbox elements are often used in related groups, however, and each member of the group is given the same name attribute (the shared name defines the members of the group). In this case, JavaScript places each Checkbox element in the group in an array, and the array is given the shared name. If, for example, each of a group of checkboxes in form f has its name attribute set to "opts", f.opts is an array of Checkbox elements, and f.opts.length is the number of elements in the array.
You can set the value attribute or the value property of a checkbox to specify the string that is passed to the server if the checkbox is checked when the form is submitted. For a single checkbox used alone, the default value of "on" is usually adequate. When multiple checkboxes with the same name are used, each should specify a distinct value so a list of values from selected checkboxes can be passed to the server.
Checkbox elements can present the user with one or more options. This element type is suitable for presenting non-mutually exclusive choices. Use the Radio element for mutually exclusive lists of options.
Form, HTMLElement, Input, Radio; HTMLInputElement in the DOM reference section
| Checkbox.onclick | the handler invoked when a checkbox is selected |
<input type="checkbox" onclick="handler"> checkbox.onclick
The onclick property of a Checkbox object refers to an event handler function that is invoked when the user clicks on the checkbox. See HTMLElement.onclick for complete details. Note, however, that Checkbox.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Document | represents an HTML document |
JavaScript 1.0; enhanced in JavaScript 1.1, Netscape 4, and IE 4
Inherits from HTMLElement
window.document document
Document inherits properties from HTMLElement and defines the following properties. Netscape and Internet Explorer both define a number of incompatible Document properties that are used mostly for DHTML; they are listed separately after these properties.
Prior to JavaScript 1.2, the Anchor object was unimplemented, and the elements of anchors[] were all null.
document.applets[0] document.animator document.applets["animator"]
Document.plugins[] is a synonym for Document.embeds[]. Do not confuse it with Navigator.plugins[].
Document inherits methods from HTMLElement and defines the following methods. Netscape and IE both define a number of incompatible Document methods that are used mostly for DHTML; they are listed separately.
The <body> tag has onload and onunload attributes. Technically, however, the onload and onunload event handlers belong to the Window object rather than the Document object. See Window.onload and Window.onunload.
The Document object obtains values for a number of its properties from attributes of the HTML <body> tag. Also, the HTML contents of a document appear between the <body> and </body> tags:
<body [ background="imageURL" ] // A background image for the document [ bgcolor="color" ] // A background color for the document [ text="color" ] // The foreground color for the document's text [ link="color" ] // The color for unvisited links [ alink="color" ] // The color for activated links [ vlink="color" ] // The color for visited links [ onload="handler" ] // JavaScript to run when the document is loaded [ onunload="handler" ] // JavaScript to run when the document is unloaded > // HTML document contents go here </body>
The Document object represents the HTML document displayed in a browser window or frame (or layer, in Netscape 4). The properties of this object provide details about many aspects of the document, from the colors of the text, background, and anchors, to the date on which the document was last modified. The Document object also contains a number of arrays that describe the contents of the document. The links[] array contains one Link object for each hypertext link in the document. Similarly, the applets[] array contains one object for each Java applet embedded in the document, and the forms[] array contains one Form object for each HTML form that appears in the document.
The write( ) method of the Document object is especially notable. When invoked in scripts that are run while the document is loading, you can call document.write( ) to insert dynamically generated HTML text into the document.
See Chapter 14 for an overview of the Document object and of many of the JavaScript objects to which it refers. See Chapter 17 for an overview of the DOM standard.
Form, the document property of the Window object; Chapter 14; Document, HTMLDocument, and HTMLBodyElement in the DOM reference section
| Document.all[] | all HTML elements in a document Internet Explorer 4 |
document.all[i] document.all[name] document.all.tags(tagname)
all[] is a versatile array that contains all the HTML elements in a document. all[] contains the elements in source order, and you can extract them directly from the array if you know their exact numeric position within the array. It is more common, however, to use the all[] array to retreive elements by the value of their name or id HTML attributes. If more than one element has the specified name, using that name as an index into the all[] returns an array of elements that share the name.
all.tags( ) is passed a tag name and returns an array of HTML elements of the specified type.
| Document.captureEvents( ) | see Window.captureEvents( ) |
| Document.clear( ) | clear a document |
JavaScript 1.0; deprecated
document.clear( )
The clear( ) method of the Document object is deprecated and should not be used. To clear a document, you should simply open a new one with Document.open( ).
| Document.close( ) | close an output stream |
JavaScript 1.0
document.close( )
This method displays any output to document that has been written but not yet displayed and closes the output stream to document. When generating complete HTML pages with Document.write( ), you should invoke Document.close( ) when you reach the end of the page.
After document.close( ) has been called, if any further output is written to document (e.g., with document.write( )), the document is implicitly cleared and reopened, erasing all the output that was written prior to calling the close( ) method.
| Document.cookie | the cookie(s) of the document |
JavaScript 1.0
document.cookie
cookie is a string property that allows you to read, create, modify, and delete the cookie or cookies that apply to the current document. A cookie is a small amount of named data stored by the web browser. It gives web browsers a "memory" so they can use data input on one page in another page or recall user preferences across web browsing sessions. Cookie data is automatically transmitted between web browser and web server when appropriate so CGI scripts on the server end can read and write cookie values. Client-side JavaScript code can also read and write cookies with this property.
The Document.cookie property does not behave like a normal read/write property. You may both read and write the value of Document.cookie, but the value you read from this property is, in general, not the same as the value you write. For complete details on the use of this particularly complex property, see Chapter 16.
Cookies are intended for infrequent storage of small amounts of data. They are not intended as a general-purpose communication or programming mechanism, so use them in moderation. Note that web browsers are not required to retain the value of more than 20 cookies per web server (for the entire server, not just for your site on the server), nor to retain a cookie name/value pair of more than 4 KB in length.
| Document.domain | the security domain of a document |
JavaScript 1.1
document.domain
For security reasons, an unsigned script running in one window is not allowed to read properties of another window unless that window comes from the same web server as the host. This causes problems for large web sites that use multiple servers. For example, a script on the host www.oreilly.com might want to share properties with a script from the host search.oreilly.com.
The domain property helps to address this problem. Initially, this string property contains the hostname of the web server from which the document was loaded. You can set this property, but only in a very restricted way: it can be set only to a domain suffix of itself. For example, a script loaded from search.oreilly.com could set its own domain property to "oreilly.com". If a script from www.oreilly.com is running in another window, and it also sets its domain property to "oreilly.com", these two scripts can share properties, even though they did not originate on the same server.
Note, however, that a script from search.oreilly.com cannot set its domain property to "search.oreilly". And, more importantly, a script from snoop.spam.com cannot set its domain to "oreilly.com", which might allow it to determine, for example, which search keywords you use.
| Document.elementFromPoint( ) | determine which HTML element is at a given point |
document.elementFromPoint(x, y)
The HTML element that appears at point (x, y) in document.
| Document.getSelection( ) | return the selected text Netscape 4 |
document.getSelection( )
The text, if any, that is currently selected within the document. This returned text has HTML formatting tags removed.
| Document.handleEvent( ) | see Window.handleEvent( ) |
| Document.lastModified | the modification date of a document |
JavaScript 1.0
document.lastModified
lastModified is a read-only string property that contains the date and time at which document was most recently modified. This data is derived from HTTP header data sent by the web server. The web server generally obtains the last-modified date by examining the modification date of the file itself.
Web servers are not required to provide last-modified dates for the documents they serve. When a web server does not provide a last-modified date, JavaScript assumes 0, which translates to a date of midnight, January 1, 1970, GMT. The following example shows how you can test for this case.
It is a good idea to let readers know how recent the information you provide on the Web is. You can include an automatic timestamp in your documents by placing the following script at the end of each HTML file. Doing this means you do not need to update the modification time by hand each time you make a change to the file. Note that this script tests that the supplied date is valid before displaying it:
<script>
if (Date.parse(document.lastModified) != 0)
document.write('<p><hr><small><i>Last modified: '
+ document.lastModified
+ '</i></small>');
</script> The Document location, referrer, and title properties
| Document.links[] | the Link objects in a document |
JavaScript 1.0
document.links document.links.length
The links property is an array of Link objects -- one object for each hypertext link that appears in document. The links[] array has links.length elements, numbered from zero to links.length-1.
| Document.open( ) | begin a new document |
document.open( ) document.open(mimetype)
The document.open( ) method opens a stream to document so subsequent document.write( ) calls can append data to the document. The optional mimetype argument specifies the type of data to be written and tells the browser how to interpret that data.
If any existing document is displayed when the open( ) method is called, it is automatically cleared by the call to open( ) or by the first call to write( ) or writeln( ). After opening a document with open( ) and writing data to it with write( ), you should complete the document by calling close( ).
You usually call Document.open( ) with no argument to open an HTML document. Occasionally, a "text/plain" document is useful, for example, for a pop-up window of debugging messages.
Document.close( ), Document.write( ); HTMLDocument.open( ) in the DOM reference section
| Document.releaseEvents( ) | see Window.releaseEvents( ) |
| Document.routeEvent( ) | see Window.routeEvent( ) |
| Document.URL | the URL of the current document |
JavaScript 1.1
document.URL
URL is a read-only string property that contains the complete URL of the current document.
document.URL is usually equal to window.location.href for the window that contains document. These two are not always equal, however, because the Document.URL property may be modified through URL redirection -- Window.location contains the requested URL, and Document.URL specifies the actual URL where it was found.
Some web authors like to include the URL of a document somewhere within the document so, for example, if the document is cut-and-pasted to a file or printed out, there is still a reference to its location online. The following script, when appended to a document, automatically adds the document's URL:
<script>
document.write('<p><hr><small><i>URL: ' + document.URL
+ '</i></small>');
</script>The lastModified, location, referrer, and title properties of the Document object; the location property of the Window object
| Document.write( ) | append data to a document |
JavaScript 1.0
document.write(value, ...)
document.write( ) appends each of its arguments, in order, to document. Any arguments that are not strings are converted to strings before they are written to the end of the document.
Document.write( ) is usually used in one of two ways. First, it can be invoked on the current document within a <script> tag or within a function that is executed while the document is being parsed. In this case, the write( ) method writes its HTML output as if that output appeared literally in the file at the location of the code that invoked the method.
Second, you can use Document.write( ) to dynamically generate the contents of a document for a window other than the current window. In this case, the target document is never in the process of being parsed, and so the output cannot appear "in place" as it does in the case just described. In order for write( ) to output text into a document, that document must be open. You can open a document by explicitly calling the Document.open( ) method. In most cases this is unnecessary, however, because when write( ) is invoked on a document that is closed, it implicitly opens the document. When a document is opened, any contents that previously appeared in that document are discarded and replaced with a blank document.
Once a document is open, Document.write( ) can append any amount of output to the end of the document. When a new document has been completely generated by this technique, the document should be closed by calling Document.close( ). Note that although the call to open( ) is usually optional, the call to close( ) is never optional.
The results of calling Document.write( ) may not be immediately visible in the targeted web browser window or frame. This is because a web browser may buffer up data to output in larger chunks. Calling Document.close( ) is the only way to explicitly force all buffered output to be "flushed" and displayed in the browser window.
Document.close( ), Document.open( ), Document.writeln( ); Chapter 14
| Document.writeln( ) | append data and a newline to a document |
JavaScript 1.0
document.writeln(value, ...)
Document.writeln( ) behaves just like Document.write( ) except that after appending all of its arguments to document, it also appends a newline character. See the Document.write( ) reference page for more information on this method.
Newline characters are not usually displayed in HTML documents, so Document.writeln( ) is generally useful only when writing text to appear in a <pre> environment, or when writing to a document opened with a MIME type of "text/plain".
| Element | see Input |
| Event | details about an event |
JavaScript 1.2; incompatible versions supported by Netscape 4 and IE 4
function handler(event) { ... } // Event handler argument in Netscape 4
window.event // Window property in IE 4
In Netscape 4, the Event object defines bitmask constants for each of the supported event types. These static properties are used to form the bitmasks that are passed to captureEvents( ) and releaseEvents( ). The available constants are:
Event.ABORT |
Event.BLUR |
Event.CHANGE |
Event.CLICK |
Event.DBLCLICK |
Event.DRAGDROP |
Event.ERROR |
Event.FOCUS |
Event.KEYDOWN |
Event.KEYPRESS |
Event.KEYUP |
Event.LOAD |
Event.MOUSEDOWN |
Event.MOUSEMOVE |
Event.MOUSEOUT |
Event.MOUSEOVER |
Event.MOUSEUP |
Event.MOVE |
Event.RESET |
Event.RESIZE |
Event.SELECT |
Event.SUBMIT |
Event.UNLOAD |
The Event object provides details about an event that has occurred. Unfortunately, these details are not standardized, and Netscape 4 and IE 4 define Event objects that are almost entirely incompatible. Besides having different properties, Netscape 4 and IE 4 provide access to Event objects in different ways. In Netscape, an Event object is passed as an argument to every event handler. For event handlers defined by HTML attributes, the name of the event argument is event. In IE, the Event object of the most recent event is instead stored in the event property of the Window object.
In addition to the incompatibility between the Netscape 4 Event object and the IE Event object, the W3C DOM defines its own Event object that is incompatible with both. See the Event, UIEvent, and MouseEvent entries in the DOM reference section.
Chapter 19; Event, UIEvent, and MouseEvent in the DOM reference section
| FileUpload | a file upload field for form input |
JavaScript 1.0 Inherits from Input, HTMLElement
form.name form.elements[i]
FileUpload inherits properties from Input and HTMLElement and defines or overrides the following:
To prevent malicious programs from uploading arbitrary files from the client, this property may not be set by JavaScript code. Similarly, the value attribute of the <input> tag does not specify the initial value for this property.
FileUpload inherits methods from Input and HTMLElement.
FileUpload inherits event handlers from Input and HTMLElement and defines or overrides the following:
A FileUpload element is created with a standard HTML <input> tag:
<form enctype="multipart/form-data"
method="post"> // Required attributes
...
<input
type="file" // Specifies that this is a FileUpload element
[ name="name" ] // A name you can use later to refer to this element
// Specifies the name property
[ size="integer" ] // How many characters wide the element is
[ maxlength="integer" ] // Maximum allowed number of input characters
[ onblur="handler" ] // The onblur( ) event handler
[ onchange="handler" ] // The onchange( ) event handler
[ onfocus="handler" ] // The onfocus( ) event handler
>
...The FileUpload element represents a file upload input element in a form. In many respects, this input element is much like the Text element. On the screen, it appears like a text input field with the addition of a Browse button that opens a directory browser. Entering a filename into a FileUpload element (either directly or through the browser) causes Netscape to submit the contents of that file along with the form. For this to work, the form must use "multipart/form-data" encoding and the POST method.
The FileUpload element does not have a defaultValue property and does not recognize the value HTML attribute to specify an initial value for the input field. Similarly, the value property of the FileUpload element is read-only. Only the user may enter a filename; JavaScript may not enter text into the FileUpload field in any way. This is to prevent malicious JavaScript programs from uploading arbitrary files (such as password files) from the user's machine.
Form, HTMLElement, Input, Text; HTMLInputElement in the DOM reference section
| FileUpload.onchange | the handler invoked when input value changes |
<input type="file" onchange="handler"...> fileupload.onchange
The onchange property of a FileUpload element specifies an event handler function that is invoked when the user changes the value in the input field (either by typing directly or using the Browse button) and then moves input focus elsewhere. This handler is intended to process a complete change to the input value and therefore is not invoked on a keystroke-by-keystroke basis.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onchange attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onchange handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Input.onchange; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Form | an HTML input form |
JavaScript 1.0 Inherits from HTMLElement
document.form_name document.forms[form_number]
Form inherits properties from HTMLElement and defines or overrides the following:
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.
Form inherits methods from HTMLElement and defines the following:
Form inherits event handlers from HTMLElement and defines the following:
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> 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
Button, Checkbox, FileUpload, Hidden, Input, Password, Radio, Reset, Select, Submit, Text, Textarea; Chapter 15; HTMLFormElement in the DOM reference section
| Form.elements[] | the input elements of the form |
form.elements[i] form.elements.length
form.elements[] is an array of the form input objects in form. The array has elements.length items in it. These items may be of any of the form input element types: Button, Checkbox, Hidden, Password, Radio, Reset, Select, Submit, Text, and Textarea. These form input objects appear in the array in the same order that they appear in the HTML source code for the form.
If an item in the form.elements[] array has been given a name with the name="name" attribute of its HTML <input> tag, that item's name becomes a property of form, and this property refers to the item. Thus, it is possible to refer to input objects by name instead of by number:
form.name
Referring to elements by name is usually easier, so it is a good idea to specify the name attribute for all form elements.
Button, Checkbox, Form, Hidden, Input, Password, Radio, Reset, Select, Submit, Text, Textarea
| Form.onreset | the handler invoked when a form is reset |
<form ... onreset="handler" ... > form.onreset
The onreset property of a Form object specifies an event handler function that is invoked when the user clicks on a Reset button in the form or when Form.reset( ) is called.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onreset attribute of the HTML <form> tag. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than the scope of the containing window.
In the Netscape 4 event model, the onreset handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If the onreset handler returns false, the elements of the form are not reset.
You could use the following event handler to ask the user to confirm that they really want to reset the form:
<form ...
onreset="return confirm('Really erase all entered data?')"
> Form.onsubmit, Form.reset( ); Chapter 19; Section , EventListener, and EventTarget in the DOM reference section
| Form.onsubmit | invoked when a form is submitted |
<form ... onsubmit="handler" ... > form.onsubmit
The onsubmit property of a Form object specifies an event handler function that is invoked when the user submits a form by clicking on a Submit button in the form. Note that this event handler is not invoked when the Form.submit( ) method is called.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onsubmit attribute of the HTML <form> tag. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than the scope of the containing window.
In the Netscape 4 event model, the onsubmit handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If the onsubmit handler returns false, the elements of the form are not submitted. If the handler returns any other value or returns nothing, the form is submitted normally. Because the onsubmit handler can cancel form submission, it is ideal for performing form data validation.
Form.onreset, Form.submit( ); Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Form.reset( ) | reset the elements of a form |
form.reset( )
The reset( ) method resets the specified form, restoring each element of the form to its default value, exactly as if a Reset button had been pressed by the user. The form's onreset( ) event handler is first invoked and may prevent the reset from occurring by returning the value false.
| Form.submit( ) | submit a formJavaScript 1.0 |
form.submit( )
The submit( ) method submits the specified form, almost as if a Submit button had been pressed by the user. The form is submitted as specified by the action, method, and encoding properties of form (or the action, method, and enctype attributes of the <form> tag), and the results are displayed in the window or frame specified by the target property or the target attribute.
The one important difference between the submit( ) method and form submission by the user is that the onsubmit( ) event handler is not invoked when submit( ) is called. If you use onsubmit( ) to perform input validation, for example, you'll have to do that validation explicitly before calling submit( ).
It is more common to use a Submit button that allows the user to submit the form than to call the submit( ) method yourself.
| Form.target | the window for form results |
JavaScript 1.0;
read-only in Internet Explorer 3