JavaScript Object Reference

This document is the reference for JavaScript objects in the client and their properties, methods, and event handlers.

NOTE: Features not yet implemented are noted as "NYI."

JavaScript Objects:

Object Hierarchy

Netscape Navigator JavaScript comes with a number of built-in objects. Although you cannot create new objects or object classes, as you can in languages such as Java, it is useful to understand the object hierarchy of the built-in objects. In the strict object-oriented sense, this type of hierarchy is known as an instance hierarchy, since it concerns specific instances of objects rather than object classes.

The hierarchy is illustrated below: 

window 
  |
  +--parent, frames, self, top 
  |
  +--location 
  | 
  +--history
  |
  +--document
       |
       +--forms
       |    |
       |  form elements (text fields, textareas, checkboxes, 
       |                 radio buttons, selections, buttons)   
       +--links
       |
       +--anchors
       |
       +--plug-ins (NYI)
       |
       +--applets (NYI)
       |
       +--elements (NYI)

The document  object and all objects above it in the hierarchy are always present. Everything below the document  object, such as forms, form elements, and anchors, are created based on the contents of the HTML page. For example, a form  object is created for each form in the document.

NOTE: Currently (in beta2), you must refer to forms as an array: The first form is document.forms[0], the second is document.forms[1], and so on. Ultimately, you will be able to name forms and refer to them by their names.

To refer to specific properties of these objects, you must specify the object name and all its ancestors. For example, suppose you have a page with one form, and the form contains this text field: 

<INPUT TYPE="text" NAME="quantity" onChange="...">
Then a form element object would be created that you would refer to as 
document.forms[0].quantity
You would refer to the value property of this object as 
document.forms[0].quantity.value

JavaScript Event Handlers

Events are actions that occur, usually as a result of some user action. For example, a button click is an event, as is giving focus to a form element. Event handlers are scripts that are executed automatically when an event occurs. Event handlers are written in HTML as attributes of form elements to which you assign JavaScript code to execute when the event occurs.

For example, suppose you have created a JavaScript function called compute(). You can cause the script to execute when the user clicks on a button by assigning its onClick attribute to the function call, as follows:

Notice the use of this.form to refer to the current form. The keyword this refers to the current object; in the above example, it would be the button object. The construct this.form then refers to the form containing the button. In the above example, the onClick event handler is a call to the compute() function, with this.form, the current form, as the parameter to the function. Instead of calling a function, you can put any JavaScript statements to be executed inside the quotes.

Events apply to form elements as follows:

The following are JavaScript event handlers:

onFocus
JavaScript code to run when the form element is input-focused.
onBlur
JavaScript code to run on loss of input focus.
onSelect
JavaScript code to run when text in a field is selected.
onChange
JavaScript code to run when the field's value is changed.
onSubmit
JavaScript code to run when the form is submitted. Note that submitting the form reloads the page.
onClick
JavaScript code to run when a button is clicked.

JavaScript Methods

A method is a function associated with an object. You execute a method as follows: 

object.method()

The following predefined methods emulate events; they are applicable to form elements if the event they emulate is applicable. See "JavaScript Event Handlers," above.

focus()
Focuses input on object.
blur()
Removes focus input from object.
select()
Selects object's input field.
click()
Clicks on anchor or button object.
enable()
Enables input focus (ungray the element). NYI.
disable()
Disables input focus (gray out the element). NYI.

Window Object

A window object is the top-level object for each document.

Properties

frames[index]
Array of child frame windows, in the order defined in the source.
frames.length
The number of child frames defined.
self
The current window.
parent
The parent (frameset) window
top
The top-most ancestor window, which is its own parent.

Methods

alert("string")
Display an Alert dialog box with string message.
confirm("string")
Display a Confirm (OK/Cancel) dialog box with the specified string as message. Returns true if user chooses OK and false if user chooses Cancel.
open("URL", "name")
Open a new client window, give it the specified name, and load the specified URL.
close()
Close the window.

Location Object

The location object contains information on the current URL.

Properties

href
The entire URL as a JavaScript string.
protocol
The substring up to and including the first colon.
host
The hostname:port part.
hostname
The hostname part.
port
The port, if any, else "".
path
The stuff after the third slash.
hash
Any CGI stuff after #.
search
Any CGI stuff after ?.
post
Any post headers. NYI.

Methods

toString()
Returns location.href, so you can use location as a string without typing ".href".
assign()
Sets location.href so you don't have to type ".href" complements toString().

