This is documentation of JavaScript 1.1, as implemented in Navigator 3.0.
COMING SOON: these sections will be integrated into the body of the JavaScript Guide. For now, the body of the JavaScript Guide is based on Navigator 2.0, and the new and changed features are noted in this document.
The following lists summarize the changes and additions to JavaScript since Navigator 2.0.
Note: These language features are not incorporated in LiveWire 1.0.
The following topics are changes or additions to the JavaScript Reference.
<<New.>>
Object. Includes a Java applet in a web page.
<APPLET
CODE=classFileName
HEIGHT=height
WIDTH=width
MAYSCRIPT
[NAME=appletName]
[CODEBASE=classFileDirectory]
[ALT=alternateText]
[ALIGN="left"|"right"|
"top"|"absmiddle"|"absbottom"|
"texttop"|"middle"|"baseline"|"bottom"]
[HSPACE=spaceInPixels]
[VSPACE=spaceInPixels]>
[<PARAM NAME=parameterName VALUE=parameterValue>]
[ ... <PARAM>]
</APPLET>
CODE=classFileName specifies the file name of the applet that you want to load. This file name must end in a .class extension.
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.
MAYSCRIPT permits the applet to access JavaScript. Use this attribute to prevent an applet from accessing JavaScript on a page without your knowledge.
NAME=appletName specifies the name of the applet. You can access this value using the name property.
CODEBASE=classFileDirectory specifies directory of the .class file, if it is different from the directory that contains the HTML page.
ALT=alternateText specifies text to display for browsers that do not support the <APPLET> tag.
ALIGN=alignment specifies the alignment of the applet on the HTML page.
HSPACE=spaceInPixels specifies a horizontal margin for the applet, in pixels, within the browser window.
VSPACE=spaceInPixels specifies a vertical margin for the applet, in pixels, within the browser window.
<PARAM> defines a parameter for the applet.
NAME=parameterName specifies the name of the parameter.
VALUE=parameterValue> specifies a value for the parameter.
To use an applet object:
1. appletName.propertyName 2. document.applets[index].propertyName
appletName is the value of the NAME attribute of an Applet object.
index is an integer representing applet in a document or a string containing the name of an Applet object.
propertyName is one of the properties listed below.
Navigator 3.0
The author of an HTML page must permit an applet to access JavaScript by specifying the MAYSCRIPT attribute of the APPLET tag. This prevents an applet from accessing JavaScript on a page without the knowledge of the page author. For example, to allow the musicPicker.class applet access to JavaScript on your page, specify the following:
Accessing JavaScript when the MAYSCRIPT attribute is not specified results in an exception.
For more information on using applets, see LiveConnect: Java-JavaScript communication.
You can reference the applets in your code by using the applets array. This array contains an entry for each Applet object (<APPLET> tag) in a document in source order. For example, if a document contains three applets, these applets are reflected as document.applets[0], document.applets[1], and document.applets[2].
To use the applets array:
1. document.applets[index] 2. document.applets.lengthindex is an integer representing an applet in a document or a string containing the name of an Applet object.
To obtain the number of applets in a document, use the length property: document.applets.length.
Elements in the applets array are read-only. For example, the statement document.applets[0]="myApplet.class" has no effect.
The Applet object has the following properties:
| Property | Description | |
|---|---|---|
| name | Reflects the NAME attribute |
The following code launches an applet called "musicApp":
For more examples, see LiveConnect: Java-JavaScript communication.
<<New.>>
Object. Defines an area of an image as an image map. When the user clicks the area, the area's hypertext reference is loaded into its target window.
To define an area, use standard HTML syntax with the addition of the onMouseOut and onMouseOver event handlers:
<MAP NAME="mapName">
<AREA
[NAME="areaName"]
COORDS="x1,y1,x2,y2,..."|"x-center,y-center,radius"
HREF="location"
[SHAPE="rect"|"poly"|"circle"|"default"]
[TARGET="windowName"]
[onMouseOut="handlerText"]
[onMouseOver="handlerText"]>
</MAP>
NAME="mapName" specifies the name of the map. You can specify this map name in the USEMAP attribute of the <IMG> tag.
AREA defines an area of an image as an image map.
NAME="areaName" specifies the name of the Area object. This attribute is not reflected in JavaScript (you cannot refer to an Area object by name).
COORDS specifies the coordinates of the image map.
HREF="location" specifies the URL of the document to load when a user clicks the area. Any region of an image that does not have an HREF attribute does not function as a hyperlink. This attribute is required if you include the onMouseOut and onMouseOver event handlers.
SHAPE specifies the shape of the map. "default" specifies a region as the default. If omitted, "rect" is used.
TARGET="windowName" specifies the window that the link is loaded into. windowName can be an existing window; it can be a frame name specified in a <FRAMESET> tag; or it can be one of the literal frame names _top, _parent, _self, or _blank; it cannot be a JavaScript expression (for example, it cannot be parent.frameName or windowName.frameName).
1. areaName.propertyName 2. document.links[index].propertyName
areaName is the value of the NAME attribute of an Area object.
index is an integer representing area in a document or a string containing the name of an Area object
propertyName is one of the properties listed below.
Navigator 3.0
Area objects are in the links array. You cannot refer to an Area object by name; you must use the links array. For example, if a document contains three area objects, these objects are reflected as document.links[0], document.links[1], and document.links[2]. For information on the links array, see the Link object.
The HREF attribute is required for Area objects that use the onMouseOut or onMouseOver event handlers. However, if you create an Area for an image and do not want the image to link to a hypertext reference when clicked, specify a JavaScript function in the area's HREF attribute by using the javascript: URL protocol. For example, if a user clicks the following Area object, the function onTop executes.
If you want an area's link to do nothing, use javascript:void(0) in the HREF attribute. When the user clicks the following Area object, nothing happens:
The Area object has the following properties:
| Property | Description | |
|---|---|---|
| hash | Specifies an anchor name in the URL | |
| host | Specifies the host and domain name, or IP address, of a network host | |
| hostname | Specifies the host:port portion of the URL | |
| href | Specifies the entire URL | |
| pathname | Specifies the url-path portion of the URL | |
| port | Specifies the communications port that the server uses for communications | |
| protocol | Specifies the beginning of the URL, including the colon (:) | |
| search | Specifies a query | |
| target | Reflects the TARGET attribute |
None
Example 1. onMouseOver and onMouseOut event handlers. The following example displays an image, globe.gif. The image uses an image map that defines areas for the top half and the bottom half of the image. The onMouseOver and onMouseOut event handlers display different status bar messages depending on whether the mouse passes over or leaves the top half or bottom half of the image. The HREF attribute is required when using the onMouseOver and onMouseOut event handlers, but in this example the image does not need a hypertext link, so the HREF attribute executes javascript:void(0), which does nothing (see the void operator for more information).
Example 2. Refer to object with links array. The following code refers to the href property of the first Area object shown in Example 1.
Example 3. Simulate onClick with HREF attribute. The following example uses an Area object's HREF attribute to execute a JavaScript function. The image displayed, colors.gif, shows two sample colors. The top half of the image is the color "antiquewhite", and the bottom half is "white". When the user clicks the top or bottom half of the image, the function setBGColor changes the document's background color to the color shown in the image.
See also
<<Changed.>>
The arguments property is now a property of the Function object.
To specify the arguments array from within a Function object:
this.arguments[index]
<<New.>>
Object. Lets you create arrays and work with them.
1. arrayObjectName = new Array() 2. arrayObjectName = new Array(arrayLength)To use Array objects:
1. arrayObjectName.propertyName 2. arrayObjectName.methodName(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.
None.
Navigator 3.0
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:
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. |
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.
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.
Math.atan2(x,y)
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.
Navigator 2.0
The atan2 method returns a numeric value.
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.
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.
The following syntax has been added for the blur method:
frameReference.focus() windowReference.blur()
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.
<<New.>>
Property. A string specifying the width, in pixels, of an image border.
imageName.border
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
The following function displays the value of an image's border property if the value is not zero.
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.
imageName.complete
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
complete is a read-only property.
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.
<<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.
The following syntax has been added for the defaultSelected property:
optionName.defaultSelected
<<New.>>
Property. This property is currently documented in Determining installed plug-ins with JavaScript.
1. navigator.mimeTypes[index].description 2. navigator.mimeTypes[mimeTypeName].description 3. navigator.plugins[index].description 4. navigator.plugins[pluginName].description
Navigator 3.0
<<Changed.>>
The following syntax has been added for the Document object:
<BODY> ... [onBlur="handlerText"] [onFocus="handlerText"] ... </BODY>
The onBlur and onFocus event handlers are specified in the <BODY> tag but are actually event handlers for the window object.
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
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.
1. navigator.plugins[index].filename 2. navigator.plugins[pluginName].filename
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.
<INPUT TYPE="file" NAME="fileUploadName">
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.
fileUploadName.propertyName
fileUploadName is the value of the NAME attribute of a FileUpload object.
propertyName is one of the properties listed below.
Navigator 3.0
You can place a FileUpload object on a form but you cannot use JavaScript to modify it in any way.
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. |
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.
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.
The following syntax has been added for the focus method:
frameReference.focus() windowReference.focus()
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.
<<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.>>
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
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.
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).
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.
functionTarget = new Function ([arg1, arg2, ... argn], functionBody)
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.
Navigator 3.0
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.
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:
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:
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.
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. |
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.
The following syntax has been added for the hash property:
areaName.hash
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.
imageName.height
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
The following function displays the values of an image's height, width, hspace, and vspace properties.
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.
The following syntax has been added for the host property:
areaName.host
You can set the host property at any time.
<<Changed.>>
The hostname property is now a property of the Area object.
The following syntax has been added for the hostname property:
areaName.hostname
You can set the hostname property at any time.
<<Changed.>>
The href property is now a property of the Area object.
The following syntax has been added for the href property:
areaName.href
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.
imageName.hspace
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
See the examples for the height property.
border, height, vspace, width properties
<<New.>>
Object. An image on an HTML form.
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"]>
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".
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
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.
Navigator 3.0
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 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.
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.lengthindex is an integer representing an image in a document or a string containing the name of an Image object.
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.
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 |
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.
Area, Link objects; onClick, onMouseOut, onMouseOver event handlers
<<Changed.>>
The index property is now a property of the Option object.
The following syntax has been added for the index property:
optionName.index
<<Changed.>>
The isNaN function now works on all platforms.
For information on isNaN, see the isNaN function.
<<New.>>
Method. Specifies whether Java is enabled.
navigator.javaEnabled()
Navigator 3.0
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.
The following code executes function1 if Java is enabled; otherwise it executes function2.
appName, appCodeName, userAgent properties
<<New.>>
Method. Joins all elements of an array into a string.
arrayName.join(separator)
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 (,).
Navigator 3.0
The string conversion of all array elements are joined into one string.
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:
<<Changed.>>
The length property is now a property of the following:
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
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.
<<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:
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:
<<Changed.>>
The following syntax has been added to the Location object:
[windowReference.]location.methodName(parameters)
The following methods have been added to the Location object:
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.
imageName.lowsrc
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
See the examples for the src property.
<<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.
Navigator 3.0
<<Changed.>>
The name property is now a read-only property of the following objects:
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
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
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.
<<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.
Navigator 3.0
In the following example, an onAbort handler in an Image object displays a message when the user aborts the image load:
onError, onLoad event handlers
<<Changed.>>
The onBlur event handler is now an event handler of windows, frames, and framesets.
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.
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.
The code for this example looks as follows:
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:
If you write an error-handling function, you have three options for reporting errors:
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.
Navigator 3.0
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.
onLoad event handler
<<Changed.>>
The onFocus event handler is now an event handler of windows, frames, and framesets.
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.
See the examples for the onBlur event handler.
<<Changed.>>
The onLoad event handler is now an event handler of the following:
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.
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.
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.
Navigator 3.0
See the examples for the Area object.
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.
See the examples for the Area object.
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.
Navigator 3.0
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.
<<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.
window.opener
Navigator 3.0
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.
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.
<<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.
The following syntax has been added for the pathname property:
areaName.pathname
You can set the pathname property at any time.
<<New.>>
Object. Generates output from a plug-in application.
<EMBED SRC=source NAME=appletName HEIGHT=height WIDTH=width> [<PARAM NAME=parameterName VALUE=parameterValue>] [ ... <PARAM>] </EMBED>
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.
Navigator 3.0
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.lengthindex is an integer representing a plugin in a document or a string containing the name of an Plugin object.
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.
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.
The following HTML includes an AVI plug-in in a document:
<<New.>>
An array of all plug-ins currently installed on the client. This array is currently documented in Determining installed plug-ins with JavaScript.
Navigator 3.0
<<Changed.>>
The port property is now a property of the Area object.
The following syntax has been added for the port property:
areaName.port
You can set the port property at any time.
<<Changed.>>
The protocol property is now a property of the Area object.
The following syntax has been added for the protocol property:
areaName.protocol
You can set the protocol property at any time.
<<New.>>
Property. Defines a property that is shared by all objects of the specified type.
objectType.prototype.propertyName = value
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.
prototype is a property of any object created with new, such as the following:
Navigator 3.0
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:
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.
location.reload([true])
Navigator 3.0
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.
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.
replace method
<<New.>>
Method. Loads the specified URL over the current history entry.
location.replace("URL")
Navigator 3.0
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.
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.
reload method
<<New.>>
Method. Simulates a mouse click on a reset button for the calling form.
formName.reset()
formName is the name of any form or an element in the forms array.
Navigator 3.0
The reset method restores a form element's default values. A reset button does not need to be defined for the form.
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.
onReset event handler, Reset object
<<Changed.>>
The following properties have been added to the Reset object:
| Property | Description | |
|---|---|---|
| type | Reflects the TYPE attribute |
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.
arrayName.reverse()
arrayName is the name of an Array object or a property of an existing object.
Navigator 3.0
The reverse method transposes the elements of the calling array object.
The following example creates an array myArray, containing three elements, then reverses the array.
This code changes myArray so that:
<<New.>>
Method. Scrolls a window to a specified coordinate.
windowReference.scroll(x-coordinate,y-coordinate)
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.
Navigator 3.0
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.
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.
The following syntax has been added for the search property:
areaName.search
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.
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 ith 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.
The code for this example looks as follows: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
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.
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.
selectName.options[index] = null
selectName is the name of an existing Select object.
index is an integer representing an option in a Select object.
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.
The following function removes an option from a Select object.
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 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.
The following syntax has been added for the selected property:
optionName.selected
<<New.>>
Method. Sorts the elements of an array.
arrayName.sort(compareFunction)
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.
Navigator 3.0
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:
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.
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
<<New.>>
Method. Splits a String object into an array of strings by separating the string into substrings.
stringName.split([separator])
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.
Navigator 3.0
The split method returns the new array.
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:
charAt, indexOf, lastIndexOf methods
<<New.>>
Property. A string specifying the URL of an image to be displayed in a document.
imageName.src
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
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.
<<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.
To create a String object:
stringObjectName = new String(string)
stringObjectName is the name of a new String object.
string is any string.
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:
The following properties have been added to the String object:
| Property | Description | |
|---|---|---|
| prototype | Lets you add properties to a String object. |
The following methods have been added to the String object:
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.
taint(propertyName)
propertyName is the property to taint.
Navigator 3.0
This function is currently documented in Data tainting.
untaint function
<<Changed.>>
The target property is now a property of the Area object.
The following syntax has been added for the target property:
areaName.target
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.
The following syntax has been added for the text property:
optionName.text
<<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.
objectName.toString([radix])
objectName is the object to convert to a string.
radix specifies the base to use for representing numeric values.
toString is a method of all objects.
Navigator 2.0 (radix added in 3.0)
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.
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.
1. objectName.type 2. mimeTypes[index].type
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.
Button, Checkbox, FileUpload, Hidden, mimeType, Password, Radio, Reset, Select, Submit, Text, Textarea
Navigator 3.0
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.
1. typeof operand 2. typeof (operand)
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.
untaint(propertyName)
propertyName is the property to remove tainting from.
Navigator 3.0
This function is currently documented in Data tainting.
In the following example, the variable untainted can be sent in a URL or form post by other scripts:
taint function
<<Changed.>>
The value property is now a property of the following objects:
The following syntax has been added for the value property:
fileUploadName.value optionName.value
optionName is the name of a Select object option created using the Option() constructor.
You can set the value property at any time.
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.
<<New.>>
Operator. Specifies an expression to be evaluated without returning a value.
1. javascript:void (expression) 2. javascript:void expression
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.
<<New.>>
Property. A string specifying a margin in pixels between the top and bottom edges of an image and the surrounding text
imageName.vspace
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
See the examples for the height property.
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.
imageName.width
imageName is either the name of an Image object or an element in the images array.
Navigator 3.0
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.
See the examples for the height property.
border, height, hspace, vspace properties
<<Changed.>>
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 |
The following methods have been added to the Window object:
The following event handlers have been added to the Window object:
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.
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 > and a less-than symbol (<) with <.
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,
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: