[Previous reference file]
Function. Adds tainting to a data element or script.
taint(dataElementName)
dataElementName is the property, variable, function,
or object to taint. If omitted, taint is added to the script itself.
Navigator 3.0
Tainting prevents other scripts from passing information
that should be secure and private, such as directory structures or user session
history. JavaScript cannot pass tainted values on to any server without the
end user's permission.
Use taint to mark data that
otherwise is not tainted.
In some cases, control flow rather than data flow carries
tainted information. In these cases, taint is added to the script's window.
You can add taint to the script's window by calling taint with no
arguments. See "Tainting that results from
conditional statements".
taint does not modify its argument; instead, it returns
a marked copy of the value, or, for objects, an unmarked reference to the
value.
The following statement adds taint to a property so that
a script cannot send it to another server without the end user's
permission:
taintedStatus=taint(window.defaultStatus)
// taintedStatus now cannot be sent in a URL or form post without
// the end user's permission
domain property;
taintEnabled method;
untaint function;
"Using data tainting for security"
Method. Specifies whether data tainting is enabled.
navigator.taintEnabled()
navigator
Navigator 3.0
Tainting prevents other scripts from passing information
that should be secure and private, such as directory structures or user session
history. JavaScript cannot pass tainted values on to any server without the
end user's permission.
Use taintEnabled to determine
if data tainting is enabled. taintEnabled returns true if data tainting
is enabled, false otherwise. The user enables or disables data tainting by
using the environment variable NS_ENABLE_TAINT.
The following code executes function1 if data tainting
is enabled; otherwise it executes function2.
if (navigator.taintEnabled()) {
function1()
}
else function2()
domain property;
taint,
untaint functions;
"Using data tainting for security"
Method. Returns the tangent of a number.
Math.tan(number)
number is a numeric expression representing the size
of an angle in radians, or a property of an existing object.
Math
Navigator 2.0
The tan method returns a numeric value that represents
the tangent of the angle.
The following function returns the tangent of the variable
x:
function getTan(x) {
return Math.tan(x)
}
If you pass getTan the value Math.PI/4, it returns
0.9999999999999999.
acos,
asin, atan,
atan2, cos,
sin methods
Property. For form, a string specifying the name
of the window that responses go to after a form has been submitted. For
link, a string specifying the name of the window that displays the
content of a clicked hypertext link.
1. formName.target
2. links[index].target
3. areaName.target
formName is either the name of a form or an element
in the forms0 array.
index is an integer representing a Link object
or the name of a Link object as specified by the NAME attribute.
areaName is the value of the NAME attribute of an
Area object.
Area object (see Link object),
Form object, Link
object
-
-
Navigator 2.0
-
Navigator 3.0: property of Area
No
The target property initially reflects the TARGET
attribute of the <A>, <AREA>, and <FORM> tags; however,
setting target overrides these attributes.
You can set target using a string, if the string
represents a window name. The target property cannot be assigned the
value of a JavaScript expression or variable.
You can set the target property at any time.
The following example specifies that responses to the
musicInfo form are displayed in the msgWindow window:
document.musicInfo.target="msgWindow"
For form: action,
encoding,
method properties;
Form object
Object. A text input field on an HTML form. The user can
enter a word, phrase, or series of numbers in a text field.
To define a Text object, use standard HTML syntax
with the addition of JavaScript event handlers:
<INPUT
TYPE="text"
NAME="textName"
VALUE="textValue"
SIZE=integer
[onBlur="handlerText"]
[onChange="handlerText"]
[onFocus="handlerText"]
[onSelect="handlerText"]>
NAME="textName" specifies the name of the Text
object. You can access this value using the name property, and you
can use this name when indexing the elements array.
VALUE="textValue" specifies the initial value of
the Text object. You can access this value using the
defaultValue property.
SIZE=integer specifies the number of characters the
Text object can accommodate without scrolling.
To use a Text object's properties and methods:
1. textName.propertyName
2. textName.methodName(parameters)
3. formName.elements[index].propertyName
4. formName.elements[index].methodName(parameters)
textName is the value of the NAME attribute of a
Text object.
formName is either the value of the NAME attribute
of a Form object or an element in the forms array.
index is an integer representing a Text object
on a form or the name of a Text object as specified by the NAME
attribute.
propertyName is one of the properties listed below.
methodName is one of the methods listed below.
Form object
-
-
Navigator 2.0
-
Navigator 3.0: added type property
A Text object on a form looks as follows:
A Text object is a form element and must be defined
within a <FORM> tag.
Text objects can be updated (redrawn) dynamically
by setting the value property (this.value).
If a form contains only one element, a Text object,
then when the user enters a value and presses Return, the form submits. (This
is a standard HTML feature.)
The Text object has the following properties:
The Text object has the following methods:
Example 1. The following example creates a
Text object that is 25 characters long. The text field appears immediately
to the right of the words "Last name:". The text field is blank when the
form loads.
<B>Last name:</B> <INPUT TYPE="text" NAME="last_name" VALUE="" SIZE=25>
Example 2. The following example creates two
Text objects on a form. Each object has a default value. The
city object has an onFocus event handler that selects all the text
in the field when the user tabs to that field. The state object has
an onChange event handler that forces the value to uppercase.
<FORM NAME="form1">
<BR><B>City: </B><INPUT TYPE="text" NAME="city" VALUE="Anchorage"
SIZE="20" onFocus="this.select()">
<B>State: </B><INPUT TYPE="text" NAME="state" VALUE="AK" SIZE="2"
onChange="this.value=this.value.toUpperCase()">
</FORM>
See also the examples for the
onBlur,
onChange,
onFocus, and
onSelect event handlers.
FileUpload object,
Form object,
Password object,
String object,
Textarea object
Property. A string specifying the text that follows an
<OPTION> tag in a Select object.
1. selectName.options[index].text
2. optionName.text
selectName is either the value of the NAME attribute
of a Select object or an element in the elements array.
index is an integer representing an option in a
Select object.
optionName is the name of a Select object
option created using the Option() constructor.
Option object (see Select
object), options array (see Select
object)
-
-
Navigator 2.0
-
Navigator 3.0: The text property of the options array can 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.
Yes
The text property initially reflects the text that
follows an <OPTION> tag in a Select object.
You can set the text property at any time and the
text displayed by the option in the Select object changes.
In the following example, the getChoice function
returns the value of the text property for the selected option. The
for loop evaluates every option in the musicType Select
object. The if statement finds the option that is selected.
function getChoice() {
for (var i = 0; i < document.musicForm.musicType.length; i++) {
if (document.musicForm.musicType.options[i].selected == true) {
return document.musicForm.musicType.options[i].text
}
}
return null
}
The previous example assumes that the Select object
is similar to the following:
<SELECT NAME="musicType">
<OPTION SELECTED> R&B
<OPTION> Jazz
<OPTION> Blues
<OPTION> New Age
</SELECT>
Object. A multiline input field on an HTML form. The user
can use a textarea field to enter words, phrases, or numbers.
To define a text area, use standard HTML syntax with the
addition of JavaScript event handlers:
<TEXTAREA
NAME="textareaName"
ROWS="integer"
COLS="integer"
[onBlur="handlerText"]
[onChange="handlerText"]
[onFocus="handlerText"]
[onSelect="handlerText"]>
textToDisplay
</TEXTAREA>
NAME="textareaName" specifies the name of the
Textarea object. You can access this value using the name property,
and you can use this name when indexing the elements array.
ROWS="integer" and COLS="integer" define the
physical size of the displayed input field in numbers of characters.
textToDisplay specifies the initial value of the
Textarea object. A Textarea allows only ASCII text, and new
lines are respected. You can access this value using the defaultValue
property.
To use a Textarea object's properties and methods:
1. textareaName.propertyName
2. textareaName.methodName(parameters)
3. formName.elements[index].propertyName
4. formName.elements[index].methodName(parameters)
textareaName is the value of the NAME attribute of
a Textarea object.
formName is either the value of the NAME attribute
of a Form object or an element in the forms array.
index is an integer representing a Textarea
object on a form or the name of a Textarea object as specified by
the NAME attribute.
propertyName is one of the properties listed below.
methodName is one of the methods listed below.
Form object
-
-
Navigator 2.0
-
Navigator 3.0: added type property
A Textarea object on a form looks as follows:
A Textarea object is a form element and must be defined
within a <FORM> tag.
Textarea objects can be updated (redrawn) dynamically
by setting the value property (this.value).
To begin a new line in a Textarea object, you can
use a newline character. Although this character varies from platform to
platform (Unix is \n, Windows is \r, and Macintosh is \n), JavaScript checks
for all newline characters before setting a string-valued property and translates
them as needed for the user's platform. You could also enter a newline character
programmatically--one way is to test the appVersion property to determine
the current platform, then set the newline character accordingly. See the
appVersion property for an example.
The Textarea object has the following properties:
The Textarea object has the following methods:
Example 1. The following example creates a
Textarea object that is six rows long and 55 columns wide. The textarea
field appears immediately below the word "Description:". When the form loads,
the Textarea object contains several lines of data, including one
blank line.
<B>Description:</B>
<BR><TEXTAREA NAME="item_description" ROWS=6 COLS=55>
Our storage ottoman provides an attractive way to
store lots of CDs and videos--and it's versatile
enough to store other things as well.
It can hold up to 72 CDs under the lid and 20 videos
in the drawer below.
</TEXTAREA>
Example 2. The following example creates a string
variable containing newline two characters for different platforms. When
the user clicks the button, the Textarea object is populated with
the value from the string variable. The result is three lines of text in
the Textarea object.
<SCRIPT>
myString="This is line one.\nThis is line two.\rThis is line three."
</SCRIPT>
<FORM NAME="form1">
<INPUT TYPE="button" Value="Populate the textarea"
onClick="document.form1.textarea1.value=myString">
<P>
<TEXTAREA NAME="textarea1" ROWS=6 COLS=55></TEXTAREA>
See also the examples for the
onBlur,
onChange,
onFocus, and
onSelect event handlers.
Form object,
Password object,
String object, Text
object
Property. A string representing the title of a document.
document.title
document
Navigator 2.0
Yes
The title property is a reflection of the value specified
within the <TITLE> and </TITLE> tags. If a document does not
have a title, the title property is null.
title is a read-only property.
In the following example, the value of the title
property is assigned to a variable called docTitle:
var newWindow = window.open("http://home.netscape.com")
var docTitle = newWindow.document.title
Method. Converts a date to a string, using the Internet GMT
conventions.
dateObjectName.toGMTString()
dateObjectName is either the name of a Date
object or a property of an existing object.
Date
Navigator 2.0
The exact format of the value returned by toGMTString
varies according to the platform.
In the following example, today is a Date
object:
today.toGMTString()
In this example, the toGMTString method converts
the date to GMT (UTC) using the operating system's time-zone offset and returns
a string value that is similar to the following form. The exact format depends
on the platform.
Mon, 18 Dec 1995 17:28:35 GMT
toLocaleString method
Method. Converts a date to a string, using the current locale's
conventions.
dateObjectName.toLocaleString()
dateObjectName is either the name of a Date
object or a property of an existing object.
Date
Navigator 2.0
If you are trying to pass a date using toLocaleString,
be aware that different locales assemble the string in different ways. Using
methods such as getHours, getMinutes, and getSeconds
gives more portable results.
In the following example, today is a Date
object:
today.toLocaleString()
In this example, toLocaleString returns a string value
that is similar to the following form. The exact format depends on the
platform.
12/18/95 17:28:35
toGMTString method
Method. Returns the calling string value converted to
lowercase.
stringName.toLowerCase()
stringName is any string or a property of an existing
object.
String
Navigator 2.0
The toLowerCase method returns the value of
stringName converted to lowercase. toLowerCase does not affect
the value of stringName itself.
The following example displays the lowercase string
"alphabet":
var upperText="ALPHABET"
document.write(upperText.toLowerCase())
toUpperCase method
Property. The top property is a synonym for the top-most
Navigator window, which is a "document window" or "Web Browser window."
1. top.propertyName
2. top.methodName
3. top.frameName
4. top.frames[index]
propertyName is defaultStatus, status,
or length.
methodName is any method associated with the
window object.
frameName and frames[index] are ways to refer
to frames.
window object
Navigator 2.0
No
The top property refers to the top-most window that
contains frames or nested framesets. Use the top property to refer
to this ancestor window.
The top property is read-only. The value of the
top property is
<object objectReference>
where objectReference is an internal reference.
The statement top.close() closes the top-most
ancestor window.
The statement top.length specifies the number
of frames contained within the top-most ancestor window. When the top-most
ancestor is defined as follows, top.length returns three:
<FRAMESET COLS="30%,40%,30%">
<FRAME SRC=child1.htm NAME="childFrame1">
<FRAME SRC=child2.htm NAME="childFrame2">
<FRAME SRC=child3.htm NAME="childFrame3">
</FRAMESET>
The following example sets the background color of a frame
called myFrame to red. myFrame is a child of the top-most ancestor
window.
top.myFrame.document.bgColor="red"
Method. Returns a string representing the specified
object.
objectName.toString()
numberObjectName.toString([radix])
objectName is the object to convert to a string.
numberObjectName is the Number object to
convert to a string.
radix is an integer between 2 and 16 specifying the
base to use for representing numeric values.
toString is a method of all objects.
Navigator 2.0
Navigator 3.0: added radix
Yes, for history, location, Link, and any form input element;
No for all other objects
Every object has a toString method that is automatically
called when it is to be represented as a text value or when an object is
referenced in a string concatenation. For example, the following examples
require theDog to be represented as a string:
document.write(theDog)
document.write("The dog is " + theDog)
You can use toString within your own code to convert
an object into a string, and you can create your own function to be called
in place of the default toString method.
Every object type has a built-in toString method,
which JavaScript calls whenever it needs to convert an object to a string.
If an object has no string value and no user-defined toString method,
toString returns "[object type]", where type is the
object type or the name of the constructor function that created the object.
For example, if the following Image object named "sealife" exists,
sealife.toString() returns [object Image].
<IMG NAME="sealife" SRC="images\seaotter.gif" ALIGN="left" VSPACE="10">
You can create a function to be called in place of the
default toString method. The toString method takes no arguments
and should return a string. The toString method you create can be
any value you want, but it will be most useful if it carries information
about the object.
Suppose you have an object type Dog and you want
to create a toString method for it. The following code defines the
Dog object type and creates theDog, an object of type
Dog:
function Dog(name,breed,color,sex) {
this.name=name
this.breed=breed
this.color=color
this.sex=sex
}
theDog = new Dog("Gabby","Lab","chocolate","girl")
The following code creates objectToString, the function
that will be used in place of the default toString method. This function
generates a string containing each property, of the form "property
= value;".
function objectToString() {
var ret = "Object " + this.name + " is ["
for (var prop in this)
ret += " " + prop + " is " + this[prop] + ";"
return ret + "]"
}
The following code assigns the user-defined function to
the object's toString method:
Dog.prototype.toString = objectToString
With the preceding code in place, any time theDog
is used in a string context, JavaScript automatically calls the
objectToString function, which returns the following string:
Object Gabby is [ name is Gabby; breed is Lab; color is
chocolate; sex is girl; toString is function objectToString() { var ret =
"Object " + this.name + " is ["; for (var prop in this) { ret += " " + prop
+ " is " + this[prop] + ";"; } return ret + "]"; } ;]
An object's toString method
is usually invoked by JavaScript, but you can invoke it yourself as
follows:
alert(theDog.toString())
For Array objects, the built-in toString
method joins the array and returns one string containing each array element
separated by commas. For example, the following code creates an array and
uses toString to convert the array to a string while writing output.
var monthNames = new Array("Jan","Feb","Mar","Apr")
document.write("monthNames.toString() is " + monthNames.toString())
The output is as follows:
monthNames.toString() is Jan,Feb,Mar,Apr
For Boolean objects and values, the built-in
toString method returns "true" or "false" depending on the value of
the boolean object. In the following code, flag.toString returns
"true".
flag = new Boolean(true)
document.write("flag.toString() is " + flag.toString() + "<BR>")
For Function objects, the built-in toString
method decompiles the function back into the JavaScript source that defines
the function. This string includes the function keyword, the argument
list, curly braces, and function body.
For example, suppose you create the function Dog
shown in "User-defined toString methods".
Any time Dog is used in a string context, JavaScript automatically
calls the toString function, which returns the following string:
function Dog(name, breed, color, sex) { this.name = name;
this.breed = breed; this.color = color; this.sex = sex; }
You can use toString on numeric values, but not
on numeric literals:
// The next two lines are valid
var howMany=10
document.write("howMany.toString() is " + howMany.toString() + "<BR>")
// The next line causes an error
document.write("45.toString() is " + 45.toString() + "<BR>")
Example 1: The location object. The following example
prints the string equivalent of the current location.
document.write("location.toString() is " + location.toString() + "<BR>")
The output is as follows:
file:///C|/TEMP/myprog.html
Example 2: Object with no string value. Suppose
the following Image object named "sealife" exists:
<IMG NAME="sealife" SRC="images\seaotter.gif" ALIGN="left" VSPACE="10">
Because the Image object itself has no string
equivalent, sealife.toString() will return the following:
[object Image]
Example 3: The radix parameter. The following example
prints the string equivalents of the numbers 0 through 9 in decimal and
binary.
for (x = 0; x < 10; x++) {
document.write("Decimal: ", x.toString(10), " Binary: ",
x.toString(2), "<BR>")
}
The preceding example produces the following output:
Decimal: 0 Binary: 0
Decimal: 1 Binary: 1
Decimal: 2 Binary: 10
Decimal: 3 Binary: 11
Decimal: 4 Binary: 100
Decimal: 5 Binary: 101
Decimal: 6 Binary: 110
Decimal: 7 Binary: 111
Decimal: 8 Binary: 1000
Decimal: 9 Binary: 1001
prototype property;
valueOf method
Method. Returns the calling string value converted to
uppercase.
stringName.toUpperCase()
stringName is any string or a property of an existing
object.
String
Navigator 2.0
The toUpperCase method returns the value of
stringName converted to uppercase. toUpperCase does not affect
the value of stringName itself.
The following example displays the string "ALPHABET":
var lowerText="alphabet"
document.write(lowerText.toUpperCase())
toLowerCase method
Property. For form elements created with the
<INPUT>, <SELECT>, or <TEXTAREA> tags, a string specifying
the type of form element. For MimeType objects, the a string specifying
the name of the MIME type.
1. objectName.type
2. navigator.mimeTypes[index].type
objectName is either the value of the NAME attribute
of a form element object (button, checkbox, file upload, hidden, password,
radio, reset, select, submit, text, or textarea) or an element in the
elements array.
index is either an integer representing a MIME type
supported by the client or a string containing the type of a MimeType
object (from the type property).
Button object,
Checkbox object,
FileUpload object,
Hidden object,
MimeType object,
Password object,
Radio object, Reset
object, Select object,
Submit object, Text
object, Textarea object
Navigator 3.0
No
For MimeType objects, the type property is
a unique string that distinguishes the MIME type from all others; for example
"video/mpeg" or "audio/x-wav".
For form elements, the value of the type property
is assigned as follows:
type is a read-only property.
The following example writes the value of the type
property for every element on a form.
for (var i = 0; i < document.form1.elements.length; i++) {
document.writeln("<BR>type is " + document.form1.elements[i].type)
}
See also the examples for the
MimeType object.
For MimeType objects:
description,
enabledPlugin,
suffixes properties
Function. Returns the ASCII string for the specified
value.
unescape("string")
string is a string or a property of an existing object,
containing characters in either of the following forms:
-
-
"%integer", where integer is a number between 0 and 255 (decimal)
-
"hex", where hex is a number between 0x0 and 0xFF (hexadecimal)
Navigator 2.0
The string returned by the unescape function is a
series of characters in the ISO Latin-1 character set. The unescape
function is a top-level JavaScript function not associated with any object.
The following example returns "&":
unescape("%26")
The following example returns "!#":
unescape("%21%23")
escape function
Function. Removes tainting from a data element or script.
untaint(dataElementName)
dataElementName is the property, variable, function,
or object to remove tainting from. If omitted, taint is removed from the
script itself.
Navigator 3.0
Tainting prevents other scripts from passing information
that should be secure and private, such as directory structures or user session
history. JavaScript cannot pass tainted values on to any server without the
end user's permission.
Use untaint to clear tainting
that marks data that should not to be sent by other scripts to different
servers.
A script can untaint only data that originated in that
script (that is, only data that has the script's taint code or has the identity
(null) taint code). If you use untaint with a data element from another
server's script (or any data that you cannot untaint), untaint returns
the data without change or error.
In some cases, control flow rather than data flow carries
tainted information. In these cases, taint is added to the script's window.
You can remove taint from the script's window by calling untaint with
no arguments, if the window contains taint only from the current window.
See "Tainting that results from conditional
statements".
untaint does not modify its argument; instead, it
returns an unmarked copy of the value, or, for objects, an unmarked reference
to the value.
The following statement removes taint from a property so
that a script can send it to another server:
untaintedStatus=untaint(window.defaultStatus)
// untaintedStatus can now be sent in a URL or form post by other
// scripts
domain property;
taint function;
"Using data tainting for security"
Property. A string specifying the complete URL of the
document.
document.URL
document
Navigator 2.0
Yes
URL is a read-only property of document containing
the full URL of the document. URL is a string-valued property that
usually matches what window.location.href is set to when you load
the document, but redirection may change location.href.
The following example displays the URL of the current
document:
document.write("The current URL is " + document.URL)
href
Property. A string representing the value of the user-agent
header sent in the HTTP protocol from client to server.
navigator.userAgent
navigator
Navigator 2.0
No
Servers use the value sent in the user-agent header to identify
the client.
userAgent is a read-only
property.
The following example displays userAgent information
for the Navigator:
document.write("The value of navigator.userAgent is " +
navigator.userAgent)
For Navigator 2.0, this displays the following:
The value of navigator.userAgent is Mozilla/2.0 (Win16; I)
appCodeName,
appName,
appVersion,
javaEnabled properties
Method. Returns the number of milliseconds in a Date
object since January 1, 1970, 00:00:00, Universal Coordinated Time (GMT).
Date.UTC(year, month, day [, hrs] [, min] [, sec])
year is a year after 1900.
month is a month between zero and 11.
date is a day of the month between one and 31.
hrs is hours between zero and 23.
min is minutes between zero and 59.
sec is seconds between zero and 59.
Date
Navigator 2.0
UTC takes comma-delimited date parameters and returns
the number of milliseconds since January 1, 1970, 00:00:00, Universal Coordinated
Time (GMT).
Because UTC is a static method of Date, you always
use it as Date.UTC(), rather than as a method of a Date
object you created.
The following statement creates a Date object using
GMT instead of local time:
gmtDate = new Date(Date.UTC(96, 11, 1, 0, 0, 0))
parse method
Property. A string that is related to the VALUE attribute
of its object.
1. objectName.value
2. radioName[index].value
3. selectName.options.[index].value
4. fileUploadName.value
5. optionName.value
objectName is either the value of the NAME attribute
of a Hidden, Password, Text, Textarea,
Button, Reset, Submit, or Checkbox object or
an element in the elements array.
radioName is the value of the NAME attribute of a
Radio object.
selectName is either the value of the NAME attribute
of a Select object or an element in the elements array.
index is an integer representing a radio button in
a Radio object or an option in a Select object.
fileUploadName is either the value of the NAME attribute
of a FileUpload object or an element in the elements array.
optionName is the name of a Select object
option created using the Option() constructor.
-
-
Button object,
Checkbox object,
FileUpload object,
Hidden object, Option object (see
Select object),
Password object,
Radio object, Reset
object, Submit object,
Text object,
Textarea object
-
options array (see Select object)
Navigator 2.0
Navigator 3.0: property of FileUpload, Option
Yes
The value property differs for every object.
When a VALUE attribute is specified in HTML, the
value property is a string that reflects it. This string is displayed
on the face of the button.
When a VALUE attribute is not specified in HTML, the
value property differs for each object:
-
-
For button, it is an empty string.
-
For reset, it is the string "Reset."
-
For submit, it is the string "Submit Query."
These strings are displayed on the faces of the buttons.
value is a read-only property.
Do not confuse the value property with the
name property. The name property is not displayed on-screen;
it is used to reference the objects programmatically.
When a VALUE attribute is specified in HTML, the
value property is a string that reflects it. When a VALUE attribute
is not specified in HTML, the value property is a string that evaluates
to "on." The value property is not displayed on-screen but is returned
to the server if the radio button or checkbox is selected.
You can set the value property at any time.
Do not confuse the value property with the selection
state of the object or the text that is displayed next to each checkbox and
radio button. The checked property determines the selection state
of the object, and the defaultChecked property determines the default
selection state. The text that is displayed is specified following the
<INPUT TYPE="checkbox"> or the <INPUT TYPE="radio"> tag.
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.
The value property is a string that initially reflects
the VALUE attribute. This string is displayed in the text and textarea fields.
The value of this property changes when a user or a program modifies the
field.
You can set the value property at any time. The display
of the Text and Textarea objects updates immediately when you
set the value property.
The value property is a string that initially reflects
the VALUE attribute. This string is represented by asterisks in the
Password object field. The value of this property changes when a user
or a program modifies the field, but the value is always displayed as
asterisks.
If you programmatically set the value property and
then evaluate it, JavaScript returns the current value. If a user interactively
modifies the value in the password field, you cannot evaluate it accurately
unless data tainting is enabled. See "Using
data tainting for security".
For Select object options created using the Option()
constructor, the value property is a string that initially reflects the VALUE
attribute. This value is not displayed onscreen, but is returned to the server
if the option is selected. The value of this property can change when a program
modifies it.
You can set the value property at any time.
The value property is a string that initially reflects
the VALUE attribute. The value of this property can change when a program
modifies it. The value property is not displayed on-screen but is
returned to the server if the option is selected.
You can set the value property at any time.
Do not confuse the value property with the selection
state of the Select object or the text that is displayed as an option.
The selected and selectedIndex properties determine which options
are selected, and the defaultSelected property determines the default
selection state. The text that is displayed in each option is specified by
its text property.
The following function evaluates the value property
of a group of buttons and displays it in the msgWindow window:
function valueGetter() {
var msgWindow=window.open("")
msgWindow.document.write("submitButton.value is " +
document.valueTest.submitButton.value + "<BR>")
msgWindow.document.write("resetButton.value is " +
document.valueTest.resetButton.value + "<BR>")
msgWindow.document.write("helpButton.value is " +
document.valueTest.helpButton.value + "<BR>")
msgWindow.document.close()
}
This example displays the following values:
Query Submit
Reset
Help
The previous example assumes the buttons have been defined
as follows:
<INPUT TYPE="submit" NAME="submitButton">
<INPUT TYPE="reset" NAME="resetButton">
<INPUT TYPE="button" NAME="helpButton" VALUE="Help">
The following function evaluates the value property
of a group of radio buttons and displays it in the msgWindow window:
function valueGetter() {
var msgWindow=window.open("")
for (var i = 0; i < document.valueTest.radioObj.length; i++) {
msgWindow.document.write
("The value of radioObj[" + i + "] is " +
document.valueTest.radioObj[i].value +"<BR>")
}
msgWindow.document.close()
}
This example displays the following values:
on
on
on
on
The previous example assumes the buttons have been defined
as follows:
<BR><INPUT TYPE="radio" NAME="radioObj">R&B
<BR><INPUT TYPE="radio" NAME="radioObj" CHECKED>Soul
<BR><INPUT TYPE="radio" NAME="radioObj">Rock and Roll
<BR><INPUT TYPE="radio" NAME="radioObj">Blues
Method. Returns the primitive value of the specified
object.
objectName.valueOf()
objectName is the object to converted to a value.
valueOf is a method of all objects.
Navigator 3.0
Every object has a valueOf method that is automatically
called when it is to be represented as a primitive value. If an object has
no primitive value, valueOf returns the object itself.
You can use valueOf within your own code to convert
an object into a primitive value, and you can create your own function to
be called in place of the default valueOf method.
Every object type has a built-in valueOf method,
which JavaScript calls whenever it needs to convert an object to a primitive
value.
You rarely need to invoke the valueOf method yourself.
JavaScript automatically invokes it when encountering an object where a primitive
value is expected.
The valueOf method is most useful for the following object
types. Most other objects have no primitive value.
You can create a function to be called in place of the
default valueOf method. The valueOf method takes no
arguments.
Suppose you have an object type myNumberType and
you want to create a valueOf method for it. The following code assigns
a user-defined function to the object's valueOf method:
myNumberType.prototype.valueOf = new Function(functionText)
With the preceding code in place, any time an object of
type myNumberType is used in a context where it is to be represented
as a primitive value, JavaScript automatically calls the function defined
in the preceding code.
An object's valueOf method is usually invoked by
JavaScript, but you can invoke it yourself as follows:
myNumber.valueOf()
Objects in string contexts convert via the toString
method, which is different from String objects converting to string
primitives via valueOf. All string objects have a string conversion,
if only "[object type]". But many objects do not convert to number,
boolean, or function. For information on toString, see
toString.
parseInt function,
toString method;
"typeof"
Property. A string specifying the color of visited links.
document.vlinkColor
document
Navigator 2.0
No
The vlinkColor property is expressed as a hexadecimal
RGB triplet or as one of the string literals listed in
"Color values". This property is the JavaScript
reflection of the VLINK attribute of the <BODY> tag. The default value
of this property is set by the user on the Colors tab of the Preferences
dialog box, which is displayed by choosing General Preferences from the Options
menu. You cannot set this property after the HTML source has been through
layout.
If you express the color as a hexadecimal RGB triplet, you
must use the format rrggbb. For example, the hexadecimal RGB values for salmon
are red=FA, green=80, and blue=72, so the RGB triplet for salmon is
"FA8072."
The following example sets the color of visited links to
aqua using a string literal:
document.vlinkColor="aqua"
The following example sets the color of active links to
aqua using a hexadecimal triplet:
document.vlinkColor="00FFFF"
alinkColor,
bgColor,
fgColor,
linkColor properties
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.
Image
Navigator 3.0
No
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
Property. A string specifying the width of an image in
pixels.
imageName.width
imageName is either the name of an Image object
or an element in the images array.
Image
Navigator 3.0
No
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
Object. The top-level object for each document,
location, and history object group.
To define a window, use the open method:
windowVar = window.open("URL", "windowName" [,"windowFeatures"])
For details on defining a window, see the
open (window object) method.
To use a window object's properties and methods:
1. window.propertyName
2. window.methodName(parameters)
3. self.propertyName
4. self.methodName(parameters)
5. top.propertyName
6. top.methodName(parameters)
7. parent.propertyName
8. parent.methodName(parameters)
9. windowVar.propertyName
10. windowVar.methodName(parameters)
11. propertyName
12. methodName(parameters)
To define an event handler for a window object, use
the <BODY> or <FRAMESET> tags:
<BODY
...
[onBlur="handlerText"]
[onFocus="handlerText"]
[onLoad="handlerText"]
[onUnload="handlerText"]>
</BODY>
<FRAMESET
ROWS="rowHeightList"
COLS="columnWidthList"
[onBlur="handlerText"]
[onFocus="handlerText"]
[onLoad="handlerText"]
[onUnload="handlerText"]>
[<FRAME SRC="URL" NAME="frameName">]
</FRAMESET>
Note
On some platforms, placing an onBlur or onFocus event handler
in a <FRAMESET> tag has no effect. Please see the release notes (after
starting Netscape, choose Release Notes from the Help menu).
For information on the <BODY> and <FRAMESET>
tags, see the document and
Frame objects.
To define an onError event handler for a window
object:
window.onerror=errorHandler
For information on specifying the onError event handler,
see onError event handler.
windowVar is the name of a new window. Use this variable
when referring to a window's properties, methods, and containership.
windowName is the window name to use in the TARGET
attribute of a <FORM> or <A> tag.
propertyName is one of the properties listed below.
methodName is one of the methods listed below.
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.
None
-
-
Navigator 2.0
-
Navigator 3.0: added closed and opener properties; added blur,
focus, and scroll methods; added onBlur, onError, and onFocus
event handlers
The window object is the top-level object in the
JavaScript client hierarchy. Frame objects are also windows.
The self and window properties are synonyms
for the current window, and you can optionally use them to refer to the current
window. For example, you can close the current window by calling either
window.close() or self.close(). You can use these
properties to make your code more readable or to disambiguate the property
reference self.status from a form called status.
See the properties and methods listed below for more examples.
The top and parent properties are also synonyms
that can be used in place of the window name. top refers to the top-most
Navigator window, and parent refers to a window containing a frameset.
See the top and
parent properties.
Because the existence of the current window is assumed,
you do not have to reference the name of the window when you call its methods
and assign its properties. For example, status="Jump to a new
location" is a valid property assignment, and close()
is a valid method call. However, when you open or close a window within an
event handler, you must specify window.open() or
window.close() instead of simply using open() or
close(). Due to the scoping of static objects in JavaScript,
a call to close() without specifying an object name is equivalent
to document.close().
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.
You can reference a window's Frame objects in your
code by using the frames array. The frames array contains an
entry for each frame in a window with a <FRAMESET> tag.
Windows lack event handlers until some HTML is loaded into
them containing a <BODY> or <FRAMESET> tag.
The window object has the following properties:
The following objects are also properties of the
window object:
The window object has the following methods:
In the following example, the document in the top window
opens a second window, window2, and defines pushbuttons that open
a message window, write to the message window, close the message window,
and close window2. The onLoad and onUnload event handlers of the document
loaded into window2 display alerts when the window opens and closes.
win1.html, which defines the frames for the
first window, contains the following code:
<HTML>
<HEAD>
<TITLE>Window object example: Window 1</TITLE>
</HEAD>
<BODY BGCOLOR="antiquewhite">
<SCRIPT>
window2=open("win2.html","secondWindow",
"scrollbars=yes,width=250, height=400")
document.writeln("<B>The first window has no name: "
+ window.name + "</B>")
document.writeln("<BR><B>The second window is named: "
+ window2.name + "</B>")
</SCRIPT>
<FORM NAME="form1">
<P><INPUT TYPE="button" VALUE="Open a message window"
onClick = "window3=window.open('','messageWindow',
'scrollbars=yes,width=175, height=300')">
<P><INPUT TYPE="button" VALUE="Write to the message window"
onClick="window3.document.writeln('Hey there');
window3.document.close()">
<P><INPUT TYPE="button" VALUE="Close the message window"
onClick="window3.close()">
<P><INPUT TYPE="button" VALUE="Close window2"
onClick="window2.close()">
</FORM>
</BODY>
</HTML>
win2.html, which defines the content for
window2, contains the following code:
<HTML>
<HEAD>
<TITLE>Window object example: Window 2</TITLE>
</HEAD>
<BODY BGCOLOR="oldlace"
onLoad="alert('Message from ' + window.name + ': Hello, World.')"
onUnload="alert('Message from ' + window.name + ': I\'m closing')">
<B>Some numbers</B>
<UL><LI>one
<LI>two
<LI>three
<LI>four</UL>
</BODY>
</HTML>
See also the example for the
Frame object.
document,
Frame objects
Property. The window property is a synonym for the
current window or frame.
1. window.propertyName
2. window.methodName
propertyName is the defaultStatus,
status, length, or name property when the calling window
refers to a window object.
propertyName is the length or name
property when the calling window refers to a Frame object.
methodName is any method associated with the
window object.
Frame object,
window object
Navigator 2.0
No
The window property refers to the current window
or frame.
Although you can use the window property as a synonym
for the current frame, your code is more readable if you use the self
property. For example, window.name and self.name
both specify the name of the current frame, but self.name is
easier to understand.
Use the window property to disambiguate a property
of the window object from a form or form element of the same name.
You can also use the window property to make your code more
readable.
The window property is read-only. The value of the
window property is
<object nameAttribute>
where nameAttribute is the NAME attribute if
window refers to a frame, or an internal reference if window
refers to a window.
In the following example, window.status is
used to set the status property of the current window. This usage
disambiguates the status property of the current window from a form
called "status" within the current window.
<A HREF=""
onClick="this.href=pickRandomURL()"
onMouseOver="window.status='Pick a random URL' ; return true">
Go!</A>
self property
Method. Writes one or more HTML expressions to a document
in the specified window.
document.write(expression1 [,expression2], ...[,expressionN])
expression1 through expressionN are any JavaScript
expressions or the properties of existing objects.
document
-
-
Navigator 2.0
-
Navigator 3.0: users can print and save generated HTML using the commands
on the File menu
The write method displays any number of expressions
in a document window. You can specify any JavaScript expression with the
write method, including numerics, strings, or logicals.
The write method is the same as the writeln
method, except the write method does not append a newline character
to the end of the output.
Use the write method within any <SCRIPT> tag
or within an event handler. Event handlers execute after the original document
closes, so the write method will implicitly open a new document of
mimeType text/html if you do not explicitly issue a
document.open() method in the event handler.
You can use the write method to generate HTML and
JavaScript code. However, the HTML parser reads the generated code as it
is being written, so you might have to escape some characters. For example,
the following write method generates a comment and writes it to
window2:
window2=window.open('','window2')
beginComment="\<!--"
endComment="--\>"
window2.document.write(beginComment)
window2.document.write(" This some text inside a comment. ")
window2.document.write(endComment)
In Navigator 3.0, users can print and save generated HTML
using the commands on the File menu.
To view HTML code that was generated
with JavaScript write and
writeln methods, the user must specify
the view-source: protocol. If the user chooses Document Source or Frame Source
from the View menu, the content displayed is that of the wysiwyg: URL. The
following example shows a view-source: URL:
view-source:wysiwyg://0/file:/c|/temp/genhtml.html
For information on specifying the view-source: protocol
in the location object, see the
location object.
In the following example, the write method takes
several arguments, including strings, a numeric, and a variable:
var mystery = "world"
// Displays Hello world testing 123
msgWindow.document.write("Hello ", mystery, " testing ", 123)
In the following example, the write method takes
two arguments. The first argument is an assignment expression, and the second
argument is a string literal.
//Displays Hello world...
msgWindow.document.write(mystr = "Hello " + "world...")
In the following example, the write method takes
a single argument that is a conditional expression. If the value of the variable
age is less than 18, the method displays "Minor." If the value of
age is greater than or equal to 18, the method displays "Adult."
msgWindow.document.write(status = (age >= 18) ? "Adult" : "Minor")
close (document object),
open (document object),
writeln methods
Method. Writes one or more HTML expressions to a document
in the specified window and follows them with a newline character.
document.writeln(expression1 [,expression2], ...[,expressionN])
expression1 through expressionN are any JavaScript
expressions or the properties of existing objects.
document
-
-
Navigator 2.0
-
Navigator 3.0: users can print and save generated HTML using the commands
on the File menu
The writeln method displays any number of expressions
in a document window. You can specify any JavaScript expression, including
numerics, strings, or logicals.
The writeln method is the same as the write
method, except the writeln method appends a newline character to the
end of the output. HTML ignores the newline character, except within certain
tags such as <PRE>.
Use the writeln method within any <SCRIPT>
tag or within an event handler. Event handlers execute after the original
document closes, so the writeln method will implicitly open a new
document of mimeType text/html if you do not explicitly
issue a document.open() method in the event handler.
All the examples used for the write method are also
valid with the writeln method.
close (document object),
open (document object),
write methods