See also

Image object; void operator

<<Changed.>>

The arguments property is now a property of the Function object.

Syntax

To specify the arguments array from within a Function object:

this.arguments[index]

Property of

<<New.>>

Object. Lets you create arrays and work with them.

Syntax

1. arrayObjectName = new Array()
2. arrayObjectName = new Array(arrayLength)

1. arrayObjectName.propertyName
2. arrayObjectName.methodName(parameters)

Parameters

arrayObjectName is either the name of a new object or a property of an existing object.

arrayLength is the initial length of the array. You can access this value using the length property

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

None.

Implemented in

Navigator 3.0

Description

The Array object is a built-in JavaScript object.

You can specify an initial length when you create the array. The following code creates an array of five elements:

When you create an array, all of its elements are initially null. The following code creates an array of 25 elements, then assigns values to the first three elements:

An array's length increases if you assign a value to an element higher than the current length of the array. The following code creates an array of length zero, then assigns a value to element 99. This changes the length of the array to 100.

You can construct a dense array of two or more elements starting with index 0 if you define initial values for all elements. A dense array is one in which each element has a value. The following code creates a dense array with three elements:

Properties

The Array object has the following properties:

Property	Description
length	Reflects the number of elements in an array
prototype	Lets you add a properties to an Array object.

Methods

Event handlers

Examples

The following example creates an array, msgArray, with a length of 0, then assigns values to msgArray[0] and msgArray[99], changing the length of the array to 100.

See also the examples for the onError event handler.

See also

Image object

<<New.>>

Method. Returns the angle (theta component) of the polar coordinate (r,theta) that corresponds to the specified cartesian coordinate (x,y).

Note: This method existed in 2.0 but was undocumented.

Syntax

Math.atan2(x,y)

Parameters

x is either a numeric expression or a property of an existing object, representing the cartesian x-coordinate.

y is either a numeric expression or a property of an existing object, representing the cartesian y-coordinate.

Method of

Math

Implemented in

Navigator 2.0

Description

The atan2 method returns a numeric value.

Examples

The following function returns the angle of the polar coordinate:

If you pass getAtan2 the values (90,15), it returns 1.4056476493802699; if you pass it the values (15,90), it returns 0.16514867741462683.

See also

acos, asin, atan, cos, sin, tan methods

<<Changed.>>

The blur method is now a method of the frame and window objects. The blur method removes focus from the window or frame. Removing focus sends a window to the background in most windowing systems.

Syntax

The following syntax has been added for the blur method:

frameReference.focus()
windowReference.blur()

Parameters

frameReference is a valid way of referring to a frame, as described in the Frame object.

windowReference is a valid way of referring to a window, as described in the Window object.

Method of

<<New.>>

Property. A string specifying the width, in pixels, of an image border.

Syntax

imageName.border

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The border property reflects the BORDER attribute of the <IMG> tag. For images created with the Image() constructor, the value of the border property is 0.

border is a read-only property.

Examples

The following function displays the value of an image's border property if the value is not zero.

See also

height, hspace, vspace, width properties

<<Changed.>>

The following properties have been added to the Button object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The following properties have been added to the Checkbox object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The close method now closes only windows opened by JavaScript using the open method. If you attempt to close any other window, a confirm is generated, which lets the user choose whether the window closes. This is a security feature to prevent "mail bombs" containing self.close(). However, if the window has only one document (the current one) in its session history, the close is allowed without any confirm. This is a special case for one-off windows that need to open other windows and then dispose of themselves.

<<New.>>

Property. A boolean value that indicates whether Navigator has completed its attempt to load an image.

Syntax

imageName.complete

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

complete is a read-only property.

Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Clicking another button lets the user see the current value of the complete property.

See also

lowsrc, src properties

<<Changed.>>

The following properties have been added to the Date object:

Property	Description
prototype	Lets you add a properties to a Date object.

<<Changed.>>

The defaultSelected property is now a property of the Option object.

Syntax

The following syntax has been added for the defaultSelected property:

optionName.defaultSelected

Parameters

Property of

<<New.>>

Property. This property is currently documented in Determining installed plug-ins with JavaScript.

Syntax

1. navigator.mimeTypes[index].description
2. navigator.mimeTypes[mimeTypeName].description
3. navigator.plugins[index].description
4. navigator.plugins[pluginName].description

Implemented in

Navigator 3.0

<<Changed.>>

Syntax

The following syntax has been added for the Document object:

<BODY>
...
   [onBlur="handlerText"]
   [onFocus="handlerText"]
...
</BODY>

Description

The onBlur and onFocus event handlers are specified in the <BODY> tag but are actually event handlers for the window object.

Properties

The following properties have been added to the Document object:

Property	Description
applets	An array reflecting all the applets in a document
embeds	An array reflecting all the plugins in a document
images	An array reflecting all the images in a document

The following objects are now properties of the Document object

Additional description

The following discussions will be added to the documentation for the Document object; however, this is not new functionality.

Do not use location as a property of the Document object; use the document.URL property instead. The document.location property, which is a synonym for document.URL, will be removed in a future release.

You can clear the document pane (and remove the text, form elements, and so on so they do not redisplay) by using document.close(); document.open(); document.write(). You can omit the document.open() call if you are writing text or HTML, since write does an implicit open of that mime type if the document stream is closed.

<<New.>>

Property. Returns a reference to the Plugin object for the plug-in that handles that MIME type, or NULL if no plug-in handles that MIME type.

This property is currently documented in Determining installed plug-ins with JavaScript.

<<New.>>

Property. A plug-in's file name. This property is currently documented in Determining installed plug-ins with JavaScript.

Syntax

1. navigator.plugins[index].filename
2. navigator.plugins[pluginName].filename

Property of

Plugin

Implemented in

Navigator 3.0

<<New.>>

Object. A file upload element on an HTML form. A file upload element lets the user supply a file as input.

HTML syntax

<INPUT
   TYPE="file"
   NAME="fileUploadName">

HTML attributes

NAME="fileUploadName" specifies the name of the FileUpload object (this is not the name of the file to upload). You can access this value using the name property.

Syntax

fileUploadName.propertyName

Parameters

fileUploadName is the value of the NAME attribute of a FileUpload object.

propertyName is one of the properties listed below.

Property of

Form

Implemented in

Navigator 3.0

Description

You can place a FileUpload object on a form but you cannot use JavaScript to modify it in any way.

Properties

The FileUpload object has the following properties:

Property	Description
name	Reflects the NAME attribute
value	Reflects the current value of the file upload element's field; this corresponds to the name of the file to upload. This is a read-only property.

Methods

Event handlers

Examples

The following example places a FileUpload object on a form and provides two buttons that let the user display current values of the name and value properties.

See also

text object

<<Changed.>>

The focus method is now a method of the frame and window objects. The focus method gives focus to a window or frame. Giving focus brings a window forward in most windowing systems.

Syntax

The following syntax has been added for the focus method:

frameReference.focus()
windowReference.focus()

Parameters

frameReference is a valid way of referring to a frame, as described in the Frame object.

windowReference is a valid way of referring to a window, as described in the Window object.

Method of

<<Changed.>>

The following has been added to the Form object's syntax:

[onReset="handlerText"]

The following objects are now properties of the Form object

The following methods have been added to the Form object

The following event handlers have been added to the Form object

<<Changed.>>

Syntax

The following syntax has been added for defining an onBlur or onFocus event handler for a frameset (framesets are windows that have non-empty frames arrays):

<FRAMESET>
...
   [<FRAME SRC="locationOrURL" NAME="frameName">]
   [onBlur="handlerText"]
   [onFocus="handlerText"]
...
</FRAMESET>

The following syntax has been added for defining an onBlur or onFocus event handler for a frame (for frames, you cannot specify these event handlers in HTML):

frameReference.onblur=errorHandler
frameReference.onfocus=errorHandler

Parameters

frameReference is a valid way of referring to a frame, as described in the Frame object.

errorHandler is the keyword null, the name of an error-handling function, or a variable or property that contains null or a valid function reference.

Description

To create an onBlur or onFocus event handler for a frame, you must set the onblur or onfocus property and specify it in all lowercase (you cannot specify it in HTML).

Event handlers

The following event handlers have been added to framesets and the Frame object:

<<New.>>

Object. Specifies a string of JavaScript code to be compiled as a function.

Syntax

functionTarget = new Function ([arg1, arg2, ... argn], functionBody)

Parameters

functionTarget is the name of a variable or a property of an existing object. It can also be an object followed by a lowercase event handler name, such as window.onerror.

arg1, arg2, ... argn are string arguments to be used by the function as formal argument names.

functionBody is a string specifying the JavaScript code to be compiled as the function body.

Implemented in

Navigator 3.0

Description

Function objects are evaluated each time they are used. This is less efficient than declaring a function and calling it within your code, because declared functions are compiled.

Specifying a variable value with a Function object

The following code assigns a function to the variable setBGColor. This function sets the current document's background color.

To call the Function object, you can specify the variable name as if it were a function. The following code executes the function specified by the setBGColor variable:

You can assign the function to an event handler in either of the following ways:

Creating the variable setBGColor shown above is similar to declaring the following function:

Assigning a function to a variable is similar to declaring a function, but they have differences:

• When you assign a function to a variable using var setBGColor = new Function("..."), setBGColor is a variable for which the current value is a reference to the function created with new Function().
• When you create a function using function setBGColor() {...}, setBGColor is not a variable, it is the name of a function.

Specifying arguments in a Function object

The following code specifies a Function object that takes two arguments.

The string arguments "x" and "y" are formal argument names that are used in the function body, "return x * y".

The following code shows several ways to call the function multFun:

You cannot call the function multFun in an event handler property, because these properties cannot take arguments. For example, you cannot call the function multFun by setting a button's onclick property as follows:

Specifying an event handler with a Function object

The following code assigns a function to a window's onFocus event handler (the event handler must be spelled in all lowercase):

Once you have a reference to a function object, you can use it like a function and it will convert from an object to a function:

Event handlers do not take arguments, you cannot declaring any in the Function() constructor.

Properties

The Function object has the following properties:

Property	Description
arguments	Corresponds to elements of a function.
prototype	Lets you add a properties to a Function object.

Methods

Event handlers

Examples

The following example creates onFocus and onBlur event handlers for a frame. This code exists in the same file that contains the <FRAMESET> tag. Note that this is the only way to create onFocus and onBlur event handlers for a frame, because you cannot specify the event handlers in the <FRAME> tag.

<<Changed.>>

The hash property is now a property of the Area object.

Syntax

The following syntax has been added for the hash property:

areaName.hash

Parameters

Property of

Description

You can set the hash property at any time.

<<New.>>

Property. A string specifying the height of an image either in pixels or as a percentage of the window height.

Syntax

imageName.height

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The height property reflects the HEIGHT attribute of the <IMG> tag. For images created with the Image() constructor, the value of the height property is the actual, not the displayed, height of the image.

height is a read-only property.

Examples

The following function displays the values of an image's height, width, hspace, and vspace properties.

See also

border, hspace, vspace, width properties

<<Changed.>>

The following properties have been added to the Hidden object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The host property is now a property of the Area object.

Syntax

The following syntax has been added for the host property:

areaName.host

Parameters

Property of

Description

You can set the host property at any time.

<<Changed.>>

The hostname property is now a property of the Area object.

Syntax

The following syntax has been added for the hostname property:

areaName.hostname

Parameters

Property of

Description

You can set the hostname property at any time.

<<Changed.>>

The href property is now a property of the Area object.

Syntax

The following syntax has been added for the href property:

areaName.href

Parameters

Property of

Description

You can set the href property at any time.

<<New.>>

Property. A string specifying a margin in pixels between the left and right edges of an image and the surrounding text.

Syntax

imageName.hspace

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The hspace property reflects the HSPACE attribute of the <IMG> tag. For images created with the Image() constructor, the value of the hspace property is 0.

hspace is a read-only property.

Examples

See the examples for the height property.

See also

border, height, vspace, width properties

<<New.>>

Object. An image on an HTML form.

HTML syntax

To define an image, use standard HTML syntax with the addition of the onAbort and onLoad event handlers:

<IMG
   [NAME="imageName"]
   SRC="Location"
   [LOWSRC="Location"]
   [HEIGHT="Pixels"|"Value"%]
   [WIDTH="Pixels"|"Value"%]
   [HSPACE="Pixels"]
   [VSPACE="Pixels"]
   [BORDER="Pixels"]
   [ALIGN="left"|"right"|
      "top"|"absmiddle"|"absbottom"|
      "texttop"|"middle"|"baseline"|"bottom"]
   [ISMAP]
   [USEMAP="Location#MapName"]
   [onAbort="handlerText"]
   [onError="handlerText"]
   [onLoad="handlerText"]>

HTML attributes

NAME="imageName" specifies the name of the Image object. You can access this value using the name property.

SRC="Location" specifies the URL of the image to be displayed in the document. You can access this value using the src property.

LOWSRC="Location" specifies the URL of a low-resolution version of the image to be displayed in the document. Navigator loads this smaller image and then replaces it with the larger image specified by SRC. You can access this value using the lowsrc property.

HEIGHT="Pixels"|"Value"% specifies the height of the image either in pixels or as a percentage of the window height. If necessary, Navigator scales the image to fit the space specified by this attribute. You can access this value using the height property.

WIDTH="Pixels"|"Value"% specifies the width of the image either in pixels or as a percentage of the window width. If necessary, Navigator scales the image to fit the space specified by this attribute. You can access this value using the width property.

HSPACE="Pixels" specifies a margin in pixels between the left and right edges of the image and the surrounding text. This attribute applies only to images that use "left" or "right" as the value of the ALIGN attribute. You can access this value using the hspace property.

VSPACE="Pixels" specifies a margin in pixels between the top and bottom edges of the image and the surrounding text. This attribute applies only to images that use "left" or "right" as the value of the ALIGN attribute. You can access this value using the vspace property.

BORDER="Pixels" specifies the width, in pixels, of an image border. You can suppress the border by setting its value to 0; however, if you suppress the border of an image that appears within an anchor, users will not see a colored border indicating that the image is a hyperlink. You can access this value using the border property.

ALIGN specifies the alignment of the image in relation to the surrounding text. Images that are aligned as "left" or "right" float into the next available space on the left or right side of the page, and cause text to wrap around them. Other ALIGN values place the image in a line of text and do not cause the text to wrap. If omitted, "bottom" is used.

ISMAP specifies the image as a server-side image map.

USEMAP="Location#MapName" specifies the image as a client-side image map. This attribute must specify the URL of the file that contains the map definition, followed by a # symbol, and then the name of the map. For example, USEMAP="http://www.HomeWorld.com/maplist.html#areamap".

Syntax

To create an Image object:

imageName = new Image([width, height])

To use an Image object's properties:

1. imageName.propertyName
2. document.images[index].propertyName
3. formName.elements[index].propertyName

To define an event handler for an Image object created with the Image() constructor:

imageName.onabort = handlerFunction
imageName.onerror = handlerFunction
imageName.onload = handlerFunction

Parameters

imageName is either the name of a new object or a property of an existing object. When using an Image object's properties, imageName is the value of the NAME attribute of an Image object

width is the image width, in pixels.

height is the image height, in pixels.

formName is either the value of the NAME attribute of a Form object or an element in the forms array.

index, when used with the images array is an integer or string representing an Image object. index, when used with the elements array, is an integer representing an Image object on a form.

propertyName is one of the properties listed below.

handlerFunction is the keyword null, the name of a function, or a variable or property that contains null or a valid function reference.

Property of

Document

Implemented in

Navigator 3.0

Description

