This JavaScript reference is a preliminary document describing the changes and new features in this pre-release version of Navigator 4.0 JavaScript. These features will be included in the new JavaScript Guide at a later date. For additional information about JavaScript, see the JavaScript Guide.
The following provides a summary of the new and changed features. Full descriptions follow.
The following features are new in JavaScript.
The event model has changed to include a new event object, new events, and event capturing.
Layers, new in Navigator 4.0, let you define overlapping layers of transparent
or solid content in a web page. Each layer in HTML has a corresponding
layer object that allows you to use JavaScript to manipulate the layer.
For JavaScript specific information, see Using JavaScript to Access Layers
in Creating
Multiple Layers of Content.
Regular expressions are patterns used to match character combinations in strings. The patterns can be constructed using the same syntax as regular expressions in PERL and passed as arguments to the String object's new methods match, replace, and split. They can also be constructed from JavaScript strings using the new RegExp object.
For additional power and functionality, scripts can now gain access to normally restricted information. This is achieved through signed scripts that request expanded privileges. This new functionality provides greater security than tainting. Tainting has been disabled.
Using style sheets, you gain finer control over the presentation of your web pages. Navigator 4.0 supports two syntaxes for designing style sheets: Cascading Style Sheets (CSS) and JavaScript style sheets. CSS is the static approach to specifying style and JavaScript is the programmatic approach.
For information on the CSS syntax, see, http://www.w3.org/pub/WWW/TR/REC-CSS1
For information on the JavaScript syntax, see JavaScript Style Sheets.
The following changes have been made to existing features:
If the <SCRIPT> tag uses LANGUAGE=JavaScript1.2, the equality operators = = and != don't try to convert operands from one type to another, and always compare identity of like-typed operands.
As JavaScript evolves along with Navigator, its capabilities expand
greatly. This means that JavaScript written for Navigator 4.0 may work
in Navigator 4.0 only. To ensure that users of earlier versions of Navigator
avoid problems when viewing pages that use JavaScript 1.2, use the LANGUAGE
attribute in the <SCRIPT> tag to indicate which version of Javascript
you're using. If you use LANGUAGE="JavaScript1.2", you need to
be aware of the equality rules described below.
Statements within a <SCRIPT> tag are ignored if the browser does
not have the level of JavaScript support specified in the LANGUAGE attribute;
for example:
By using the LANGUAGE attribute, you can write general JavaScript that Navigator version 2.0 and higher recognize, and include additional or refined behavior for newer versions of Navigator.
If the <SCRIPT> tag uses LANGUAGE=JavaScript1.2, the equality operators (== and !=) work differently. This section describes how the equality operators work without LANGUAGE=JavaScript1.2 and how they work with LANGUAGE=JavaScript1.2. An example follows these descriptions.
The following describes how the equality operators (= = and !=) worked in previous versions of JavaScript and how they work in JavaScript 1.2 when LANGUAGE=JavaScript1.2 is not used in the <SCRIPT> tag. Note that if LANGUAGE=JavaScript, and LANGUAGE=JavaScript1.1 are used, the equality operators maintain their previous behavior.
If LANGUAGE=JavaScript1.2 is used in the <SCRIPT> tag, the equality operators (= = and != ) behave as follows:
(("" + 3)=="3")
(("3"-0)==3)
var x = 3 String(x) = "3"
var x = "3" Number(x) = 3
This approach avoids errors, maintains transitivity, and simplifies the language.
The following example demonstrates the = = operator with different <SCRIPT> tags.
<HTML>
<SCRIPT> document.write("3" == 3); </SCRIPT> <BR> <SCRIPT> document.write(("3"-0) == 3); </SCRIPT> <BR>
<SCRIPT LANGUAGE="JavaScript"> document.write("3" == 3); </SCRIPT> <BR> <SCRIPT LANGUAGE="JavaScript1.1"> document.write("3" == 3); </SCRIPT> <BR> <SCRIPT LANGUAGE="JavaScript1.2"> document.write("3" == 3); </SCRIPT> <BR> <SCRIPT LANGUAGE="JavaScript1.2"> document.write(("3"-0) == 3); </SCRIPT> <BR> <SCRIPT LANGUAGE="JavaScript1.2"> document.write(String(3) == "3"); </SCRIPT> <BR>
</HTML>
The output from the above is:
true
true
true
true
false
true
true
JavaScript's event model includes several new events, an event object, and the ability to capture and handle events before they reach their intended target. This section contains the following information:
New events are described in the Events section.
The event object contains properties that describe a JavaScript event, and is passed as an argument to an event handler when the event occurs. In the case of a mousedown event, for example, the event object contains the type of event (in this case "mousedown"), the x and y position of the cursor at the time of the event, a number representing the mouse button used, and a field containing the modifier keys (Control, Alt, Meta, or Shift) that were depressed at the time of the event. The properties used within the event object vary from one type of event to another. This variation is provided in the individual event descriptions.
JavaScript supports the following events. This document describes the new events, the JavaScript Guide describes pre-Navigator 4.0 events.
|
|
event.propertyName
All event handlers.
The following properties are specific to an event and are passed with the event object. To learn which properties are used by an event, see the "Event object properties used" section of the individual event.
Property | Description |
type | String representing the event type. |
layerX | Number specifying either the object width when passed with the resize
event, or the cursor's horizontal position in pixels relative to the layer
in which the event occurred.
Note that layerX is synonymous with x. |
layerY | Number specifying either the object height when passed with the resize
event, or the cursor's vertical position in pixels relative to the layer
in which the event occurred.
Note that layerY is synonymous with y. |
pageX | Number specifying the cursor's horizontal position in pixels, relative to the page. |
pageY | Number specifying the cursor's vertical position in pixels relative to the page. |
screenX | Number specifying the cursor's horizontal position in pixels, relative to the screen. |
screenY | Number specifying the cursor's vertical position in pixels, relative to the screen. |
which | Number specifying either the mouse button that was pressed or the ASCII value of a pressed key. |
modifiers | String specifying the modifier keys associated with a mouse or key event. Modifier key values are: ALT_MASK, CONTROL_MASK, SHIFT_MASK, and META_MASK. |
data | Returns an array of strings containing the URLs of the dropped objects. Passed with the dragdrop event. |
The following example uses the event object to provide the type of event to the alert message.
<A HREF="http://home.netscape.com" onClick='alert("Link got an event: " + event.type)'>Click for link event</A>
The following example uses the event object in an explicitly called event handler
<SCRIPT>
function fun1(e) { alert ("Document got an event: " + e.type); alert ("x position is " + e.layerX); alert ("y position is " + e.layerY); if (e.modifiers & Event.ALT_MASK) alert ("Alt key was down for event."); return true; }
document.onmousedown = fun1;
</SCRIPT>
You can now have a window or document capture and handle an event before it reaches its intended target. To accomplish this, both the window and document have these new methods:
For example, suppose you wanted to capture all click events occurring in a window.
First, you need to set up the window to capture all Click events:
window.captureEvents(Event.CLICK);
The argument to captureEvents is a property of the event object and indicates the type of event to capture. To capture multiple events, the argument is a list separated by or (|). For example:
window.captureEvents(Event.CLICK | Event.MOUSEDOWN | Event.MOUSEUP)
Next, you need to define a function that handles the event. The argument e is the event object for the event.
function clickHandler(e) { //What goes here depends on how you want to handle the event. //This is described below. }
You have four options for handling the event:
function clickHandler(e) { return true; }
function clickHandler(e) { return false; }
Note: When routeEvent calls an event handler, the event handler is activated. If routeEvent calls an event handler whose function is to display a new page, the action takes place without returning to the capturing object.
function clickHandler(e) { var retval = routeEvent(e); if (retval == false) return false; else return true; }
function clickHandler(e) { window.document.links[0].handleEvent(e); }
As long as the link has an onClick handler, the link will handle any click event it receives.
Finally, you need to register the function as the window's event handler for that event:
window.onClick = clickHandler;
In the following example, the window and document capture and release events:
<HTML>
<SCRIPT>
function fun1(e) { alert ("The window got an event of type: " + e.type + " and will call routeEvent."); window.routeEvent(e); alert ("The window returned from routeEvent."); return true; }
function fun2(e) { alert ("The document got an event of type: " + e.type); return false; }
function setWindowCapture() { window.captureEvents(Event.CLICK);
}
function releaseWindowCapture() { window.releaseEvents(Event.CLICK); }
function setDocCapture() { document.captureEvents(Event.CLICK); }
function releaseDocCapture() { document.releaseEvents(Event.CLICK); }
window.onclick=fun1; document.onclick=fun2;
</SCRIPT>
...
</HTML>
This section describes new and revised events.
All information about an event, such as its type, is now passed to its handler through the event object. The properties passed with the event object are listed under the heading "Event properties used." Pre-Navigator 4.0 events that aren't listed here use the type property only.
In Navigator 4.0, a window or document can capture events before they reach their intended target. For more information see Event Capturing.
Note: Navigator 4.0 recognizes mixed-case and lower case use of events and event handlers. For example, you can explicitly call an event handler using either element.onclick or element.onClick.
Event. Occurs when the user clicks a link or a form element (a Click is a combination of the MouseDown and MouseUp events). The event handler, onClick, is fully described in the JavaScript Guide.
onClick="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
Button, Checkbox, Link, Radio, Reset, and Submit objects
type indicates a Click event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the Click event occurred.
which represents 1 for a left-mouse click and 3 for a right-mouse click.
Event. Occurs when the user drops an object onto the Navigator window, such as dropping a file on the Navigator window.
onDragDrop="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
window object
type indicates a DragDrop event.
data returns an Array of Strings containing the URLs of the dropped objects.
The DragDrop event is fired whenever a system item (file, shortcut, etc.) is dropped onto the Navigator window via the native system's drag and drop mechanism. The normal response for the Navigator is to attempt to load the item into the browser window. If the event handler for the DragDrop event returns true, the browser will load the item normally. If the event handler returns false, the drag and drop will be cancelled.
Event. Occurs when the user depresses a key.
onKeyDown="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
document, Image, Link, and Textarea objects
type indicates a KeyDown event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the KeyDown event occurred.
which represents the ASCII value of the key pressed.
modifiers contains the list of modifier keys held down when the KeyDown event occurred.
A KeyDown event always occurs before a KeyPress event. If onKeyDown returns false, no KeyPress events occur. This prevents KeyPress events occurring due to the user holding down a key.
Event. Occurs when the user presses or holds down a key.
onKeyPress="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
document, Image, Link, and Textarea objects
type indicates a KeyPress event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the KeyPress event occurred.
which represents the ASCII value of the key pressed.
modifiers contains the list of modifier keys held down when the KeyPress event occurred.
A KeyPress event occurs immediately after a KeyDown event only if the onKeyDown returns something other than false. A KeyPress event repeatedly occurs until the user releases the key. You can cancel individual KeyPress events.
Event. Occurs when the user releases a key.
onKeyUp="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
document, Image, Link, and Textarea objects
type indicates a KeyUp event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the KeyUp event occurred.
which represents the ASCII value of the key pressed.
modifiers contains the list of modifier keys held down when the KeyUp event occurred.
Event. Occurs when the user depresses a mouse button.
onMouseDown="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
Button, document, and Link objects
type indicates a MouseDown event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the MouseDown event occurred.
which represents 1 for a left-mouse-button down and 3 for a right-mouse-button down.
modifiers contains the list of modifier keys held down when the MouseDown event occurred.
If onMouseDown returns false, the default action (entering drag mode, entering selection mode, or arming a link) is cancelled.
Note: Arming is caused by a MouseDown over a link. When a link is armed it changes color to represent its new state.
Event. Occurs when the user moves the cursor.
onMouseMove="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
None
type indicates a MouseMove event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the MouseMove event occurred.
The MouseMove event is sent only when a capture of the event is requested by an object (see Event Capturing).
captureEvents method
Event. Occurs when the user moves the cursor out of an object.
onMouseOut="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
Area, Layer, and Link objects
type indicates a MouseOut event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the MouseOut event occurred.
Event. Occurs when the user moves the cursor over an object.
onMouseOver="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
Area, Layer, and Link objects
type indicates a MouseOver event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the MouseOver event occurred.
Event. Occurs when the user releases a mouse button.
onMouseUp="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
Button, document, and Link objects
type indicates a MouseUp event.
layerX, layerY, pageX, pageY, screenX, and screenY represent the cursor location at the time the MouseUp event occurred.
which represents 1 for a left-mouse-button up and 3 for a right-mouse-button up.
modifiers contains the list of modifier keys held down when the MouseUp event occurred.
If onMouseUp returns false, the default action is cancelled. For example, if onMouseUp returns false over an armed link, the link is not triggered. Also, if MouseUp occurs over an unarmed link (possibly due to onMouseDown returning false), the link is not triggered.
Note: Arming is caused by a MouseDown over a link. When a link is armed it changes color to represent its new state.
Event. Occurs when the user or script moves a window or frame.
onMove="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
window and Frame objects
type indicates a Move event.
x and y represent the position of the top-left corner of the window or frame.
Note: In pr4, screenX and screenY will be used instead of x and y.
Event. Occurs when a user or script resizes a window or frame.
onResize="handlerText"
handlerText is JavaScript code or a call to a JavaScript function.
window and Frame objects
type indicates a Resize event.
x and y represent the width and height of the window or frame.
Note: In pr4, width and height will be used instead of x and y.
This section lists new and revised methods.
Method. Returns a string containing the text of the current selection.
document.getSelection()
document object
Method. Points the Navigator to the previous URL in the current history list; equivalent to the user pressing the Navigator Back button.
windowReference.back()
windowReference is the name of a window object.
window object
Method. Finds the specified text string in the contents of the specified window.
windowReference.find(["string"][,true|false][,true|false])
windowReference is the name of a window object.
string is the text string for which to search.
true if the string is found; otherwise false.
window object
When a string is specified, the browser performs a case-insensitive, forward search. If a string is not specified, the method displays the Find dialog box, allowing the user to enter the search string.
The two optional Boolean parameters allow you to specify search options. The first parameter, if true, specifies a case-sensitive search. The second parameter, if true, specifies a backward search. To use either parameter, both must be specified.
Method. Points the Navigator to the next URL in the current history list; equivalent to the user pressing the Navigator Forward button.
windowReference.forward()
windowReference is the name of a window object.
window object
Method. Points the Navigator to the URL specified in preferences as the user's home page; equivalent to the user pressing the Navigator Home button.
windowReference.home()
windowReference is the name of a window object.
window object
Method. Moves the window by the specified amounts.
windowReference.moveBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to move the window horizontally.
vertical is an integer representing the number of pixels by which to move the window vertically.
window object
To move a window offscreen, call this method in a signed script.
moveTo method
Method. Moves the top-left corner of the window to the specified screen coordinates.
windowReference.moveTo(x-coordinate, y-coordinate)
windowReference is a valid way of referring to a window.
x-coordinate is an integer representing the top edge of the window in screen coordinates.
y-coordinate is an integer representing the left edge of the window in screen coordinates.
window object
To move a window offscreen, call this method in a signed script.
moveBy method
Method. Opens a new web browser window. New window features have been added to the open method of the window object. The following provides a description of the open method and the new window features. For a complete description of the open method, see open (window object) in the JavaScript Guide.
[windowVar = ][window].open("URL", "windowName", ["windowFeatures"])
windowVar is the name of a new window. Use this variable when
referring to a window's properties, methods, and containership.
URL specifies the URL to open in the new window.
windowName is the window name to use in the TARGET attribute of
a FORM or <A> tag. windowName can contain only alphanumeric
or underscore (_) characters.
windowFeatures is a comma-separated list of any of the following
options and values:
alwaysLowered [=yes|no]|[=1|0] alwaysRaised [=yes|no]|[=1|0] dependent [=yes|no]|[=1|0] hotkeys [=yes|no]|[=1|0] innerWidth=pixels replaces width innerHeight=pixels replaces height outerWidth=pixels outerHeight=pixels screenX=pixels screenY=pixels titlebar [=yes|no]|[=1|0] z-lock [=yes|no]|[=1|0]
Note: Several of these features require the use of signed scripts. This is stated in the feature's description.
alwaysRaised if true, creates a new window that floats on top of other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.
alwaysLowered if true, creates a new window that floats below other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.
dependent if true, creates a new window as a child of the current window.
hotkeys if true, disables most hotkeys in a new window that has no menu bar. The security and quit hotkeys remain enabled.
innerWidth specifies the width, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
innerHeight specifies the height, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
outerWidth specifies the horizontal dimension, in pixels, of the window's outside boundary. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
outerHeight specifies the vertical dimension, in pixels, of the outside boundary of the window. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
screenX is the distance the new window is placed from the left side of the screen. To place a window offscreen, set this feature in a signed scripts.
screenY is the distance the new window
is placed from the top of the screen. To place a window offscreen,
set this feature in a signed scripts.
titlebar if true, creates a window with a title bar. To set the
titlebar to false, set this feature in a signed script.
z-lock if true, creates a new window that does not rise above other windows when activated. This feature can be set only in signed scripts.
window object
Method. Resizes the entire window by moving the window's bottom-right corner by the specified amount.
windowReference.resizeBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to resize the window horizontally.
vertical is an integer representing the number of pixels by which to resize the window vertically.
window object
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed script.
resizeTo method
Method. Resizes the entire window to the specified outer height and width.
windowReference.resizeTo(outerwidth, outerheight)
windowReference is a valid way of referring to a window.
outerwidth is an integer representing the window's width in pixels.
outerheight is an integer representing the window's height in pixels.
window object
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed script.
resizeBy method
Method. Scrolls the viewing area of the window by the given amount.
windowReference.scrollBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to scroll the viewing area horizontally.
vertical is an integer representing the number of pixels by which to scroll the viewing area vertically.
window object
scrollTo method
Method. Scrolls the viewing area of the window to the specified coordinates, such that the point (x, y) becomes the top-left corner.
Note: scrollTo extends the capabilities of scroll. scroll remains for backward compatibility.
windowReference.scrollTo(x-coordinate, y-coordinate)
windowReference is a valid way of referring to a window.
x-coordinate is an integer representing the x-coordinate of the viewing area in pixels.
y-coordinate is an integer representing the y-coordinate of the viewing area in pixels.
window object
scrollBy method
Method. Stops the current download; equivalent to the user pressing the Navigator Stop button.
windowReference.stop()
windowReference is the name of a window object.
window object
Method. Sets the window or document to capture all events of the specified type.
objectReference.captureEvents(eventType)
objectReference is the name of a window or document object.
eventType is the type of event to be captured. The available event types are listed with the event object.
window and document objects
captureEvents works in tandem with releaseEvents, routeEvent, and handleEvent. For more information, see Event Capturing.
Method. Cancels a timeout set with the setInterval method.
clearInterval(intervalID)
intervalID is a timeout setting that was returned by a previous call to the setInterval method.
Frame object, window object
See the description for setInterval method.
setInterval method
Method. Invokes the handler for the specified event.
objectReference.handleEvent(event)
objectReference is the name of an object.
event is the name of an event for which the specified object has an event handler.
objects with event handlers
handleEvent works in tandem with captureEvents, releaseEvents, and routeEvent. For more information, see Event Capturing.
Method. Prints the contents of the window or frame; equivalent to the user pressing the Navigator Print button.
windowReference.print()
frameReference.print()
windowReference is the name of a window object.
frameReference is the name of a frame object.
window and Frame objects
Method. Sets the window or document to release captured events of the specified type, sending the event to objects further along the event hierarchy.
Note: If the original target of the event is a window, the window receives the event even if it is set to release that type of event.
objectReference.releaseEvents(eventType)
objectReference is the name of a window, document, or layer object.
eventType is the type of event to be captured.
window and document objects
releaseEvents works in tandem with captureEvents, routeEvent, and handleEvent. For more information, see Event Capturing.
Method. Passes a captured event along the normal event hierarchy.
objectReference.routeEvent(event)
objectReference is the name of a window, document, or layer object.
event is the name of the event to be routed.
window and document objects
If a sub-object (document or layer) is also capturing the event, the event is sent to that object. Otherwise, it is sent to its original target.
routeEvents works in tandem with captureEvents, releaseEvents, and handleEvent. For more information, see Event Capturing.
Method. Repeatedly calls a function or evaluates an expression after a specified number of milliseconds has elapsed.
The timeouts continue to fire until the associated window or frame is destroyed or the interval is cancelled using the clearInterval method.
Used to call a function:
intervalID=setInterval(function, msec, [arg1, ..., argn])
Used to evaluate an expression:
intervalID=setInterval(expression, msec)
intervalID is an identifier that is used only to cancel the function call with the clearInterval method.
function is any function.
expression is a string expression or a property of an existing object. The expression must be quoted; otherwise, setInterval calls it immediately. For example setInterval("calcnum(3, 2)", 25).
msec is a numeric value, numeric string, or a property of an existing object in millisecond units.
arg1, ..., argn are the arguments, if any, passed to function.
Frame object, window object
clearInterval and setTimeout methods
Method. Calls a function or evaluates an expression after a specified number of milliseconds has elapsed.
The setTimeout method calls a function after a specified amount of time. It does not call the function repeatedly. For example, if a setTimeout method specifies five seconds, the function is evaluated after five seconds, not every five seconds. For repetitive timeouts, use the setInterval method.
Used to call a function:
timeoutID=setTimeout("function", msec, [arg1, ..., argn])
Used to evaluate an expression:
timeoutID=setTimeout(expression, msec)
timeoutID is an identifier that is used only to cancel the evaluation with the clearTimeout method.
function is any function.
expression is a string expression or a property of an existing object. The expression must be quoted; otherwise, setTimeout calls it immediately. For example setTimeout("calcnum(3, 2)", 25).
msec is a numeric value, numeric string, or a property of an existing object in millisecond units.
arg1, ..., argn are the arguments, if any, passed to function.
Frame object, window object
clearTimeout in the JavaScript Guide and setInterval methods
Object. Contains information about the display screen resolution and colors.
screen.propertyName
propertyName is one of the properties listed below.
None
Property | Description |
width | Specifies the width of the screen in pixels. |
height | Specifies the height of the screen in pixels. |
pixelDepth | Specifies the number of bits per pixel in the display. |
colorDepth | Specifies the number of colors possible to display. The number of colors is found using the color palette if one is available, or using the pixel depth. |
None
None
This section list new and revised properties for the navigator object and the window object.
Property. Indicates the translation of the Navigator being used.
navigator.language
The language property has been added for use with the JAR Manager.For more information, see the JAR Manager Developer's Guide.
The value for language is usually a two-letter code, such as "en" and occasionally a five-character code to indicate a language sub-type, such as "zh_CN".
Webpage authors would use this property when they need to determine the language of the Navigator client software being used. For example the scripter could display translated text for the user.
language is a read-only property.
Property. Indicates the machine type for which the Navigator was compiled.
navigator.platform
The platform property has been added for use with the JAR Manager. For more information, see the JAR Manager Developer's Guide.
The machine type the Navigator was compiled for may differ from the actual machine type due to version differences, emulators, or other reasons.
Webpage authors would use this property to ensure that their triggers download the appropriate JAR files. The triggering page checks the Navigator version before checking the platform property.
JAR-install writers would use this property to double-check that their package is being installed on an appropriate machine, or for small JAR's to decide which of several machine-specific files to install.
Platform values are Win32, Win16, Mac68k, MacPPC and various Unix.
platform is a read-only property.
Property. Specifies the vertical dimension, in pixels, of the window's content area.
[windowReference.]innerWidth
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
To create a window smaller than 100 x 100 pixels, set this property in a signed script.
Property. Specifies the horizontal dimension, in pixels, of the window's content area.
[windowReference.]innerWidth
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
To create a window smaller than 100 x 100 pixels, set this property in a signed script.
Object. Represents the Navigator window's location bar.
[windowReference.]locationbar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The locationbar object has one property, visible, that allows you to hide or show the location bar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the location bar of myWindow.
myWindow.locationbar.visible=false
Object. Represents the Navigator window's menu bar.
[windowReference.]menubar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The menubar object has one property, visible, that allows you to hide or show the menu bar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the menu bar of myWindow.
myWindow.menubar.visible=false
Property. Specifies the vertical dimension, in pixels, of the window's outside boundary.
[windowReference.]innerWidth
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
To create a window smaller than 100 x 100 pixels, set this property in a signed script.
Property. Specifies the horizontal dimension, in pixels, of the window's outside boundary.
[windowReference.]innerWidth
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
To create a window smaller than 100 x 100 pixels, set this property in a signed script.
Object. Represents the Navigator window's personal bar (also called the directories bar).
[windowReference.]personalbar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The personalbar object has one property, visible, that allows you to hide or show the personal bar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the personal bar of myWindow.
myWindow.personalbar.visible=false
Object. Represents the Navigator window's scroll bars.
[windowReference.]scrollbar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The scrollbars object has one property, visible, that allows you to hide or show the menubar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the scroll bar of myWindow.
myWindow.scrollbars.visible=false
Object. Represents the Navigator window's status bar.
[windowReference.]statusbar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The statusbar object has one property, visible, that allows you to hide or show the status bar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the status bar of myWindow.
myWindow.statusbar.visible=false
Object. Represents the Navigator window's tool bar.
[windowReference.]toolbar.visible
windowReference is either the name of a window object or one of the synonyms top or parent.
window object
The toolbar object has one property, visible, that allows you to hide or show the toolbar of the specified window.
This property must be set in a signed script.
visible = [true, false] | [1, 0]
The following example hides the tool bar of myWindow.
myWindow.toolbar.visible=false
Regular expressions are patterns used to match character combinations in strings. The patterns can be constructed using the same syntax as regular expressions in PERL and passed as arguments to the String object's new methods match, replace, and split. They can also be constructed from JavaScript strings using the new RegExp object.
Regular expression patterns are delimited by open and close slash characters: /pattern/. The pattern is composed of simple characters, such as /abc/, or a combination of simple and special characters, such as /ab*c/ or /Chapter \d+\.\d*/ .
The first example, /abc/, matches character combinations in strings only when exactly the characters 'abc' occur together and in that order. Such a match would succeed in the strings "Hi, do you know your abc's?" and "The latest airplane designs evolved from slabcraft." In both cases the match is with the substring "abc". There is no match in the string "Grab crab" because it does not contain the substring "abc".
The second example, /ab*c/, matches any character combination in which a single 'a' is followed by zero or more 'b's and then immediately followed by 'c'. For example, in the string "cbbabbbbcdebc", the pattern matches the substring "abbbbc".
The third example, /Chapter \d+\.\d*/, illustrates additional escaped and special characters of the regular expression syntax. It represents the pattern described by:
Precisely the characters "Chapter ", followed by one or more numeric characters (\d means any numeric character and + means one or more times), followed by a decimal point (which in itself is a special character! Preceding the decimal point with \ means the pattern must look for the literal character "."), followed by any numeric character zero or more times (\d means numeric character, * means zero or more times.)
This pattern is found in these strings: "Open Chapter 4.3, paragraph 6" and "Chapter 1.13." The pattern is not found in these strings: "Chapters 3 and 4", "Chapter A.12" and "In the Next Chapter".
For a description of the full syntax and its special characters see any good PERL reference book. (Documentation of this syntax will be included in a revised version of this document.)
The String object has three new methods that work with regular expressions:
string.match(matchString)
matchString is a regular expression pattern
To ignore case, use the i option when constructing the regular expression. For example:
string.match(/chapter /i)
string.replace(findString, subString)
findString is a regular expression pattern. This is the pattern you want to find in the string.
subString is a string to replace the string found with findString
To ignore case, use the i option when constructing the regular expression. For example:
string.replace(/chapter /i, "Title")
To perform a global replace, use the g option when constructing the regular expression. For example:
string.replace(/Chapter /g, "Title")
To perform a global replace and ignore case, use the ig option when constructing the regular expression. For example:
string.replace(/chapter /ig, "Title")
string.split(stringToBreakUp)
stringToBreakup is a regular expression pattern. Find the pattern and remove it from the string.
The following example uses the match method to find a pattern match:
<SCRIPT LANGUAGE="JavaScript1.2"> s = "For more information, see Chapter 3.4.5.1" pattern = /(Chapter \d+(\.\d)*)/ //the parenthesis are used for memory found = s.match(pattern) document.write(found) </SCRIPT >
pattern returns an array (found) with the values Chapter 3.4.5.1,.1. Chapter 3.4.5.1 is the first value remembered from (Chapter \d+(\.\d)*) and .1 is the second value, remembered from (\.\d)*.
The following example uses the split, replace and sort methods to create a list of sorted names.
<SCRIPT LANGUAGE="JavaScript1.2"> /********* * This script illustrates the formation of regular expressions * and the use of string.split() and string.replace(). * * It cleans a roughly-formatted input string containing * names (first name first) separated by blanks, tabs and * exactly one semicolon. * * It reverses the name order (last name first) and sorts the list. *********/ /********* * The name string contains multiple spaces and tabs, * and may have multiple spaces between first and last names. *********/ names = new String ( "Harry Trump ;Fred Barney; Helen Rigby ; Bill Abel ;Chris Hand ") document.write ("---------- Original String" + "<BR>" + "<BR>") document.write (names + "<BR>" + "<BR>") /********* * Prepare two regular expression patterns and array storage. * Split the string into array elements. *********/ // pattern: possible white space then semicolon then possible white space pattern = /\s*;\s*/
// break the string into pieces separated by the pattern above and // and store the pieces in an array called nameList nameList = names.split (pattern)
// new pattern: one or more characters then spaces then characters // use parentheses to "memorize" portions of the pattern // the memorized portions are referred to later pattern = /(\w+)\s+(\w+)/
// new array for holding names being processed bySurnameList = new Array; /********* * Display the name array and populate the new array * with comma-separated names, last first. * * The replace method removes anything matching the pattern * and replaces it by the memorized string - 2nd memorized portion * followed by comma space followed by 1st memorized portion. * * The variables $1 and $2 refer to the portions * memorized while matching the pattern. *********/ document.write ("---------- After Split by Regular Expression" + "<BR>") for ( i = 0; i < nameList.length; i++) { document.write (nameList[i] + "<BR>") bySurnameList[i] = nameList[i].replace (pattern, "$2, $1") } /********* * Display the new array. *********/ document.write ("---------- Names Reversed" + "<BR>") for ( i = 0; i < bySurnameList.length; i++) { document.write (bySurnameList[i] + "<BR>") } /********* * Sort by last name, then display the sorted array. *********/ bySurnameList.sort() document.write ("---------- Sorted" + "<BR>") for ( i = 0; i < bySurnameList.length; i++) { document.write (bySurnameList[i] + "<BR>") } document.write ("---------- End" + "<BR>") </SCRIPT >
The new RegExp object contains the pattern of a regular expression and its prototype contains 9 memory slots described below.
The constructor of the RegExp object provides runtime construction of regular expressions. Unlike the compile time PERL syntax /pattern/, RegExp ("pattern") creates a regular expression at execution time. Note that the normal string escape rules are necessary to quote special string characters. For example: new RegExp ("(\\w+)") is the runtime equivalent of /(\w+)/
RegExp has the methods:
regexp.compile(stringRepresentingRegularExpression)
regexp.exec(string)
Use the compile() method when a regular expression will not change and will be used repeatedly. In the following example, the regular expression will not change during execution of the loop. To avoid rescanning the string on every loop iteration, instead of using:
re = new RegExp("pattern") while (cond) { ... // use re inside loop ... }
it is more efficient to use:
// make a regular expression from "pattern", put it in re re.compile("pattern") while (cond) { ... // use re inside loop ... }
The regexp.exec(string) method executes the pattern match represented by regexp on its string argument. This is the dual of string.match(regexp). Differences will be described in the update to this document.
When regular expressions are constructed with new RegExp( ) or compiled with expression.compile( ), an optional second argument can be used to make the pattern case insensitive, or to make it a global rather than single case pattern match. That is:
The properties $1, ..., $9 of RegExp are storage for memorized portions found during pattern matching. For example:
<SCRIPT LANGUAGE="JavaScript1.2"> s = "hdsaofi(&(&t4wqhdfsajg6yr9ycho xi9sodauajgfdas890" re = /(\w+)\W+(\w+)/ // match alphanumeric, nonalphanumeric, alphanumeric x = s.match (re) // and during the match memorize two portions document.write (RegExp.$1 + "<BR>") // writes hdsaofi document.write (RegExp.$2 + "<BR>") // writes t4wqhdfsajg6yr9ycho document.write (RegExp.$3 + "<BR>") // writes nothing since not filled </SCRIPT >
For additional power and functionality, scripts can now gain access to normally restricted information. This is achieved through signed scripts that request expanded privileges. A signature verifies the person or organization that produced the script. When your script requests expanded privileges, the user is given the opportunity to check the validity of the signature and either grant or deny the expanded privileges.
Note: This new functionality provides greater security than tainting. Tainting has been disabled.
This section contains:
Using the JAR Packager provides a description of digital signatures, certificates, and Java Archive (JAR) files (the file that holds the signatures).
Introduction to the Capabilities Classes describes the Java security model for signed applets, the model from which signed scripts is adapted.
1. Include the ARCHIVE and ID attributes in the <SCRIPT> tag. For information, see The Concepts of Signed Scripts.
2. Include calls to Java functions requesting expanded privileges. For information, see Expanded Privileges.
3. Sign the script with the JAR Packager. For information, see Using the JAR Packager.
The following list outlines the basic concepts of signed scripts. These are explained in this section.
A script that requests privileges must be signed. The signature lets the user know who developed the script, and based on this information, the user can decide whether or not to grant privileges. For any one script to request privileges, all scripts on the HTML page must be signed.
You can sign in-line scripts and event handlers that use scripts. You can't sign javascript: URLs.
A signed script requires the following information:
For example:
<SCRIPT ARCHIVE="myArchive.jar" ID="1"> document.write("This script is signed."); </SCRIPT>
When signing event handlers, ARCHIVE is not specified; instead, the handler must be preceded by a script containing ARCHIVE. For example:
<SCRIPT ARCHIVE="myArchive.jar" ID="1"> ... </SCRIPT>
<FORM> <INPUT TYPE="button" VALUE="Click Here" onClick="alert('A signed script')" ID="2"> </FORM>
You need only specify the ARCHIVE file once. If you include the ARCHIVE file in the first script on your HTML page, the remaining scripts use the same archive. This is not implemented in pr3. For now, you must include ARCHIVE in all <SCRIPT> tags. Because ID is specific to a script, you need to include it in each script. For example:
<SCRIPT ARCHIVE="myArchive.jar" ID="1"> document.write("This script is signed."); </SCRIPT>
<SCRIPT ID="2"> document.write("This script is signed too."); </SCRIPT>
Changes to a signed script's byte stream invalidate the script's signature. This includes moving the HTML page between platforms that have different representations of text. For example, moving an HTML page from a Windows server to a UNIX server changes the byte stream and invalidates the signature. (This doesn't include viewing pages from multiple platforms.) To avoid this, you can move the page in binary mode. Note that doing so changes the appearance of the page in your editor but not in the browser.
To access restricted information, a signed script must include a function that calls Netscape's Java security classes and requests expanded privileges. The Java classes are explained in detail in Introduction to the Capabilities Classes.
The function includes three lines of code:
//get an instance of class Target //the Target represents the resource you want to access //someTarget is described in Targets
var targ = netscape.security.Target.findTarget("someTarget");
//get an instance of the class PrivilegeManager //the PrivilegeManager keeps track of who is allowed to access targets
var mgr == netscape.security.AppletSecurity.getPrivilegeManager();
//enable privilege to access information
mgr.enablePrivilege(targ);
When the script calls these Java classes, the signature is verified, and if the signature is valid, expanded privileges are granted. If necessary, a dialog is displayed that tells the user who wrote the application and gives the user the option to grant or deny expanded privileges.
Note: Privileges are granted only in the requesting function and any functions the requesting function calls. When the script leaves that function, privileges no longer apply.
The types of information you can access are called targets. These are listed below.
Target | Description |
---|---|
UniversalBrowserRead | allows reading of data from the browser that are normally private |
UniversalBrowserWrite | allows modification of data in a browser that are normally unmodifiable |
UniversalFileRead | allows a script to set the 'file' part of a file upload widget. This allows an arbitrary local file to be uploaded to wherever the form gets submitted. |
UniversalSendMail | allows program to send mail in the user's name |
The following script includes a button, that, when clicked, displays an alert dialog containing part of the URL history of the browser. To work properly, the script must be signed.
<SCRIPT ARCHIVE="myArchive.jar" ID="1">
function getHistory(i) { //Attempt to access privileged information return history[i]; }
function getImmediateHistory() { //Request privilege var targ = netscape.security.Target.findTarget("UniversalBrowserRead"); var mgr = netscape.security.AppletSecurity.getPrivilegeManager(); mgr.enablePrivilege(targ);
return getHistory(1); }
</SCRIPT> ... <INPUT TYPE="button" onClick="alert(getImmediateHistory());" ID="2">
The break statement can now include an optional label that allows the program to break out of a labeled statement. This type of break must be in a statement identified by the label used by break.
The statements in a labeled statement can be of any type.
break label
label is the identifier associated with the label of the statement.
In the following example, a statement labeled checkiandj contains a statement labeled checkj. If break is encountered, the program breaks out of the checkj statement and continues with the remainder of the checkiandj statement. If break had a label of checkiandj, the program would break out of the checkiandj statement and continue at the statement following checkiandj.
checkiandj : if (4==i) { document.write("You've entered " + i + ".<BR>"); checkj : if (2==j) { document.write("You've entered " + j + ".<BR>"); break checkj; document.write("The sum is " + (i+j) + ".<BR>"); } document.write(i + "-" + j + "=" + (i-j) + ".<BR>"); }
The continue statement can now include an optional label that allows the program to terminate execution of a labeled statement and continue to the specified labeled statement. This type of continue must be in a looping statement identified by the label used by continue.
continue label
label is the identifier associated with the label of the statement.
In the following example, a statement labeled checkiandj contains a statement labeled checkj. If continue is encountered, the program continues at the top of the checkj statement. Each time continue is encountered, checkj re-iterates until its condition returns false. When false is returned, the remainder of the checkiandj statement is completed. checkiandj re-iterates until its condition returns false. When false is returned, the program continues at the statement following checkiandj.
If continue had a label of checkiandj, the program would continue at the top of the checkiandj statement.
checkiandj : while (i<4) { document.write(i + "<BR>"); i+=1; checkj : while (j>4) { document.write(j + "<BR>"); j-=1; if ((j%2)==0); continue checkj; document.write(j + " is odd.<BR>"); } document.write("i = " + i + "<br>"); document.write("j = " + j + "<br>"); }
The do while statement executes its statements until the test condition evaluates to false. Statement is executed at least once.
do statement while (condition);
statement is a block of statements that is executed at least once and is re-executed each time the condition evaluates to true.
condition is evaluated after each pass through the loop. If condition evaluates to true, the statements in the preceeding block are re-executed. When condition evaluates to false, control passes to the statement following do while.
In the following example, the do loop iterates at least once and re-iterates until i is no longer less than 5.
do { i+=1 document.write(i); } while (i<5);
A labeled statement provides an identifier that can be used with break or continue to indicate where the program should continue execution.
In a labeled statement, break or continue must be followed with a label, and the label must be the identifier of the labeled statement containing break or continue.
label : statement
statement is a block of statements. break can be used with any labeled statement, and continue can be used with looping labeled statements.
For an example of a labeled statement using break, see break.
For an example of a labeled statement using continue, see continue.
A switch statement allows a program to evaluate an expression and attempt to match the expression's value to a case label. If a match is found, the program executes the associated statement.
The program first looks for a label matching the value of expression and then executes the associated statement. If no matching label is found, the program looks for the optional default statement, and if found, executes the associated statement. If no default statement is found, the program continues execution at the statement following the end of switch.
The optional break statement associated with each case label ensures that the program breaks out of switch once the matched statement is executed and continues execution at the statement following switch. If break is omitted, the program continues execution at the next statement in the switch statement.
switch (expression){ case label : statement; break; case label : statement; break; ... default : statement; }
expression is the value matched against label.
label is an identifier used to match against expression.
statement is any statement.
In the following example, if expression evaluates to "Bananas", the program matches the value with case "Bananas" and executes the associated statement. When break is encountered, the program breaks out of switch and executes the statement following switch. If break were omitted, the statement for case "Cherries" would also be executed.
switch (i) { case "Oranges" : document.write("Oranges are $0.59 a pound.<BR>"); break; case "Apples" : document.write("Apples are $0.32 a pound.<BR>"); break; case "Bananas" : document.write("Bananas are $0.48 a pound.<BR>"); break; case "Cherries" : document.write("Cherries are $3.00 a pound.<BR>"); break; default : document.write("Sorry, we are out of " + i + ".<BR>"); } document.write("Is there anything else you'd like?<BR>");
Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to this document (the "Document"). Use of the Document is governed by applicable copyright law. Netscape may revise this Document from time to time without notice.
THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OR DATA, INTERRUPTION OF BUSINESS, OR FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND, ARISING FROM ANY ERROR IN THIS DOCUMENT.
The Document is copyright © 1997 Netscape Communications Corporation. All rights reserved.
Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries. Netscape's logos and Netscape product and service names are also trademarks of Netscape Communications Corporation, which may be registered in other countries. Other product and brand names are trademarks of their respective owners.
The downloading, export or reexport of Netscape software or any underlying information or technology must be in full compliance with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation to the U.S. Government is with restricted rights as described in the license agreement accompanying Netscape software.