Version 1.0
Copyright (c) 2000 - 2005
Jean-Hugues Rety and Robert Kendall
These functions create links, text, graphics, or other elements that are displayed on a page when it is loaded by the browser.
Displays text or any elements (such as graphics) that can be defined by HTML code. Alternative elements can be displayed conditionally.
Syntax
[popupText = string]
[statusText = string]
[popupTextColor = color]
[popupBgColor = color]
[popupAtt = values]
[annotatedTextColor = color]
[prefix = prefixValue]
[suffix = suffixValue]
display(text[, condition][, elseText])
Parameters
text
The text to be displayed. It can include or consist entirely of HTML code
defining page elements such as tables or graphics.
Condition
A JavaScript expression that evaluates to either true or false.
elseText
Alternative text to be displayed.
Attributes
If the popupText or statusText attribute is defined,
the displayed text will become annotated text. It will cxhange to the color
specified by annotatedTextColor and when the mouse pointer is moved
over it, a message will appear in either a pop-up box or the status bar. Other
attributes can create prefixes or suffixes (visual elements that precede or
follow a displayed item). These attributes are common to both the link() and
display() functions and are documented in Function
Attributes, which also explains how to create default attributes. The following
attribute is unique to the display() function:
annotatedTextColor
Specifies an HTML color value that determines the color of the displayed
text (annotated text) if popupText or statusText is
defined. The value may be the name of a color enclosed in quotation marks ("red",
"green", etc.) or a hexadecimal value. This attribute does not affect
the color of the pop-up text.
Description
If condition is present, text will be displayed only if condition is true. If elseText is present, it will be displayed if condition is false.
See the description of Attributes above for ways of defining text as annotated text with mouse-activated pop-up annotations.
Example
display("from Node 1", (hist(-1) == "node1.htm"), "from
somewhere else")
If the last node visited was node1.htm, the function will display "from Node 1"; otherwise it will display "from somewhere else."
Creates a static or conditional link with optional text annotations and variable display attributes.
Syntax
[popupText = popupTextString]
[statusText = statusTextString]
[popupTextColor = color]
[popupBgColor = color]
[popupAtt = popupAttValues]
[linkColor = linkColorValue]
[prefix = prefixValue]
[suffix = suffixValue]
link(destination, text[, condition][, elseDestination][,
elseText])
Parameters
destination
The name of an HTML file (including extension) to serve as the primary link
destination.
text
The text to be linked from.
condition
A JavaScript expression that evaluates to either true or false.
elseDestination
The name of an HTML file (including extension) to serve as an alternative
link destination.
elseText
Alternative text to be linked from.
Attributes
This function can optionally be preceded by several attribute definitions that will create link annotations or change the appearance of the link. (These attribute definitions will have no effect on links not created with the link() function.) The attributes for creating link annotations and prefixes or suffixes (visual elements that precede or follow a link) are common to both the link() and the display() function. They are documented in Function Attributes, which also explains how to create default attributes. The following attribute is unique to the link() function:
linkColor
Specifies an HTML color value that determines the color of the linked text.
The value may be the name of a color enclosed in quotation marks ("red",
"green", etc.) or a hexadecimal value.
Description
If no optional parameters are present, this function creates a link on text to the node destination. If condition is present, destination and text will be used to create the link only if condition is true.
If condition is false, the function will operate as follows:
If "null" (entered without quotation marks) is used as the value for destination, text will be displayed as unlinked text. If "null" is used as the value for elseDestination, elseText will be displayed as unlinked text.
See the description of Attributes above for ways of adding annotations to the link or changing its appearance.
Example
popupText = "Good Choice!"
statusText = "Click here for enlightenment"
linkColor = "red"
prefix = "[ "
suffix = " ]"
link("node1.htm", "Go to Node 1", notVisited("node1.htm"),
"node2.htm", "Go to Node 2")
If node1.htm has not been visited, the function will create a link to node1.htm on the text "Go to Node 1." Otherwise it will create a link to node2.htm on the text "Go to Node 2." When the mouse pointer is moved over the link, "Good Choice!" appears as pop-up text and "Click here for enlightenment" is displayed in the status bar. The color of the link is red and it is surrounded by square brackets.
Creates a selectable area within an image map. The area can be created conditionally.
Syntax
[popupText = popupTextString]
[statusText = statusTextString]
[popupTextColor = color]
[popupBgColor = color]
[popupAtt = popupAttValues]
area(destination, areaDefinition[, condition][, elseDestination][,
elseAreaDefinition])
Parameters
destination
The name of an HTML file (including extension) to serve as the primary link
destination.
areaDefinition
The HTML code that defines an area within an <area> tag. This must
include the shape and coords attributes but not the
href attribute.
condition
A JavaScript expression that evaluates to either true or false.
elseDestination
The name of an HTML file (including extension) to serve as an alternative
link destination.
elseText
The HTML code that defines an alternative area within an <area> tag.
This must include the shape and coords attributes
but not the href attribute.
Attributes
This function can optionally be preceded by several attribute definitions that will create link annotations. (These attribute definitions will have no effect on imagemap areas not created with the area() function.) The attributes for creating link annotations are documented in Function Attributes, which also explains how to create default attributes.
Description
If no optional parameters are present, this function creates an imagemap area using the shape and coordinates defined in areaDefinition. The link will be to the node destination. If condition is present, destination and areaDefinition will be used to create the area only if condition is true.
If condition is false, the function will operate as follows:
See the description of Attributes above for ways of adding annotations to the imagemap area.
Example
popupText = "Good Choice!"
statusText = "Click here for enlightenment"
area("node1.htm", 'shape="poly" coords="19,21,41,6"',
notVisited("node1.htm"), "node2.htm")
If node1.htm has not been visited, the function will create an imagemap area with a link to node1.htm using the specified "shape" and "coords" values. Otherwise it will create a link to node2.htm using the same "shape" and "coords" values. When the mouse pointer is moved over the link, "Good Choice!" appears as pop-up text and "Click here for enlightenment" is displayed in the status bar. (Pop-up text behaves somewhat erratically with the area() function. It appears outside of the image instead of over the selected area.)
Single quote marks instead of double quote marks must be placed around the values that constitute the areaDefinition and elseAreaDefinition parameters. This is because these parameters contain double quote marks within them.
The area() function must be placed within the <map></map>
tags. It takes the place of an <area> tag. For example:
<IMG SRC="picture.jpg" WIDTH=92 HEIGHT=80 USEMAP="#Map"
BORDER="0">'
<map name="Map">
<script language="javascript">
area("node1.htm", 'shape="poly" coords="19,21,41,6"',
notVisited("node1.htm"), "node2.htm")
</script>
</map>
Both the display() and link() functions can optionally be preceded by several attribute definitions. These attributes can create text annotations for links or displayed items. They can also insert visual elements before or after displayed items. Each attribute must be defined for each individual occurrence of the display() or link() function. Default values for all these attributes can be defined in the configuration file (config.js). (See "Configuration Options" in the User's Guide.) If you wish an attribute definition to affect all the links in the hypertext created with the display() function or all the elements created with the link() function, specify it as a default in the configuration file. These attribute definitions will have no effect on links not created with the link() function.
Attributes for Annotations
popupText
Specifies a text string to serve as pop-up text. The text will be displayed
in a box to the right of the link or annotated text when the mouse pointer is
moved over it. By default, the text is black against a pale yellow background.
(These colors can be changed by means of the attribute definitions below.) The
pop-up text feature relies on DHTML and therefore will only work in version
4 or later browsers. [Note: A bug in the current version
prevents pop-up text from working properly in Netscape Navigator if the relevant
link or annotated text appears in text that is centered or in a table.]
statusText
Specifies a text string to serve as status text. The text will be displayed
in the browser's status bar (at the bottom of the window) when the mouse pointer
is moved over the link annotated text.
popupTextColor
Specifies an HTML color value that determines the color of the pop-up text.
The value may be the name of a color enclosed in quotation marks ("red",
"green", etc.) or a hexadecimal value.
popupBgColor
Specifies an HTML color value that determines the color of the background for
the pop-up text. The value may be the name of a color enclosed in quotation
marks ("red", "green", etc.) or a hexadecimal value.
popupAtt
Specifies attributes that determine the appearance of the pop-up text. This
text is formatted by means of an HTML table, so popupAtt will accept
any string of attributes allowed by the HTML <TABLE> tag. The attributes
are entered in the following format:
popupAtt = 'attribute1="value1" [attribute2="value2"]'
This example sets a specific width for the pop-up box:
popupAtt = 'width="100"'
Attributes for Prefixes and Suffixes
prefix
Specifies text or HTML code to precede the link or annotated text. This
can be used to create a bullet or one of a set of enclosing brackets or to insert
spaces between adjacent links.
suffix
Specifies text or HTML code to follow the link or annotated text. This can be
used to create one of a set of enclosing brackets or to insert spaces between
adjacent links.
All of the selection functions (except for hist()) select one or more items from a set of items, such as text strings or node filenames. These functions can be used to select a value for destination in a link() function or to create randomly or conditionally displayed text using the display() function. The functions select from a series of items specified as parameters. Any number of items can be entered as parameters separated by commas. Alternatively, the items can be stored in an array in either config.js or the node that calls the function. If a parameter is the name of an array, the function will operate on all the items contained in that array. (See "Item Arrays" under "Configuration Options" in the User's Guide.)
Most of these functions select and return a single item, but nRandom(), filter(), and conditionalFilter() return an array containing multiple items. An additional selection function can then be applied to the results of these functions to select a single item from the new set.
These functions all select a single node filename, and the selection depends upon the positions of nodes in the history.
Selects the node occupying a specified position in the history record.
Syntax
hist(rank)
Parameters
rank
A positive or negative integer.
Description
Positive numbers represent successive positions in the history record beginning with the first node in the history record (that is, the first node that was read). The node currently displayed by the browser is represented by 0. Negative numbers represent positions starting from the end of the history record and continuing toward the beginning. Thus -1 represents the last node read. The function returns the filename of the selected node.
Examples
hist(1) represents the first node read.
hist(0) represents the node currently displayed by the browser.
hist(-1) represents the last node read.
Evaluates a set of nodes and returns the node that was visited first.
Syntax
earliest(filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function returns the name of the node that occupies the earliest position in the history record. If none of the specified nodes have been visited, the function returns null.
Example
earliest("node1.htm", "node2.htm", "node3.htm")
== "node2.htm"
This expression is true if node2.htm was first visited before node1.htm and node3.htm.
Evaluates a set of nodes and returns the node that was visited last.
Syntax
latest(filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function returns the filename that occupies the latest position in the history record. If none of the the specified nodes have been visited, the function returns null.
Example
latest("node1.htm", "node2.htm", "node3.htm")
== "node2.htm"
This expression is true if node2.htm was last visited after node1.htm and node3.htm.
Evaluates a set of nodes and returns the node that is the least familiar to the reader. This is usually the node that has not been visited for the longest period of time.
Syntax
leastFamiliar(filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function is used to select the node that is least familiar to the reader. The function first looks for unvisited nodes, evaluating the node filenames in sequence and returning the first unvisited node it finds. If no unvisited nodes are available, it selects the node that has not been visited for the longest period of time.
Evaluates a set of nodes and returns the node that has not been visited for the longest period of time.
Syntax
oldest(elseFilename, filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
elseFilename
The name of an HTML file (including extension).
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function selects the node that has not been visited for the longest period of time. If none of the nodes have been visited, the funtion returns elseFilename.
These functions select randomly from a set of filenames, text strings, or other items.
Randomly returns one of a set of items.
Syntax
random(item1 | arrayName1[, item2 | arrayName2]...[,
itemN | arrayNameN])
Parameters
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames or other items.
Description
This function randomly selects one item from a set of items. Items can be filenames, text strings, numbers, or any other JavaScript objects. This function can be used to randomly select a value for destination in a link() function or to create randomly displayed text using the display() function.
Returns an array of a specified number of items randomly selected from a set of items.
Syntax
nRandom(n, item1 | arrayName1[, item2 | arrayName2]...[,
itemN | arrayNameN])
Parameters
n
An integer specifying the number of items to select.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames or other items.
Description
This function randomly selects a specified number of items from a set of items. Items can be filenames, text strings, numbers, or any other JavaScript objects.
These functions select one or more items from a set of items, using a filterFunction to exclude nodes from the selection process if they don't meet a specified condition. For example, the first unvisited node could be selected.
For excluding nodes from the selection process, you can use as the filterFunction any predefined function that accepts a single node as its parameter and returns a Boolean value (true or false). These are the functions that can be used:
You can also create a custom function that accepts an item as a parameter and use it as filterFunction. This custom function can be defined in the config.js file. The following example defines a filter function that will select a node only if it has been visited less than three times.
myFunction = new function(node, "nbVisits(node) < 3")
General boolean expressions that don't accept parameters can be included in the custom function. For example, the following example defines a filter function that will select a node only if it has been visited less than three times or more than 50 nodes have been visited altogether.
myFunction = new function(node, "nbVisits(node) < 3 || nbVisited() >
50")
If one of the above lines of code is included in config.js, myFunction can then be used as filterFunction in the functions described below. Custom functions can be particularly useful for selecting other types of text strings besides filenames.
Evaluates a set of items and returns an array containing only the items that meet a specified condition.
Syntax
filter(filterFunction, item1 | arrayName1[, item2 | arrayName2]...[,
itemN | arrayNameN])
Parameters
filterFunction
A JavaScript function that defines the selection criteria. This function
must evaluate to either true or false and should accept an item
as a parameter. Do not enclose this parameter in quotation marks.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of filenames or other items.
Description
This function returns an array containing all of the items that meet the condition specified in filterFunction. If none of the specified items satisfy filterFunction, the function returns an empty array.
Other functions can be used on the results of filter() to select a single item from the array.
Evaluates a set of nodes and returns the first node that meets the condition specified by the filter.
Syntax
filteredFirst(filterFunction, elseItem, item1 | arrayName1[,
item2 | arrayName2]...[, itemN | arrayNameN])
Parameters
filterFunction
A JavaScript function that defines the selection filter. This function must
evaluate to either true or false and should accept an item as
a parameter. Do not enclose this parameter in quotation marks.
elseItem
The item that is selected if no other item meets the selection criteria.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function evaluates the node filenames in sequence and returns the first node it finds that satisfies the condition specified in filterFunction. If no nodes satisfy filterFunction, then the function returns elseItem.
Evaluates a set of nodes and returns a randomly selected node that meets the condition specified by the filter.
Syntax
filteredRandom(filterFunction, elseItem, item1 | arrayName1[,
item2 | arrayName2]...[, itemN | arrayNameN])
Parameters
filterFunction
A JavaScript function that defines the selection filter. This function must
evaluate to either true or false and should accept an item as
a parameter. Do not enclose this parameter in quotation marks.
elseItem
The item that is selected if no other item meets the selection criteria.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function returns a randomly selected node that satisfies the condition specified in filterFunction. If no nodes satisfy filterFunction, then the function returns elseItem.
Evaluates a set of nodes and returns the node that is the least familiar to the reader. This is usually the node that has not been visited for the longest period of time. It excludes any nodes that do not meet the condition specified by the filter.
Syntax
filteredOldest(filterFunction, elseItem, item1 | arrayName1[,
item2 | arrayName2]...[, itemN | arrayNameN])
Parameters
filterFunction
A JavaScript function that defines the selection filter. This function must
evaluate to either true or false and should accept an item as
a parameter. Do not enclose this parameter in quotation marks.
elseItem
The item that is selected if no other item meets the selection criteria.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
This function is used to select the node that is least familiar to the reader. The function first looks for unvisited nodes, evaluating the node filenames in sequence and returning the first unvisited node it finds. If no unvisited nodes are available, it selects the node that has not been visited for the longest period of time. Any nodes that do not meet the condition specified by filterFunction are excluded from the selection process. If no nodes satisfy filterFunction, then the function returns elseItem.
These functions select an item by evaluating a series of conditional expressions. Each conditional expression is paired with an item. When a true condition is found, the item accompanying the condition is selected.
Returns the item paired with the first condition that evaluates to true.
Syntax
conditionalFirst(elseItem, item1, condition1[, item2, condition2]...[,itemN,
conditionN])
Parameters
elseItem
The item to return if none of the conditions are true.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
condition1...conditionN
JavaScript expressions that evaluate to either true or false.
Description
This function evaluates the specified conditions in sequential order. When a true condition is found, the function returns the item preceding that condition. If no condition is true, the function returns elseItem. Items can be filenames, text strings, numbers, or any other JavaScript objects.
Returns the item paired with a randomly selected condition that evaluates to true.
Syntax
conditionalRandom(elseItem, item1, condition1[, item2, condition2]...[,itemN,
conditionN])
Parameters
elseItem
The item to return if none of the conditions are true.
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
condition1...conditionN
JavaScript expressions that evaluate to either true or false.
Description
This function evaluates the specified conditions in random order. When a true condition is found, the function returns the item preceding that condition. If no condition is true, the function returns elseItem. Items can be filenames, text strings, numbers, or any other JavaScript objects.
Evaluates a set of item/condition pairs and returns an array containing only the items that meet the condition with which they are paired.
Syntax
conditionalFilter(item1, condition1[, item2, condition2]...[,itemN,
conditionN])
Parameters
item1...itemN
Filenames, text strings, numbers, or any other JavaScript objects.
condition1...conditionN
JavaScript expressions that evaluate to either true or false.
Description
This function evaluates all the specified conditions. Whenever a true condition is found, the function selects the item preceding that condition in the parameter list. All the selected items are returned as an array. Items can be filenames, text strings, numbers, or any other JavaScript objects.
These functions extract information from the history record to evaluate aspects of the reader's knowledge of the hypertext. They can determine which nodes have been visited, how many times they were visited, and so on. All these functions take node filenames as parameters and perform evaluations on those nodes.
These functions accept a single node filename as a parameter and perform an evaluation upon that node.
Determines how long ago a specified node was last visited.
Syntax
age(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns an integer indicating how long ago the specified node was last visited. If the node was the last node visited, the function will return 1. If it was the second-to-last node visited, the function will return 2, and so on. If the specified node is the currently displayed node, the function will return 0. A value of -1 indicates that the node has not been visited.
Determines where a specified node appears in the history.
Syntax
histRank(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns a JavaScript array of numbers indicating the positions occupied by the specified node in the history record. The first node in the history is 1.
Example
var positionsArray = histRank("node1.htm")
If node1.htm appears in the history at positions 2, 34, and 40, than the following three expressions will be true:
positionsArray[0] == 2
positionsArray[1] == 34
positionsArray[2] == 40
Determines whether a node has been visited.
Syntax
visited(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns true if the specified node has been visited.
Determines whether a node has not yet been visited.
Syntax
notVisited(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns true if the specified node has not been visited.
Determines how many times a specified node or set of nodes has been visited.
Syntax
nbVisits([filename1 | arrayName1]...[, filenameN |
arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns the number of times the node(s) specified by filename(s) or arrayName(s) have been visited. If more than one filename is specified, returns the sum of all visits to all specified nodes. If no parameters are specified, the evaluation is performed on the entire hypertext and the length of the entire history is returned.
This function can be used with JavaScript comparators such as these:
== equal to
!= not equal to
> greater than
<= greater than or equal than to
< less than
<= less than or equal to
Determines whether a specified node has been immediately preceded by another specified node during the reading.
Syntax
visitedFrom(filename[, antecedent1 | antecedentArray1]...[,
antecedentN | antecedentArrayN]
Parameters
filename
The name of an HTML file (including extension).
antecedent1...antecedentN
The name of an HTML file (including extension).
antecedentArray1...antecedentArrayN
The name of an array containing HTML filenames.
Description
If filename has been immediately preceded during the reading by one of the nodes specified as antecedents, the function returns true. If filename has not been immediately preceded by one of the antecedents or if filename has not been visited, the function returns false. If antecedent is not specified, the currently displayed node is defined as antecedent.
Note that visitedFrom() evaluates all appearances of filename
in the reading history. If you wish to determine only whether node1.htm
was the last node displayed, use this expression instead of visitedFrom():
hist(-1) == "node1.htm"
Example
visitedFrom("node2.htm", "node1.htm")
This returns true if the following sequence is found anywhere in the history:
node1.htm, node2.htm
Determines whether a node has been immediately preceded in the reading by a node other than those specified.
Syntax
visitedNotFrom(filename, antecedent1 | antecedentArray1[, antecedent2
| antecedentArray2]...[, antecedentN | antecedentArrayN]
Parameters
filename
The name of an HTML file (including extension).
antecedent1...antecedentN
The name of an HTML file (including extension).
antecedentArray1...antecedentArrayN
The name of an array containing HTML filenames.
Description
If filename has been visited immediately after a node not specified
as one of the antecedents, the function returns true. If filename
has always been preceded by one of the antecedents or if filename
has not been visited, the function returns false. Note that visitedNotFrom()
evaluates all appearances of filename in the reading history.
Example
visitedNotFrom("node1.htm", "node2.htm", "node3.htm")
This expression will return true if the history consists of the following sequence of nodes:
node4.htm, node1.htm, node2.htm
It will return false if the history consists of this sequence:
node2.htm, node1.htm, node3.htm
Determines whether a node was previously visited and immediately preceded by one of the specified nodes.
Syntax
visitedOnlyFrom(filename, antecedent1 | antecedentArray1[,
antecedent2 | antecedentArray2]...[, antecedentN | antecedentArrayN]
Parameters
filename
The name of an HTML file (including extension).
antecedent1...antecedentN
The name of an HTML file (including extension).
antecedentArray1...antecedentArrayN
The name of an array containing HTML filenames.
Description
If filename was visited and on each visit was immediately preceded by one of the nodes specified as antecedents, the function returns true. If filename was preceded by a node not among antecedents or if filename has not been visited, the function returns false.
These functions perform evaluations upon groups of nodes or upon all the nodes in the hypertext. The nodes to evaluate can be specified either by entering their filenames separated by commas or by entering the name of array that contains the filenames.
Determines whether one or more of the specified nodes has been visited.
Syntax
someVisited(filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns true if one or more of the specified nodes has been visited. Otherwise returns false.
Example
someVisited("node1.htm", "node2.htm", "node3.htm")
This returns true if either node1.htm, node2.htm, or node3.htm has been visited.
Determines whether all of the specified nodes have been visited.
Syntax
allVisited(filename1 | arrayName1[, filename2 | arrayName2]...[,
filenameN | arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns true if all specified nodes have been visited. Otherwise returns false.
Example
allVisited("node1.htm", "node2.htm", "node3.htm")
This returns true if node1.htm, node2.htm, and node3.htm have all been visited.
Determines how many different nodes have been visited in either the entire hypertext or a specified set of nodes.
Syntax
nbVisited([filename1 | arrayName1]...[, filenameN |
arrayNameN])
Parameters
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns the number of different nodes that have been visited among the specified filenames or arrayNames. If no parameters are specified, the evaluation is performed on the entire hypertext. Any nodes visited multiple times are counted only once.
This function can be used with JavaScript comparators such as these:
== equal to
!= not equal to
> greater than
<= greater than or equal than to
< less than
<= less than or equal to
These functions return information about links in the pages currently displayed by the browser. They can be used to determine such things as whether a specific node is linked to on the current page or whether all the links on the page lead to previously visited nodes.
Because of the way JavaScript is executed, these functions can only evaluate links that appear on the page above the location of the link status function statement.
These functions can be used to determine whether a specified node is linked to on the current page. Any of them can be used as a filterFunction value for filtered selection functions.
Determines whether the specified node is linked to in the current node.
Syntax
linked(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns true if the specified node is linked to in the node containing the function. Otherwise returns false. The function can take into account only links that appear on the page above the location of the linked() statement.
Determines whether the specified node is not linked to in the current node.
Syntax
notLinked(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns true if the specified node is not linked to in the node containing the function. Otherwise returns false. The function can take into account only links that appear on the page above the location of the linked() statement.
Determines whether the specified node has not been visited and is not linked to in the current node.
Syntax
notVisitedNotLinked(filename)
Parameters
filename
The name of an HTML file (including extension).
Description
Returns true if the specified node has not been visited and is not linked
to in the node containing the function. Otherwise returns false. The function
can take into account only links that appear on the page above the location
of the linked() statement. Equivalent to (notVisited(filename)
&& notLinked(filename)).
These functions can be used to get information about all the links in a currently displayed page or to determine whether some or all of a set of nodes are linked to in a page currently displayed by the browser.
These functions can evaluate a page displayed in any frame. If framename is not specified, the function checks only the page in which the function statement is located. If framename is specified, the function checks only the page displayed in the specified frame.
If the page being evaluated is the one containing the function statement, the evaluation can take into account only links that appear on the page above the location of the function statement. Hidden or inactive links are not evaluated.
Determines whether one or more of the specified nodes are linked to in a currently displayed page.
Syntax
someLinked([framename,] filename1 | arrayName1[,
filename2 | arrayName2]...[, filenameN | arrayNameN])
Parameters
framename
A JavaScript frame object.
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns true if one or more of the specified nodes is linked to in a page currently displayed by the browser. Otherwise returns false. If framename is specified, the function checks only the page displayed in the specified frame. Otherwise, it checks only the page in which the function statement is located.
Example
someLinked(parent.frameA, "node1.htm", "node2.htm")
This returns true if either node1.htm or node2.htm are
linked to in the node currently displayed in frameA.
Determines whether all of the specified nodes are linked to in a currently displayed page.
Syntax
allLinked([framename,] filename1 | arrayName1[, filename2
| arrayName2]...[, filenameN | arrayNameN])
Parameters
framename
A JavaScript frame object.
filename1...filenameN
The names of HTML files (including extensions).
arrayName1...arrayNameN
The names of predefined arrays of HTML filenames.
Description
Returns true if all of the specified nodes are linked to in a page currently displayed by the browser. Otherwise returns false. If framename is specified, the function checks only the page displayed in the specified frame. Otherwise, it checks only the page in which the function statement is located.
Example
allLinked(parent.frameA, "node1.htm", "node2.htm")
This returns true if node1.htm and node2.htm are
both linked to in the node currently displayed in frameA.
Determines how many links are in a currently displayed page.
Syntax
nbLinks([framename])
Parameters
framename
A JavaScript frame object.
Description
Returns the number of links in the node containing the function. If framename is specified, the function checks only the page displayed in the specified frame. Otherwise, it checks only the page in which the function statement is located.
This function can be used with JavaScript comparators such as these:
== equal to
!= not equal to
> greater than
<= greater than or equal than to
< less than
<= less than or equal to
Example
nbLinks(parent.frameA)
This returns the number of links contained in the node currently displayed
in frameA.
Determines how many links in a currently displayed page have not been followed.
Syntax
nbLinksNotFollowed([framename])
Parameters
framename
A JavaScript frame object.
Description
Returns the number of links that haven't been followed in a page currently displayed by the browser. If framename is specified, the function checks only the page displayed in the specified frame. Otherwise, it checks only the page in which the function statement is located.
This function can be used with JavaScript comparators such as these:
== equal to
!= not equal to
> greater than
<= greater than or equal than to
< less than
<= less than or equal to
Example
nbLinksNotFollowed(parent.frameA)
This returns the number of links not followed in the node currently displayed
in frameA.
Determines whether all the links in a currently displayed page have been followed.
Syntax
allLinksFollowed([framename])
Parameters
framename
The name of a frame.
Description
Returns true if all the links in a page currently displayed by the browser have been followed. Otherwise returns false. If framename is specified, the function checks only the page displayed in the specified frame. Otherwise, it checks only the page in which the function statement is located.
These functions extract information about the history record, display its contents, or perform operations directly upon it to alter its content by adding or removing nodes. Take care when using the functions that directly alter the history contents.
Adds a specified node to the history record.
Syntax
addHist([filename])
Parameters
filename
The name of an HTML file (including extension).
Description
Appends the name of the specified node to the end of the history record. If no node is specified, the currently displayed node is appended to the history record. This function should only be used in special circumstances, because the system automatically adds nodes to the history record as they are visited.
Deletes the history record.
Syntax
deleteHist()
Parameters
None.
Description
Deletes the cookies containing the history record. A new history cookie is automatically created and initialized the next time the library is loaded by a page.
Initializes the history record to contain only the specified node.
Syntax
initHist([filename])
Parameters
filename
The name of an HTML file (including extension).
Description
Deletes the cookies containing the history record and creates a new history record containing only the name of the specified node. If no node is specified, the currently displayed node is used.
Determines whether the history record is empty--that is, whether no nodes have been visited.
Syntax
histEmpty()
Parameters
None.
Description
Returns true if the history record is empty--that is, if no nodes have been visited. Otherwise returns false. The following two expressions are equivalent:
histEmpty() == true
nbVisited() == 0
Returns an array containing the filenames of all the nodes in the history.
Syntax
histArray()
Parameters
None.
Description
The array returned by this function contains the filenames of all the nodes that have been visited in the order in which they were visited.
Example
This statement:
document.write(histArray().join(", "))
will produce the following text, assuming that these nodes have been visited in this order:
"node1.htm, node2.htm, node1.htm"
Displays a list of the filenames of the nodes that have been visited.
Syntax
displayHist([n])
Parameters
n
A numeral indicating how many filenames to display.
Description
Displays the filenames of the nodes that have been visited in the order in which they were visited. If n is specified, the function lists only the last n nodes that were visited. If n is not specified, it displays all the nodes that have been visited. The filenames are displayed in a row separated by the ">" symbol.
Example
This statement:
displayHist(3)
will produce the following text, assuming that these nodes have been visited in this order:
node1.htm > node2.htm > node3.htm