The position and size of an image in a document are set when the document is displayed in Navigator and cannot be changed. You can change the image displayed by setting the src and lowsrc properties. (See the descriptions of src and lowsrc.)

You can use JavaScript to create an animation with an Image object by repeatedly setting the src property, as shown in Example 4 below. JavaScript animation is slower than GIF animation, because with GIF animation the entire animation is in one file; with JavaScript animation, each frame is in a separate file, and each file must be loaded across the network (host contacted and data transferred).

Image objects do not have onClick, onMouseOut, and onMouseOver event handlers. However, if you define an Area object for the image or place the <IMG> tag within a Link object, you can use the Area or Link object's event handlers. See the Area and Link objects.

The Image() constructor

The primary use for an Image object created with the Image() constructor is to load an image from the network (and decode it) before it is actually needed for display. Then when you need to display the image within an existing image cell, set the src property of the displayed image to the same value as that used for the prefetched image, as follows.

The resulting image will be obtained from cache, rather than loaded over the network. You can use this technique to create smooth animations, or you could display one of several images based on form input.

The images array

You can reference the images in your code by using the images array. This array contains an entry for each Image object (<IMG> tag) in a document in source order (images created with the Image() constructor are not included in the images array). For example, if a document contains three images, these images are reflected as document.images[0], document.images[1], and document.images[2].

To use the images array:

1. document.images[index]
2. document.images.length

To obtain the number of images in a document, use the length property: document.images.length.

Elements in the images array are read-only. For example, the statement document.images[0]="logo.gif" has no effect.

Properties

The Image object has the following properties:

Property	Description
border	Reflects the BORDER attribute
complete	Boolean value indicating whether Navigator has completed its attempt to load the image
height	Reflects the HEIGHT attribute
hspace	Reflects the HSPACE attribute
lowsrc	Reflects the LOWSRC attribute
name	Reflects the NAME attribute
prototype	Lets you add a properties to an Image object.
src	Reflects the SRC attribute
vspace	Reflects the VSPACE attribute
width	Reflects the WIDTH attribute

Note: The border, hspace, name, and vspace properties are not meaningful for images created with the Image() constructor.

The images array has the following properties:

Property	Description
length	Reflects the number of images in a document

Methods

Event handlers

Examples

Example 1. Refer to an image by its name. If you refer to an image by its name, you must include the form name if the image is on a form. For example, suppose the following image is defined:

The following code refers to the image if it is on a form:

The following code refers to the image if is not on a form:

Example 2. Create an image with the Image() constructor. The following example creates an Image object, myImage, that is 70 pixels wide and 50 pixels high. If the source URL, seaotter.gif, does not have dimensions of 70x50 pixels, it is scaled to that size.

If you omit the width and height arguments from the Image() constructor, myImage is created with dimensions equal to that of the image named in the source URL.

Example 3. Display an image based on form input. In the following example, the user selects which image is displayed. The user orders a shirt by filling out a form. The image displayed depends on the shirt color and size that the user chooses. All possible image choices are pre-loaded to speed response time. When the user clicks the button to order the shirt, the allShirts function displays the images of all the shirts.

Example 4. JavaScript animation. The following example uses JavaScript to create an animation with an Image object by repeatedly changing the value the src property. The script begins by preloading the ten images that make up the animation (!image1.gif, !image2.gif, !image3.gif, and so on). When the Image object is placed on the document with the <IMG> tag, !image1.gif is displayed and the onLoad event handler starts the animation by calling the animate function. Notice that the animate function does not call itself after changing the src property of the Image object. This is because when the src property changes, the image's onLoad event handler is triggered and the animate function is called.

See also the examples for the onAbort, onError, and onLoad event handlers.

See also

Area, Link objects; onClick, onMouseOut, onMouseOver event handlers

<<Changed.>>

The index property is now a property of the Option object.

Syntax

The following syntax has been added for the index property:

optionName.index

Parameters

Property of

<<Changed.>>

The isNaN function now works on all platforms.

For information on isNaN, see the isNaN function.

<<New.>>

Method. Specifies whether Java is enabled.

Syntax

navigator.javaEnabled()

Method of

navigator

Implemented in

Navigator 3.0

Description

javaEnabled returns true if Java is enabled, false otherwise. The user can enable or disable Java by choosing Network Preferences from the Navigator's Options menu.

Examples

The following code executes function1 if Java is enabled; otherwise it executes function2.

See also

appName, appCodeName, userAgent properties

<<New.>>

Method. Joins all elements of an array into a string.

Syntax

arrayName.join(separator)

Parameters

arrayName is the name of an Array object or a property of an existing object.

separator specifies a string to separate each element of the array. The separator is converted to a string if necessary. If omitted, the array elements are separated with a comma (,).

Method of

Array

Implemented in

Navigator 3.0

Description

The string conversion of all array elements are joined into one string.

Examples

The following example creates an array, a with three elements, then joins the array three times: using the default separator, then a comma and a space, and then a plus.

This code produces the following output:

See also

reverse, sort methods

<<Changed.>>

The length property is now a property of the following:

Syntax

The following syntax has been added for the length property:

1. arrayName.length
2. images.length
3. navigator.plugins[index].length
4. navigator.plugins[pluginName].length

Parameters

Description

• The number of elements in an array.
• The number of images in a document.

For arrays, you can set the length property to truncate an array at any time. You cannot extend an array; for example, if you set length to 3 when it is currently 2, the array will still contain only 2 elements. For information on other ways to change the length of an array, see the Array object.

Examples

Property of

<<Changed.>>

The links array now contains Area objects that are created with <AREA HREF="...">.

The following event handlers have been added to the Link object:

Additional description

The following discussion will be added to the documentation for the Link object; however, this is not new functionality.

You can use a Link object to execute a JavaScript function rather than link to a hypertext reference by specifying the javascript: URL protocol for the link's HREF attribute. You might want to do this if the link surrounds an Image object and you want to execute JavaScript code when the image is clicked. Or you might want to use a link instead of a button to execute JavaScript code.

For example, when a user clicks the following links, the slower and faster functions execute:

You can use a Link object to do nothing rather than link to a hypertext reference by specifying the javascript:void(0) URL protocol for the link's HREF attribute. You might want to do this if the link surrounds an Image object and you want to use the link's event handlers with the image. When a user clicks the following link or image, nothing happens:

See also

void

<<Changed.>>

Syntax

The following syntax has been added to the Location object:

[windowReference.]location.methodName(parameters)

Methods

The following methods have been added to the Location object:

Additional description

The following discussion will be added to the documentation for the Location object; however, this is not new functionality.

In event handlers, you must specify window.location instead of simply using location. Due to the scoping of static objects in JavaScript, a call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

Do not use location as a property of the Document object; use the document.URL property instead. The document.location property, which is a synonym for document.URL, will be removed in a future release.

<<New.>>

Property. A string specifying the URL of a low-resolution version of an image to be displayed in a document.

Syntax

imageName.lowsrc

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The lowsrc property initially reflects the LOWSRC attribute of the <IMG> tag. Navigator loads the smaller image specified by lowsrc and then replaces it with the larger image specified by the src property. You can change the lowsrc property at any time.

Examples

See the examples for the src property.

See also

complete, src properties

<<Changed.>>

The following methods have been added to the Math object:

<<New.>>

An array of all MIME types supported by the client. This array is currently documented in Determining installed plug-ins with JavaScript.

Property of

navigator

Implemented in

Navigator 3.0

<<Changed.>>

The name property is now a read-only property of the following objects:

Syntax

The following syntax has been added for the name property:

1. fileUploadName.name
2. imageName.name
3. navigator.plugins[index].name
4. navigator.plugins[pluginName].name

Parameters

imageName is either the value of the NAME attribute of a Image object or an element in the images array.

index is an integer representing a plug-in a document or a string containing the name of a Plugin object

Description

For the FileUpload object, name is a read-only property.

For images created with the Image() constructor, the value of the name property is null.

Property of

See also

<<Changed.>>

The following objects are now properties of the navigator object