History Object

The history contains information on the URLs that the client has visited. This information is stored in a history list, and is accessible through the Go menu in the Navigator.

Properties

back
URL of previous history entry.
forward
URL of next history entry.
current
URL of current page.
length
Length of the history list.

Methods

go(delta)
The argument delta is an integer. If delta is greater than zero, then it loads the URL that is that number of entries forward in the history list; otherwise, it loads the URL that is that number of entries backward in the history list.
go("string")
Go to the newest history entry whose title or URL contains string as a substring; substring matching is case-insensitive.
toString()
Return a string consisting of an HTML table with links to all entries in the history list.

Document Object

The document object contains information on the current document.

Properties

title
Current document title (if undefined, "Untitled").
location
The full URL of the document.
lastmodified
A string containing the last-modified date.
loadedDate
NYI.
referer
NYI.
bgColor
RGB value of background color, expressed as a hexidecimal triplet.
fgColor
RGB value of foreground (text) color, expressed as a hexidecimal triplet.
linkColor
RGB value for color of hyperlinks, expressed as a hexidecimal triplet.
vlinkColor
RGB value for color of visited links, expressed as a hexidecimal triplet.
alinkColor
RGB value for color of activated links (after mouse-button down, but before mouse-button up), expressed as a hexidecimal triplet.
forms[index]
Array of form objects, in source order. There will be a form object for each form in the document.
forms.length
The number of form objects in this document.
links[index]
Array objects corresponding to all HREF links in source order.
links.length
The number of link objects (HREF links) in this document.
anchors[index]
Array of objects corresponding to named anchors ( tags) in source order.
anchors.length
The number of anchor objects (named anchors) in this document.

Methods

write()
Write HTML to the current window, in sequence with the HTML containing this SCRIPT. SCRIPTs have no effect on paragraphs or other structures in which they may occur.
writeln()
The same as write(), but adds a carriage return. Note that this only affects preformatted text (inside a 
 or  tag). 

<dt><b>clear( )</b> 

<dd>Clears the window. 

<dt><b>open("MIME type")</b> 

<dd>NYI. 

<dt><b>close( )</b> 

<dd>Closes the window. NYI.

</dl>



<!----------------------------------------------------------------------------!>

<p>

<hr>

<a name="forms">

<h2>Forms</h2> </a>

<P>

Each form in a document corresponds to a distinct object.

These objects are maintained in an array called <i>forms</i>, so the first form
in a document is

<i>document.forms[0]</i>, the second is <i>document.forms[1]</i>, and so on. 
You then 

refer to the form elements in each form by that name.  For example, you would
refer to

a text field named 

<i>quantity</i> in the second form as:

<pre>

document.forms[1].quantity

</pre>

You would refer to the value property of this form element object as:

<pre>

document.forms[1].quantity.value

</pre>



<h3>Properties</h3>



<dl>

<dt><b>name</b> 

<dd>String value of NAME attribute.  NYI.

<dt><b>method</b> 

<dd>Value of METHOD attribute, "get" or "post" (0 or 1).



<dt><b>action</b> 

<dd>String value of ACTION attribute. 

<dt><b>target</b> 

<dd>Window targeted for form response after the form has been submitted. </dl>



<h3>Event Handlers</h3>



<dl>

<dt><b>onSubmit()</b> 

<dd>Method, JavaScript code to run when the form is submitted. </dl>



<h3>Methods</h3>



<dl>

<dt><b>submit()</b> 

<dd>Submits the form. </dl>



<!----------------------------------------------------------------------------!>

<p>

<hr>

<a name="text_elements">

<h3>Text elements</h3></a>

<P>

The <I>text elements</I>, the text and the textarea, 

share the same properties, methods, and event handlers. They are

defined in HTML as follows:



<XMP>

<TEXTAREA NAME="textarea1" ROWS=4 COLS=50 WRAP=soft
onChange="update(this.form);">

This is a whole bunch of random text....  

</TEXTAREA>








The first element is a text element, and the second is a textarea element.




Properties








name 


String, the value of the NAME attribute. 


value 


String, the contents of the field. 


defaultValue 


String, the initial contents of the field. 





Methods






focus() 


Focuses input on object. 


blur() 


Removes focus input from object. 


select() 


Selects object's input field. 







Event Handlers








onFocus 


Executed when input focus enters the field, either by tabbing in or by
clicking but

not selecting in the field. 


onBlur 


Executed when input focus leaves the field. 


