 |
Chapter 21 JavaScript Reference |
 |
|
Chapter 21 JavaScript Reference |
|
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).
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.
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]
document window.document
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.
The arguments are described in a list here. This is the description for argument arg1, for example.
And this is the description for argument arg2.
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.
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:
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.
This is the same for prop2.
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.
Some objects define event handlers in addition to properties and methods. They are listed and briefly described in this section.
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
>
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.
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.
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.
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.
Finally, every reference page concludes with cross-references to related reference pages that may be of interest. Sometimes reference pages also refer back to one of the main chapters of the book.
|
 |
|
| How to Read the Reference Pages |  |
alert() |