The following methods have been added to the navigator object

<<New.>>

Event handler. An abort event occurs when the user aborts the loading of an image (for example by clicking a link or clicking the Stop button). The onAbort event handler executes JavaScript code when an abort event occurs.

See the relevant objects for the onAbort syntax.

Implemented in

Navigator 3.0

Event handler of

Examples

In the following example, an onAbort handler in an Image object displays a message when the user aborts the image load:

See also

onError, onLoad event handlers

<<Changed.>>

The onBlur event handler is now an event handler of windows, frames, and framesets.

Event handler of

Description

For windows, frames, and framesets, the onBlur event handler specifies JavaScript code to execute when a window loses focus.

A frame's onBlur event handler overrides an onBlur event handler in the <BODY> tag of the document loaded into frame.

See the relevant objects for the onBlur syntax.

Note: On Windows platforms, placing an onBlur event handler in a <FRAMESET> tag has no effect.

Examples

Example 1. Change the background color of a window. In the following example, a window's onBlur and onFocus event handlers change the window's background color depending on whether the window has focus.

Example 2. Change the background color of a frame. The following example creates four frames. The source for each frame, onblur2.html has the <BODY> tag with the onBlur and onFocus event handlers shown in Example 1. When the document loads, all frames are "lightgrey". When the user clicks a frame, the onFocus event handler changes the frame's background color to "antiquewhite". The frame that loses focus is changed to "lightgrey". Note that the onBlur and onFocus event handlers are within the <BODY> tag, not the <FRAME> tag.

The following code has the same effect as the previous code, but is implemented differently. The onFocus and onBlur event handlers are associated with the frame, not the document. The onBlur and onFocus event handlers for the frame are specified by setting the onblur and onfocus properties. For information on using new to specify a string of JavaScript code to be compiled as a function, see the Function object.

Example 3. Close a window. In the following example, a window's onBlur event handler closes the window when the window loses focus.

<<Changed.>>

For checkboxes, links, radio buttons, reset buttons, and submit buttons, the onClick event handler can now return false to cancel the action normally associated with a click event. Returning false in an onClick event handler for a button has no effect.

Note: On Windows platforms, returning false in an onClick event handler for a reset button has no effect.

For example, click the following hyperlink and then choose Cancel. When you choose Cancel, the new page is not loaded.

Netscape

The code for this example looks as follows:

Examples

The following example creates a checkbox with an onClick event handler. The event handler displays a confirm that warns the user that checking the checkbox purges all files. If the user chooses Cancel, the onClick event handler returns false and the checkbox is not checked.

<<New.>>

Event handler. An error event occurs when the loading of a document or image causes an error. The onError event handler executes JavaScript code when an error event occurs.

The onError event handler can be any of the following:

• null to suppress all error dialogs. Setting window.onerror to null means your users won't see JavaScript errors caused by your own code.
• The name of a function that handles errors (arguments are message text, URL, and line number of the offending line). To suppress the standard JavaScript error dialog, the function must return true. See Example 3 below.
• A variable or property that contains null or a valid function reference.

If you write an error-handling function, you have three options for reporting errors:

• Trace errors but let the standard JavaScript dialog report them (use an error handling function that does not return true)
• Report errors yourself and disable the standard error dialog (use an error handling function that returns true)
• Turn off all error reporting (set the onError event handler to null)

An error event occurs only when a JavaScript syntax or runtime error occurs, not when a Navigator error occurs. For example, if you try set window.location.href='notThere.html' and notThere.html does not exist, the resulting error message is a Navigator error message; therefore, an onError event handler would not intercept that message.

See the relevant objects for the onError syntax.

Implemented in

Navigator 3.0

Event handler of

Examples

Example 1. Null event handler. In the following <IMG> tag, the code onError="null" suppresses error messages if errors occur when the image loads.

Example 2. Null event handler for a window. The onError event handler for windows cannot be expressed in HTML. Therefore, you must spell it all lowercase and set it in a <SCRIPT> tag. The following code assigns null to the onError handler for the entire window, not just the Image object. This suppresses all JavaScript error messages.

In the following example, window.onerror=null suppresses all error reporting. Without onerror=null, the code would cause a stack overflow error.

Example 3. Error handling function. The following example defines a function, myOnError, that intercepts JavaScript errors. The function uses three arrays to store the message, URL, and line number for each error. When the user clicks the Display Error Report button, the displayErrors function opens a window and creates an error report in that window. Note that the function returns true to suppress the standard JavaScript error dialog.

This example produces the following output:

Error Report

Error in file: file:///c%7C/temp/onerror.html
Line number: 34
Message: unterminated string literal

Error in file: file:///c%7C/temp/onerror.html
Line number: 34
Message: missing ) after argument list

Error in file: file:///c%7C/temp/onerror.html
Line number: 30
Message: noSuchFunction is not defined

Example 4. Event handler calls a function. In the following <IMG> tag, the onError event handler calls the function badImage if errors occur when the image loads.

See also

onLoad event handler

<<Changed.>>

The onFocus event handler is now an event handler of windows, frames, and framesets.

Event handler of

Description

For windows, frames, and framesets, the onFocus event handler specifies JavaScript code to execute when a window gets focus.

A frame's onFocus event handler overrides an onFocus event handler in the <BODY> tag of the document loaded into frame.

Note that placing an alert in an onFocus event handler results in recurrent alerts: when you press OK to dismiss the alert, the underlying window gains focus again and produces another focus event.

See the relevant objects for the onFocus syntax.

Note: On Windows platforms, placing an onFocus event handler in a <FRAMESET> tag has no effect.

Examples

See the examples for the onBlur event handler.

<<Changed.>>

The onLoad event handler is now an event handler of the following:

Event handler of

Description

For images, the onLoad event handler indicates the script to execute when an image is displayed. Do not confuse displaying an image with loading an image. You can load several images, then display them one by one in the same Image object by setting the object's src property. If you change the image displayed in this way, the onLoad event handler executes every time an image is displayed, not just when the image is loaded into memory.

If you specify an onLoad event handler for an Image object that displays a looping GIF animation (multi-image GIF), each loop of the animation triggers the onLoad event, and the event handler executes once for each loop.

You can use the onLoad event handler to create a JavaScript animation by repeatedly setting the src property of an Image object. See the Image object for information.

Examples

Example 1. Display alert when image loads. The following example creates two Image objects, one with the Image() constructor and one with the <IMG> tag. Each Image object has an onLoad event handler that calls the displayAlert function, which displays an alert. For the image created with the <IMG> tag, the alert displays the image name. For the image created with the Image() constructor, the alert displays a message without the image name. This is because the onLoad handler for an object created with the Image() constructor must be the name of a function, and it cannot specify parameters for the displayAlert function.

Example 2. Looping GIF animation. The following example displays an image, birdie.gif, that is a looping GIF animation. The onLoad event handler for the image increments the variable cycles, which keeps track of the number of times the animation has looped. To see the value of cycles, the user clicks the button labeled Count Loops.

Example 3. Change GIF animation displayed. The following example uses an onLoad event handler to rotate the display of six GIF animations. Each animation is displayed in sequence in one Image object. When the document loads, !anim0.html is displayed. When that animation completes, the onLoad event handler causes the next file, !anim1.html, to load in place of the first file. After the last animation, !anim5.html, completes, the first file is again displayed. Notice that the changeAnimation function does not call itself after changing the src property of the Image object. This is because when the src property changes, the image's onLoad event handler is triggered and the changeAnimation function is called.

See also the examples for the Image object.

See also

onAbort, onError event handlers

<<New.>>

Event handler. A mouseOut event occurs each time the mouse pointer leaves an area (client-side image map) or link from inside that area or link. The onMouseOut event handler executes JavaScript code when a mouseOut event occurs.

If the mouse moves from one area into another in a client-side image map, you'll get onMouseOut for the first area, then onMouseOver for the second.

Area objects that use the onMouseOut event handler must include the HREF attribute within the <AREA> tag.

