Chapter 21
JavaScript Reference

Sample Entry

Name

Sample Entry--- how to read these reference pages

Title and Description

Every reference page begins with a title and one-line description like those above. They are useful to help you find the page you are looking for. The title usually consists of two words. The first is the name of the reference page, and the second is the type of reference page. For example, the reference page for the Date object is titled "Date Object". The reference page for the getDay() method of the Date object is "Date.getDay() Method". Similarly, the title of the reference page for the frames[] array property of the Window object is "Window.frames[] Property". The title of the page documenting the Button element of an HTML form is "Button Element", and you'll also find reference pages with titles that include the types "Function" (functions that are not methods), "Handler" (event handlers) and "Constant" (read-only properties that always have the same value).

Availability

Because slightly different versions of JavaScript run on Navigator 2.0 and 3.0 and on Internet Explorer 3.0, each reference page begins with an "Availability" section. This section specifies exactly which platforms the object, method, property, function, or event handler is available on. You can assume that anything available in one version of a browser is also available in later versions. For example, an objects available in Navigator 2.0 is also available in Navigator 3.0. Similarly, you can assume that methods, properties, etc., that are available in Navigator 3.0 and Internet Explorer 3.0 will also be available in Navigator 4.0 and Internet Explorer 4.0.

The availability section will occasionally note other things as well. If something is particularly buggy, or if it is deprecated (i.e., if its use is discouraged), that will be noted in this section as well.

Synopsis

The next section of every page is a synopsis of how you use the object, method, property, function, or event handler in your actual code. For example, the synopsis for the Form object is:

document.form_name
document.forms[form_number]

This synopsis shows two different ways of referring to a Form object. The italic font indicates text that is to be replaced with something else. form_name would be replaced with the name of a form, and form_number would be replaced with the index of the form in the forms[] array. Similarly, document would be replaced in these synopses with a reference to a Document object. By looking up the synopsis of the Document object, we discover that it also has two forms:

document
window.document

That is, we can replace document with the literal document, or with window.document. If we choose the latter, then we'll need to look up the Synopsis of the Window object to find out how to refer to a Window--that is, to find out what to replace window with.

Arguments

If the reference page describes a function or method, then the Synopsis is followed by an Arguments subsection, which describes the arguments to the function or method. For some object types, such as the Date object, the Synopsis section is replaced by a "Constructor" section. The Constructor section is also followed by this Arguments subsection.

arg1

The arguments are described in a list here. This is the description for argument arg1, for example.

arg2

And this is the description for argument arg2.

Returns

Because functions, methods, and constructors have return values as well as arguments, the Arguments subsection is followed by a Returns subsection, which explain the return value of the function, method, or constructor.

Properties

If the reference page documents an object, then the Properties section lists the properties the object supports, and provides short explanations of each. Each property will also have a complete reference page of its own. For example, the reference page for the Document object lists the lastModified property in this section, and gives a brief explanation of it. But the property is fully documented in the Document.lastModified reference page. The property listing looks like this:

prop1

This is a summary of property prop1, including the type of the property, its purpose or meaning, and whether it is read-only or read/write.

prop2

This is the same for prop2.

Methods

Reference pages for objects that define methods include a Methods section. It is just like the Properties section, except that it documents methods instead of properties.

Event Handlers

Some objects define event handlers in addition to properties and methods. They are listed and briefly described in this section.

HTML Syntax

A number of JavaScript objects have analogs in HTML. The reference pages for these objects include a section that shows the annotated HTML syntax that is used to create one of the JavaScript objects. For example, the reference page for the Button form element has the following in its "HTML Syntax" section:

<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 that can later be used to refer to the button
    specifies the name property
  [ onClick="handler" ]   JavaScript statements to be executed when the button is clicked
>

Description

Each reference page contains a section named "Description." This is the basic description of whatever it is that is being documented, the heart of the reference page. Unfortunately, on some of the more complex pages you have to read through quite a bit of synopsis, syntax, and lists of properties, methods, and event handlers before you get to it.

For some pages this section is no more than a short paragraph. On others it may occupy a page or more.

Usage

Some pages have a Usage section in addition to the Description section. When this section appears, be sure to pay attention to it. It describes common techniques for using the function, object, property or whatever, or it contains cautions that you should be aware of when using it.

Example

Some pages follow the Description and Usage information with an example showing a typical usage. Most pages do not contain examples--you'll find those in the main body of the text instead.

Bugs

When the topic of the page doesn't work quite right, this section describes the bugs. Appendix B, Known Bugs also contains a complete listing of common JavaScript bugs.