onSelect 


Executed when the field is input-focused by selecting some

of its text value. 


onChange 


Executed when input focus exits the field after the user

modifies its text (so JavaScript code knows to validate something). 















Checkboxes





A checkbox  is basically a toggle switch that the user can select
to be on or off.

It is defined as in the following example:






<INPUT TYPE="checkbox" NAME="CheckOption1" CHECKED onClick="update(this.form)">
Option Text






Properties








name 


String, reflection of the NAME attribute. 


value 


String, "on" if item is checked; "off" otherwise.


status 


Boolean, false if not checked, true if checked.


defaultStatus 


Boolean property that indicates if the element is selected by default,

by the CHECKED attribute.





Event Handlers








onClick 


JavaScript code to run when user checks or unchecks an item.







Methods








click() 


Select the checkbox, causing it to be "on".

















Radio buttons





Radio buttons  all have the same NAME attribute, so the
JavaScript reflection

of the button-group is a single object that has numbered properties starting

from zero, one for each button. 




For example, the following defines a radio button group to choose

among three catalogs, and a text field that defaults to what was chosen

via the radio buttons but that allows the user to type a nonstandard

catalog name as well. The JavaScript automatically sets the catalog name

input field based on the radio buttons. 







onClick="catalog.value = 'top-of-the-line'"> It's really
great! 





onClick="catalog.value = 'middle-of-the-road'"> It's pretty
good. 





onClick="catalog.value = 'bargain-basement'"> It stinks!

 







Properties








name 


String, reflection of the NAME attribute. 


index 


Number, the ordinal number of this field, 0-based. 


value 


String, reflection of the VALUE attribute. 


status 


Boolean, false if not pressed, true if pressed. 


defaultStatus 


Boolean property that indicates if the element is selected by default,

by the CHECKED attribute.





Event Handlers








onClick 


JavaScript code to run when a button is clicked. 





Methods








click() 


Select a radio button. 

















Selections





A selection element is defined as in the following example:




<SELECT name="select1" onChange='update(this.form)'>

<OPTION> red

<OPTION> green

<OPTION SELECTED> blue

</SELECT>








The corresponding JavaScript object consists of an array of option 
objects,

each of which has the following properties.




Properties








index 


Number identifying the position of the option in the selection, starting
from zero. 


text 


String, reflection of the text after the  tag. 


value 


Reflection of VALUE attribute, sent to server on submit. 


defaultSelected 


Boolean property that indicates if the option is selected by default,

by the presence of the SELECTED attribute in the HTML OPTION tag.


selected 


Boolean property that indicates the current selected state of the option. 







Event Handlers








onFocus 


Executed when input focus enters the field, either by tabbing in or by
clicking but

not selecting in the field. 


onBlur 


Executed when input focus leaves the field. 


onChange 


Executed when input focus exits the field after the user

modifies its text (so JavaScript code knows to validate something). 







Methods








click() 


Select a radio button.

Buttons

There are three kinds of buttons in HTML forms:

  • Submit buttons, that cause the form to be submitted
  • Reset buttons, that reset all elements in the form to their defaults
  • Custom buttons, to perform any other function

For all of these buttons, the VALUE attribute specifies the text to display on the face of the button.

A submit button is defined as in the following example:

<INPUT TYPE="submit" VALUE="Submit Query" NAME="SubmitButton">

Clicking on this button will submit the form to the program specified by the ACTION attribute of the form. This action will always load a new page into the client; it may be the same as the current page, if the action so specifies.

A reset button is defined as in this example:

<INPUT TYPE="reset" VALUE="Clear Form">

A custom button is defined as in this example:

<INPUT TYPE="button" VALUE="Calculate" NAME="CalcButton" onClick="myfunction(this.form)">

A custom button does not neccessarily load a new page into the client; it merely executes the script specified by the onClick attribute. In this example, myfunction() is a JavaScript function.

Properties

value
A string that is the same as the VALUE attribute.
name
A string that is the same as the NAME attribute.

Event Handlers

onClick
JavaScript code to run when a button is clicked.

Methods

click()
Select the button.

Links

A hyperlink is defined as in the following example:

<A HREF="http://www.netscape.com">Netscape Home Page</A>

All links in a document are maintained in the links array; the first link is link[0], the second is link[1], and so on. Each link object is a location object.

Anchors

An anchor is defined as in the following example:

<A NAME="topic"><H2>Topic</H2></A>

NYI. -->