You must return true within the event handler if you want to set the status or defaultStatus properties with the onMouseOver event handler.

See the relevant objects for the onMouseOut syntax.

Implemented in

Navigator 3.0

Event handler of

Examples

See the examples for the Area object.

See also

onMouseOver event handler

<<Changed.>>

Event handler. The onMouseOver event handler is now an event handler of the following:

A mouseOver event occurs once each time the mouse pointer moves over an object or area from outside that object or area. The onMouseOver event handler executes JavaScript code when a mouseOver event occurs.

If the mouse moves from one area into another in a client-side image map, you'll get onMouseOut for the first area, then onMouseOver for the second.

Area objects that use the onMouseOver event handler must include the HREF attribute within the <AREA> tag.

You must return true within the event handler if you want to set the status or defaultStatus properties with the onMouseOver event handler.

See the relevant objects for the onMouseOver syntax.

Examples

See the examples for the Area object.

See also

onMouseOut event handler

<<New.>>

Event handler. A reset event occurs when a user resets a form (clicks a Reset button). The onReset event handler executes JavaScript code when a reset event occurs.

See the relevant objects for the onReset syntax.

Implemented in

Navigator 3.0

Event handler of

Form

Examples

The following example displays a Text object with the default value "CA" and a reset button. If the user types a state abbreviation in the Text object and then clicks the reset button, the original value of "CA" is restored. The form's onReset event handler displays a message indicating that defaults have been restored.

See also

Reset object, reset method

<<Changed.>>

The example for the onSubmit event handler will be changed to the following. This is not new functionality.

<<New.>>

Property. Specifies the window of the calling document when a window is opened using the open method.

Syntax

window.opener

Property of

Window

Implemented in

Navigator 3.0

Description

When a source document opens a destination window by calling the open method, the opener property specifies the window of the source document. Evaluate the opener property from the destination window.

This property persists across document unload in the opened window.

You might want to clear the opener property to free otherwise closed windows in a chain of openers leading to the current one.

You can change the opener property at any time.

Examples

Example 1: close the opener. The following code closes the window that opened the current window.

Example 2: evaluate the name of the opener. A window can determine the name of its opener as follows:

Example 3: change the value of opener. The following code changes the value of the opener property to null. After this code executes, you cannot close the opener window as shown in Example 1.

Example 4: change a property of the opener. The following code changes the background color of the window specified by the opener property.

See also

close, open methods

<<New.>>

Object. A Select object option created using the Option() constructor. For information, see the Select object.

<<Changed.>>

parseFloat now returns "NaN" on all platforms if the first character of the string specified in parseFloat(string) cannot be converted to a number.

For information on parseFloat, see the parseFloat function.

<<Changed.>>

parseInt now returns "NaN" on all platforms if the first character of the string specified in parseInt(string) cannot be converted to a number.

For information on parseInt, see the parseInt function.

<<Changed.>>

The following properties have been added to the Password object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The pathname property is now a property of the Area object.

Syntax

The following syntax has been added for the pathname property:

areaName.pathname

Parameters

Property of

Description

You can set the pathname property at any time.

<<New.>>

Object. Generates output from a plug-in application.

Syntax

<EMBED
   SRC=source
   NAME=appletName
   HEIGHT=height
   WIDTH=width>
   [<PARAM NAME=parameterName VALUE=parameterValue>]
   [ ... <PARAM>]
</EMBED>

Parameters

SRC=source specifies the URL containing the source content.

NAME=appletName specifies the name of the embedded object in the document.

HEIGHT=height specifies the height of the applet in pixels within the browser window.

WIDTH=width specifies the width of the applet in pixels within the browser window.

<PARAM> defines a parameter for the embedded object.

NAME=parameterName specifies the name of the parameter.

VALUE=parameterValue specifies a value for the parameter.

Property of

Document

Implemented in

Navigator 3.0

Description

The embeds array

You can reference the plugins in your code by using the embeds array. This array contains an entry for each Plugin object (<EMBED> tag) in a document in source order. For example, if a document contains three plugins, these plugins are reflected as document.embeds[0], document.embeds[1], and document.embeds[2].

To use the embeds array:

1. document.embeds[index]
2. document.embeds.length

To obtain the number of plugins in a document, use the length property: document.embeds.length.

Elements in the embeds array are read-only. For example, the statement document.embeds[0]="myavi.avi" has no effect.

The plugins array

JavaScript has an array, plugins, that lets you determine whether a user has installed a particular plug-in. Do not confuse the plugins array with the Plugin object and the embeds array. For information on the plugins array, see Determining installed plug-ins with JavaScript.

Properties

Methods

Event handlers

Examples

The following HTML includes an AVI plug-in in a document:

See also

Applet, mimeType objects

<<New.>>

An array of all plug-ins currently installed on the client. This array is currently documented in Determining installed plug-ins with JavaScript.

Property of

navigator

Implemented in

Navigator 3.0

<<Changed.>>

The port property is now a property of the Area object.

Syntax

The following syntax has been added for the port property:

areaName.port

Parameters

Property of

Description

You can set the port property at any time.

<<Changed.>>

The protocol property is now a property of the Area object.

Syntax

The following syntax has been added for the protocol property:

areaName.protocol

Parameters

Property of

Description

You can set the protocol property at any time.

<<New.>>

Property. Defines a property that is shared by all objects of the specified type.

Syntax

objectType.prototype.propertyName = value

Parameters

objectType is the name of the constructor specifying the object type.

propertyName is the name of the property to be created.

value is the property value initially assigned for all objects of the specified objectType.

Property of

prototype is a property of any object created with new, such as the following:

Implemented in

Navigator 3.0

Description

Use the prototype property to explicitly add properties to objects created with the new operator.

For example, you can create Date objects by using the Date() constructor and the new operator. Date.prototype refers to the prototype object for the Date() constructor. If you set a property for the prototype, such as Date.prototype.description, then all objects created with Date() will have the description property, even if the objects already exist.

After you set a property for the prototype, all subsequent objects created with Date() will have the property:

Examples

Example 1. Add a property to a user-defined object. The following example uses the function Car to define a Car object type. It then uses new to create myCar, an instance of the object. The code Car.prototype.wheels=4 adds the wheels property to all instances of the Car object.

<<Changed.>>

The following properties have been added to the Radio object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The Math.random method now works on all platforms. The random number generator is seeded from current time, as in Java.

<<New.>>

Method. Forces a reload of the window's current document.

Syntax

location.reload([true])

Parameters

Method of

Location

Implemented in

Navigator 3.0

Description

The reload method forces a reload of the document specified by the URL in the location.href property.

This method uses the same policy that the Navigator's Reload button uses (Once per Session, Every Time, or Never). The user sets the default value of this policy by choosing Network Preferences from the Options menu and specifying Verify Documents on the Cache tab of the Preferences dialog box.

The reload method does not force a transaction with the server, unless the user has set the preference to Every Time, in which case it does a "conditional GET" request using an If-modified-since HTTP header, to ask the server to return the document only if its last-modified time is newer than the time the client keeps in its cache. In other words, reload will reload from the cache, unless the user has specified Every Time and the document has changed on the server since it was last loaded and saved in the cache.

In event handlers, you must specify window.location.reload() instead of simply using location.reload(). Due to the scoping of static objects in JavaScript, a call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Clicking another button lets the user reload the document.

See also

replace method

<<New.>>

Method. Loads the specified URL over the current history entry.

Syntax

location.replace("URL")

Parameters

Method of

Location

Implemented in

Navigator 3.0

Description

The replace method loads the specified URL over the current history entry, so after the replace method is used, the user cannot navigate to the previous URL by using Navigator's Back button.

In event handlers, you must specify window.location.replace() instead of simply using location.replace(). Due to the scoping of static objects in JavaScript, a call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

Examples

The following example lets the user choose among several catalogs to display. The example displays two sets of radio buttons which let the user choose a season and a category, for example the Spring/Summer Clothing catalog or the Fall/Winter Home & Garden catalog. When the user clicks the Go button, the displayCatalog function executes the replace method, replacing the current URL with the URL appropriate for the catalog the user has chosen. Note that after the replace method is used, the user cannot navigate to the previous URL (the list of catalogs) by using Navigator's Back button.

See also

reload method

<<New.>>

Method. Simulates a mouse click on a reset button for the calling form.

Syntax

formName.reset()

Parameters

formName is the name of any form or an element in the forms array.

Method of

Form

Implemented in

Navigator 3.0

Description

The reset method restores a form element's default values. A reset button does not need to be defined for the form.

Examples

The following example displays a Text object in which the user is to type "CA" or "AZ". The Text object's onChange event handler calls a function that executes the form's reset method if the user provides incorrect input. When the reset method executes, defaults are restored and the form's onReset event handler displays a message.

See also

onReset event handler, Reset object

<<Changed.>>

The following properties have been added to the Reset object:

Property	Description
type	Reflects the TYPE attribute

See also

onReset event handler, reset method

<<New.>>

Method. Transposes the elements of an array: the first array element becomes the last and the last becomes the first.

Syntax

arrayName.reverse()

Parameters

arrayName is the name of an Array object or a property of an existing object.

Method of

Array

Implemented in

Navigator 3.0

Description

The reverse method transposes the elements of the calling array object.

Examples

The following example creates an array myArray, containing three elements, then reverses the array.

This code changes myArray so that:

• myArray[0] is "three"
• myArray[1] is "two"
• myArray[2] is "one"

See also

join, sort methods

<<New.>>

Method. Scrolls a window to a specified coordinate.

Syntax

windowReference.scroll(x-coordinate,y-coordinate)

Parameters

windowReference is a valid way of referring to a window, as described in the Window object.

x-coordinate is an integer representing the x-coordinate in pixels.

y-coordinate is an integer representing the y-coordinate in pixels.

Method of

Window

Implemented in

Navigator 3.0

Description

JavaScript does not reflect document dimensions in pixels, so when using the scroll method, you must hardcode the x and y coordinates. A document's upper left coordinates are 0,0.

Examples

Example 1. Scroll the current window. The following example scrolls the current window to the coordinates 50,100.

Example 2. Scroll a different window. The following code, which exists in one frame, scrolls a second frame. Two Text objects let the user specify the x and y coordinates. When the user clicks the Go button, the document in frame2 scrolls to the specified coordinates.

<<Changed.>>

The search property is now a property of the Area object.

Syntax

The following syntax has been added for the search property:

areaName.search

Parameters

Property of

Description

You can set the search property at any time.

<<Changed.>>

You can now change the text of options in a Select object, and you can create options using the new Option() constructor.

Changing option text

To change an option's text, use the text property of the options array. For example, suppose a form has the following Select object:

You can set the text of the i^th item in the selection based on text entered in a text field named whatsNew as follows:

For example, enter some text in the first text field below and then enter a number between 0 and 2 (inclusive) in the second text field. When you click the button, the text will be substituted for the indicated option number.

Adding options using the Option() constructor

Syntax

To create an option to add to an existing Select object:

optionName = new Option([optionText, optionValue, defaultSelected, selected])

To add the new option to an existing Select object:

selectName.options[index]=optionName

Parameters

optionName is either the name of a new object or a property of an existing object.

optionText specifies the text to display in the select list. You can access this value using the text property.

optionValue specifies a value that is returned to the server when the option is selected and the form is submitted. You can access this value using the value property.

defaultSelected specifies whether the option is initially selected (true or false). You can access this value using the defaultSelected property.

selected specifies the current selection state of the option (true or false). You can access this value using the selected property.

selectName is the name of an existing Select object.

index is an integer representing an option in a Select object. You can access this value using the index property.

Description

Each option created using the Option() constructor is an object and has the same properties as elements of the options array.

After you create the options and add them to the Select object, you must refresh the document by using history.go(0). This statement must be last. When the document reloads, variables are lost if not saved in cookies or form element values.

Examples

Deleting options

Syntax

selectName.options[index] = null

Parameters

selectName is the name of an existing Select object.

index is an integer representing an option in a Select object.

Description

Deletion compresses the options array. For example, if you delete options[0], the existing options[1] becomes options[0]. It's a good idea to delete options at the end of the array first.

Examples

The following function removes an option from a Select object.

Changing the selection state

The following discussion will be added to the documentation for the Select object; however, this is not new functionality.

You can use the selected and selectedIndex properties to change the selection state of options in a Select object.

• The selectedIndex property for a Select object is an integer specifying the index of the selected option. This is most useful for Select objects that are created without the MULTIPLE attribute. The following statement sets a Select object's selectedIndex property: document.myForm.musicTypes.selectedIndex = i
• The selected property for an option is a Boolean value specifying the current selection state of the option in a Select object. If an option is selected, its selected property is true; otherwise it is false. This is more useful for Select objects that are created with the MULTIPLE attribute. The following statement sets an option's selected property to true: document.myForm.musicTypes.options[i].selected = true

Properties

The following properties have been added to the Select object:

Property	Description
text	Not a new property, it can now be changed and the text displayed by the option in the Select object changes
type	Specifies that the object is a Select object and indicates whether MULTIPLE is specified

Objects created with the Option() constructor have the following properties:

Property	Description
defaultSelected	Specifies the initial selection state of the option
index	Specifies the index of the option in a Select object
prototype	Lets you add a properties to an option.
selected	Specifies the current selection state of the option
text	Specifies the text for the option
value	Specifies the value that is returned to the server when the option is selected and the form is submitted

<<Changed.>>

The selected property is now a property of the Option object.

Syntax

The following syntax has been added for the selected property:

optionName.selected

Parameters

Property of

<<New.>>

Method. Sorts the elements of an array.

Syntax

arrayName.sort(compareFunction)

Parameters

arrayName is the name of an Array object or a property of an existing object.

compareFunction specifies a function that defines the sort order. If omitted, the array is sorted lexicographically (in dictionary order) according to the string conversion of each element.

Method of

Array

Implemented in

Navigator 3.0

Description

If compareFunction is not supplied, elements are sorted by converting them to strings and comparing strings in lexicographic ("dictionary" or "telephone book," not numerical) order. For example, "80" comes before "9" in lexicographic order, but if you are comparing numbers 9 needs to come before 80.

If compareFunction is supplied, the array elements are sorted according to the return value of the compare function. If a and b are two elements being compared, then:

• If compareFunction(a, b) is less than zero, sort b to a lower index than a.
• If compareFunction(a, b) returns zero, leave a and b unchanged with respect to each other, but sorted with respect to all different elements.
• If compareFunction(a, b) is greater than zero, sort b to a higher index than a.

So the compare function has the following form:

To compare numbers instead of strings, the compare function can simply subtract b from a:

JavaScript uses a stable sort: the index partial order of a and b does not change if a and b are equal. If a's index was less than b's before sorting, it will be after sorting, no matter how a and b move due to sorting.

Examples

The following example creates four arrays and displays the original array, then the sorted arrays. The numeric arrays are sorted without, then with, a compare function.

This example produces the following output. As the output shows, when a compare function is used, numbers sort correctly whether they are numbers or numeric strings.

stringArray: Blue,Humpback,Beluga
Sorted: Beluga,Blue,Humpback

numberArray: 40,1,5,200
Sorted without a compare function: 1,200,40,5
Sorted with compareNumbers: 1,5,40,200

numericStringArray: 80,9,700
Sorted without a compare function: 700,80,9
Sorted with compareNumbers: 9,80,700

mixedNumericArray: 80,9,700,40,1,5,200
Sorted without a compare function: 1,200,40,5,700,80,9
Sorted with compareNumbers: 1,5,9,40,80,200,700

See also

join, reverse methods

<<New.>>

Method. Splits a String object into an array of strings by separating the string into substrings.

Syntax

stringName.split([separator])

Parameters

stringName is any string or a property of an existing object.

separator specifies the character to use for separating the string. The separator is treated as a string. If separator is omitted, the array returned contains one element consisting of the entire string.

Method of

String

Implemented in

Navigator 3.0

Description

The split method returns the new array.

Examples

The following example defines a function that splits a string into an array of string using the specified separator. After splitting the string, the function displays messages indicating the original string (before the split), the separator used, the number of elements in the array, and the individual array elements.

This example produces the following output:

See also

charAt, indexOf, lastIndexOf methods

<<New.>>

Property. A string specifying the URL of an image to be displayed in a document.

Syntax

imageName.src

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The src property initially reflects the SRC attribute of the <IMG> tag. Setting the src property begins loading the new URL into the image area (and aborts the transfer of any image data that is already loading into the same area). Therefore, if you plan to alter the lowsrc property, you should do so before setting the src property. If the URL in the src property references an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

When you change the src property of a displayed image, the new image you specify is displayed in the area defined for the original image. For example, suppose an Image object originally displays the file beluga.gif:

If you set myImage.src='seaotter.gif', the image seaotter.gif is displayed in the same space originally used by beluga.gif, even if seaotter.gif is not the same size as beluga.gif.

You can change the src property at any time.

Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Each image also uses the lowsrc property to display a low-resolution image.

See also the examples for the Image object.

See also

complete, lowsrc properties

<<Changed.>>

String objects are now "real" objects. In previous releases, you constructed strings by quoting some characters, and if you wanted to use the string as an object, you followed the string reference with a property or method name such as .length or .indexOf("sub"). Now you can create String objects using the String() constructor.

Syntax

To create a String object:

stringObjectName = new String(string)

Parameters

stringObjectName is the name of a new String object.

string is any string.

Description

Strings can now be passed among scripts in different windows or frames. In Navigator 2.0, you had to add an empty string to another window's string to reference it as follows:

Properties

The following properties have been added to the String object:

Property	Description
prototype	Lets you add properties to a String object.

Methods

The following methods have been added to the String object:

Examples

The following code creates two string variables and opens a second window:

If the HTML source for the second window (string2.html) creates two string variables, empLastName and empFirstName, the following code in the first window assigns values to the second window's variables:

The following code in the first window displays the values of the second window's variables:

<<Changed.>>

The following properties have been added to the Submit object:

Property	Description
type	Reflects the TYPE attribute

<<New.>>

Property. This property is currently documented in Determining installed plug-ins with JavaScript.

<<New.>>

Function. Adds tainting to a property.

Syntax

taint(propertyName)

Parameters

propertyName is the property to taint.

Implemented in

Navigator 3.0

Description

This function is currently documented in Data tainting.

See also

untaint function

<<Changed.>>

The target property is now a property of the Area object.

Syntax

The following syntax has been added for the target property:

areaName.target

Parameters

Property of

Description

target is a string specifying the name of the window that displays the content of a clicked area.

The target property initially reflects the TARGET attribute of the tag; however, setting target overrides this attribute.

The target property cannot be assigned the value of a JavaScript expression or variable.

You can set the target property at any time.

<<Changed.>>

The following properties have been added to the Text object:

Property	Description
type	Reflects the TYPE attribute

<<Changed.>>

The text property of the options array can now be changed and the text displayed by the option in the Select object changes. In previous releases, you could set the text property but the new value was not reflected in the Select object.

The text property is now a property of the Option object.

Syntax

The following syntax has been added for the text property:

optionName.text

Parameters

Property of

<<Changed.>>

The following properties have been added to the Textarea object:

Property	Description
type	Specifies that the object is a Textarea object

<<New.>>

Method. Converts an object into a string.

Note: This method existed in 2.0 but was undocumented.

Syntax

objectName.toString([radix])

Parameters

objectName is the object to convert to a string.

radix specifies the base to use for representing numeric values.

Method of

toString is a method of all objects.

Implemented in

Navigator 2.0 (radix added in 3.0)

Description

Every object has a toString method that is called when it is to be represented as a text value. toString is also used when an object is referenced in a string concatenation. You can also use toString within your own code to convert an object into a string.

If an object has no string value, its toString method will return "[object type]" where type is the object type. For example, if the following Image object named "sealife" exists, sealife.toString() will return [object Image].

When used with an array, toString joins the array and returns one string containing each array element separated by commas. For example, the following code creates an array and writes output using toString to convert the array to a string.

For Function objects, toString decompiles the function back into a canonical source string.

Examples

The following example prints the string equivalents of the numbers 0 through 9 in decimal and binary.

The preceding example produces the following output:

<<New.>>

Property. For form elements created with the <INPUT>, <SELECT>, or <TEXTAREA> tags, a string specifying the type of form element. For mimeType objects, the name of the MIME type.

Syntax

1. objectName.type

2. mimeTypes[index].type

Parameters

objectName is either the value of the NAME attribute of a form element object (button, checkbox, hidden, password, radio, reset, select, submit, text, or textarea) or an element in the elements array.

Property of

Button, Checkbox, FileUpload, Hidden, mimeType, Password, Radio, Reset, Select, Submit, Text, Textarea

Implemented in

Navigator 3.0

Description

The value of the type property is assigned to form elements as follows:

HTML element	Value of type property
INPUT TYPE="button"	"button"
INPUT TYPE="checkbox"	"checkbox"
INPUT TYPE="file"	"file"
INPUT TYPE="hidden"	"hidden"
INPUT TYPE="password"	"password"
INPUT TYPE="radio"	"radio"
INPUT TYPE="reset"	"reset"
INPUT TYPE="submit"	"submit"
INPUT TYPE="text"	"text"
SELECT	"select-one"
SELECT MULTIPLE	"select-multiple"
TEXTAREA	"textarea"

<<New.>>

Operator. Returns a string indicating the type of the unevaluated operand.

Syntax

1. typeof operand
2. typeof (operand)

Arguments

Examples

Suppose you define the following variables:

The typeof operator returns the following results for these variables:

For the keywords true and null, the typeof operator returns the following results:

For a number or string, the typeof operator returns the following results:

For property values, the typeof operator returns the type of value the property contains:

For methods and functions, the typeof operator returns results as follows:

For objects, the typeof operator returns results as follows:

<<New.>>

Function. Removes tainting from a property.

Syntax

untaint(propertyName)

Parameters

propertyName is the property to remove tainting from.

Implemented in

Navigator 3.0

Description

This function is currently documented in Data tainting.

Examples

In the following example, the variable untainted can be sent in a URL or form post by other scripts:

See also

taint function

<<Changed.>>

The value property is now a property of the following objects:

Syntax

The following syntax has been added for the value property:

fileUploadName.value
optionName.value

Parameters

optionName is the name of a Select object option created using the Option() constructor.

Description

Select object options

You can set the value property at any time.

FileUpload objects

The value property is a string that reflects the current value of a FileUpload object's field. Use the value property to obtain the file name that the user typed into a FileUpload object.

value is a read-only property.

Property of

<<New.>>

Operator. Specifies an expression to be evaluated without returning a value.

Syntax

1. javascript:void (expression)
2. javascript:void expression

Arguments

Description

Use the void operator to specify an expression as a hypertext link. The expression is evaluated but is not loaded in place of the current document.

The following code creates a hypertext link that does nothing when the user clicks it. When the user clicks the link, void(0) evaluates to 0, but that has no effect in JavaScript.

The following code creates a hypertext link that submits a form when the user clicks it.

See also

Area, link objects

<<New.>>

Property. A string specifying a margin in pixels between the top and bottom edges of an image and the surrounding text

Syntax

imageName.vspace

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The vspace property reflects the VSPACE attribute of the <IMG> tag. For images created with the Image() constructor, the value of the vspace property is 0.

vspace is a read-only property.

Examples

See the examples for the height property.

See also

border, height, hspace, width properties

<<New.>>

Property. A string specifying the width of an image either in pixels or as a percentage of the window width.

Syntax

imageName.width

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Description

The width property reflects the WIDTH attribute of the <IMG> tag. For images created with the Image() constructor, the value of the width property is the actual, not the displayed, width of the image.

width is a read-only property.

Examples

See the examples for the height property.

See also

border, height, hspace, vspace properties

<<Changed.>>

Properties

The following properties have been added to the Window object:

Property	Description
opener	Specifies the window name of the calling document when a window is opened using the open method

Methods

The following methods have been added to the Window object:

Event handlers

The following event handlers have been added to the Window object:

Syntax

The following syntax has been added to the <BODY> and <FRAMESET> tags:

<BODY>
...
   [onBlur="handlerText"]
   [onFocus="handlerText"]
...
</BODY>

<FRAMESET>
...
   [<FRAME SRC="locationOrURL" NAME="frameName">]
   [onBlur="handlerText"]
   [onFocus="handlerText"]
...
</FRAMESET>

Note: On Windows platforms, placing an onBlur or onFocus event handler in a <FRAMESET> tag has no effect.

The following syntax has been added to the Window object for defining an onError event handler for a Window object:

window.onerror=errorHandler

errorHandler is the keyword null, the name of an error-handling function, or a variable or property that contains null or a valid function reference.

For information on specifying the onError event handler, see onError event handler.

Additional description

The following discussion will be added to the documentation for the Window object; however, this is not new functionality.

When you reference the Location object within an event handler, you must specify window.location instead of simply using location. Due to the scoping of static objects in JavaScript, a call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

The following topics are changes or additions to the JavaScript Developer's Guide.

You can now reset an event handler specified by HTML from within JavaScript, for example:

Note that event handlers are function references, so you must assign fun2, not fun2() (the latter calls fun2 and has whatever type and value fun2 returns).

Also, since the event handler HTML attributes are literal function bodies, you cannot use <INPUT onClick=fun1> in the HTML source to make fun1 the onClick handler for an input; you must call fun1 instead, as in the example.

Finally, because HTML is case-insensitive while JavaScript is case-sensitive, you must spell event handler names in JavaScript in lowercase.

When you define an object's properties with property names, you cannot refer to these properties by their ordinal index, as you could in Navigator 2.0. This applies when you create an object and its properties with a constructor function, as in the above example of the Car object type, and when you define individual properties explicitly (for example, myCar.color = "red").

If you define object properties initially with an index, for example,

The rule is: if you initially define a property by its name, you must always refer to it by its name. If you initially define a property by an index, you must always refer to it by its index.

The exception to this rule is objects reflected from HTML: for example, the frames, forms, elements, and anchors arrays. You can always refer to these objects by their ordinal number (based on where they appear in the document) and by their name (if defined). For example, you can refer to the second form in a document as document.forms[1] or as document.myform, if the second <FORM> tag has a NAME attribute of "myform".

JavaScript entities allow you to use a JavaScript expression as the value for an HTML attribute. This allows you to create more flexible HTML constructs.

You may already be familiar with HTML character entities by which you can define characters with special numerical codes or names by preceding the name with an ampersand and terminating it with a semicolon. For example, you can include a greater-than symbol (>) with the character entity &GT; and a less-than symbol (<) with &LT;.

JavaScript entities also start with an ampersand and end with a semicolon. Instead of a name or number, you use a JavaScript expression enclosed in curly braces {}. You can use JavaScript entities only where an HTML attribute value would normally go. For example, suppose you define a variable barWidth. You could create a horizontal rule with the specified percentage width as follows:

So, for example, if barWidth were 50, then this would create the following display:

As always, once layout has occurred, the display of a page can change only if you reload the page.

The <SCRIPT> HTML tag has a new attribute, SRC, that lets you specify a file as the JavaScript source (rather than embedding the JavaScript in the HTML). For example:

Any JavaScript statements in a SCRIPT tag with a SRC attribute are ignored. Note, however, that the closing </SCRIPT> tag is required.

The SRC attribute value can be any URL, relative or absolute. For example:

External JavaScript files are especially useful to share functions among many different pages. JavaScript-only files cannot contain any HTML tags: they must contain only JavaScript statements and function definitions.

JavaScript-only files should have filename suffix .js, and the server must map the .js suffix to the MIME type "application/x-javascript", which the server sends back in the HTTP header. If the server does not map the .js filename suffix to application/x-javascript MIME type, Navigator will not load the JavaScript file specified by the SRC attribute properly.

Note: This requirement does not apply if you are using local files.

The <NOSCRIPT> tag is similar to the NOFRAMES tag for Frames. HTML enclosed within the tag is displayed by a non-JavaScript browser; code enclosed within the tag is hidden and ignored by Navigator. Use this tag to specify alternate content for browsers that do not support JavaScript, or in case the user has disabled JavaScript in Options | Network Preferences.

For example:

Navigator (version 2.02 and later) automatically prevents scripts on one server from accessing properties of documents on a different server. This restriction prevents scripts from fetching private information such as directory structures or user session history. However, this restriction also affects some legitimate applications, such as "navigation helper" scripts that use frames and need to see other frames' content, no matter the origin.

JavaScript now has a feature called data tainting that retains the security restriction but provides a workaround mechanism for legitimate applications. When data tainting is active, JavaScript in one window will be able to see properties of another window, no matter what server the other window's document was loaded from. However, if JavaScript in the first window attempts to send data derived from the other window's properties to a server, a confirming dialog box is displayed so the user can cancel or confirm the operation. By default, all properties in the second window are tainted so they cannot be sent to a server other than the one the documents in the window came from.

To enable data tainting,

• On Unix, use the setenv command.
• On Windows, use set.
• On Macintosh, set the environment variable NS_ENABLE_TAINT. Edit the resource with type 'Envi' and number 128 in the Netscape application by removing the two ascii slashes "//" before the NS_ENABLE_TAINT text at the end of the resource.

You can control the tainting of properties with two functions: taint adds tainting to a property and untaint removes tainting from a property. These functions each take a single property as an argument.

For example, to remove taint from a form input element so that a script can send it to another server, use:

Neither taint nor untaint modifies its argument; rather, both functions return a marked or unmarked reference to the argument object, or copy of the primitive type value (number or boolean value). You use untaint to clear the "taint code" that marks data as belonging to a server, and therefore not to be sent by other scripts to different servers. You use taint to mark data that otherwise is not tainted with your script's "taint code." A script can untaint only data that has its own "taint code", or has the identity (null) taint code. Data with any other script's "taint code" are copied and returned by untaint without change or error.

To handle cases where control flow rather than data flow carries tainted information, each window has a taint accumulator associated with it. The taint accumulator holds taint tested in the condition part of if, for, and while statements, and mixes different taint codes to create new codes that identify the combination of data origins (serverA, serverB, serverC, etc.).

The taint accumulator is reset to identity only if it contains exactly the current document's origin code. Otherwise it accumulates until the document is unloaded. All windows loading documents from the same origin share a single taint accumulator.

If a script calls taint with no argument, it will mix its own taint code into its accumulator. If it calls untaint with no argument, and only if its accumulator holds exactly its taint code (not a mixture), then the accumulator is reset to hold the identity code.

If a window's accumulator holds taint, scripted actions initiated from the context of that window (form submission; setting location, even of another window's location) are checked. Only if the accumulated script taint, the taint code of the targeted server, and the taint code of the data being sent are compatible will the operation proceed. Compatible here means a binary relation: either that two taint codes are equal, or that at least one is the identity taint code. The identity code is like zero for addition, hence its name.

If script, server, and data taints are incompatible, a confirming dialog is posted to detail the conflicting origin URL prefixes, and to allow the user to cancel or OK the URL load or form post.

Accumulated taint propagates across setTimeout and into the evaluation of the first argument to setTimeout. It propagates through document.write into generated tags, so that a malicious script cannot signal private information such as session history by generating an HTML tag with an implicitly-loaded URL SRC parameter: