Configurating the Tree Navigator

 

Getting started.


Before you can use the Tree Navigator in your own web pages, you must first create a configuration file, telling the Tree which nodes to display, and which links each node corresponds to. The format of the configuration file is straight forward. Below is an example configuration file:

node = {
    name = "FooBar Homepage"
    url  = "www.foobar.com"
}
This file will cause the tree to display a single node which is a link to the foobar homepage. This sample illustrates the use of the node  statement, which is the most used in configuration files.

Node statements may be nested as in the example below:

node = {
    name = "FooBar Inc."
    url  = "http://www.foobar.com"
    node = {
        name = "FooBar products"
        url = "http://www.foobar.com"
    }
}


The second node in this tree will be a child node. That is, it will only be displayed if the user opens the parent node, by clicking on the icon to the left of it.

In the above example, both nodes had an URL associated with them. If no URL is specified, this particular node will not act as a link, but it will still be usefull as a parent node for other  links

Some configuration commands are only allowed outside of any node definition. These commands control the behavior of the tree in general. Other command may be present both outside and inside node definitions. These commands control the default behavior of nodes in the tree, but may be overridden by the same command within a node definition.

The complete set of commands which the Tree Navigator understands are documented later in this chapter.
 

Putting it on the web page

The Tree Navigator is a Java applet. Applets are placed in  web pages using the applet tag. Below is a sample of how this is done:
<html>
<body>
<applet
  ARCHIVE  = "navtree.jar"
  CODEBASE = "."
  CODE     = "aves.navtree.NavTree.class"
  NAME     = "NavTree"
  WIDTH    = 200
  HEIGHT   = 300
  HSPACE   = 0
  VSPACE   = 0
  ALIGN    = middle
>
<param name="config" value="myconfig.cfg">
</applet>
</body>
</html>
This example should be self explanatory to anyone familiar with html.  Note, that the name of the configuration file is passed to the applet using the <param> tag (The filename is the value of the parameter).

If you display the above html document in a browser it will simply display the Navigator Tree, with the nodes defined in the configuration file.  The easiest way to use the Tree Navigator is in combination with frames. Frames are set up whit html code similar to this:
 
<frameset>
   <frame src="left.html" name="left">
   <frame src="blank.html" name="main">
</framset>
 

This will split the screen in two frames. If left.html displays the tree, you can show the links in the other frame by setting the target to main (or whatever you called the other frame) in the configuration file. More on the target command later.

Applet parameters

An applet parameter is a command to the applet, whict is specified directly in the <applet> tag in the HTML file controling the applet. You have already seen an example of an applet paramter above, namely the "config" parameter which tells the Tree navigator where to find it's configuration file. In this section, each parameter understood by the Tree Navigator is explained.
 

The "config" parameter

This parameter tells the Tree navigator where to find it's configuration file. The value of the parameter is the URL of the configuration file. This may be a relative URL, following the normal conventions. The "config" parameter must be present in the applet tag for the Tree Navigator to function.
 
 
 

The "show" parameter

This parameter tells the applet which of the nodes should be shown when the applet is first displayed. The value of the parameter is the name of the node to display. This name may be overridden by using the tag command in the node definition. See the description of the tag command later in this chapter. This parameter will actually cause the nodes link to be displayed, so beware: If you are not using frames, the Tree Navigator will never be displayed, but will be replaced by the contents of the page to which the node links.

This command is useful only if you are displaying the tree in one frame, and the contents of the links in another page.

 

The "select" parameter

This parameter tells the Tree Navigator which node should be selected at startup. The value of the parameter is the  name of the node to select, or the tag of the node if this is given in the node definition. This parameter will not actually cause the node's link to be displayed. The "select" parameter is useful if you are not using frames, but are displaying the tree in every page.
 

Configuration commands

In the following section each configuration command supported by Tree Navigator is described. Most of these commands can only be used in the top level of the configuration file, that is: they must not be placed within any node definition. It will be clearly stated if a command can be used within node definitions.
 
 

node command

Allowed in top level: yes
Allowed in nodes: yes
Default value: n/a
Syntax:  node = { <node definition ...> }
Available since: 1.0

The node command defines a node to be displayed in the tree. Node commands may appear within other node commands, thus defining a tree. The <node definition ...> can be any combination of commands allowed within nodes.
 
 

name command

Allowed in top level: no
Allowed in nodes: yes
Default value: n/a
Syntax:  name = <name>
Available since: 1.0

The name  command specifies the name of the node as it is displayed in the tree. Every node in the tree should usually include either this command or the image command. 
  

image command

Allowed in top level: no
Allowed in nodes: yes
Default value: n/a
Syntax:  image = <url>
Available since: 1.1

This command can be used to tell the Tree Navigator to display an image instead of a text as the label of this node. You should use only one of the two commands (name or image) in each node definition. It is your responisibility to supply an image which will fit within the yscale of the tree. 

 

raiseimage command

Allowed in top level: no
Allowed in nodes: yes
Default value: the same as the normal image, ie. no raise effect
Syntax:  raiseimage = <url>
Available since: 1.2

This command can be used to tell the Tree Navigator to display a different image whenever the mouse passes over the node. This command only makes sense if the node normally displays an image, that is it has an image command instead of a name command.

 

selectimage command

Allowed in top level: no
Allowed in nodes: yes
Default value: the same as the normal image.
Syntax:  raiseimage = <url>
Available since: 1.2

This command can be used to tell the Tree Navigator to display a different image whenever this node is selected. This command only makes sense if the node normally displays an image, that is it has an image command instead of a name command.

  
 

url command

Allowed in top level: no
Allowed in nodes: yes
Default value: n/a
Syntax:  name = <name>
Available since: 1.0

The url command specifies which link to display when this node is selected by the user. If a node has no url command,  selecting it has no effect.
 
 
 

micro command

Allowed in top level: no
Allowed in nodes: yes
Default value: n/a
Syntax:  micro = <microhelp text>
Available since: 1.0

This command specifies which microhelp text should be displayed when the user moves tho mouse over a node in the tree. The microhelp is displayed in a small yellow box just below the  nodes name. If this command is not given within a node definition, no text will be displayed. 
  
 

microtime command

Allowed in top level: yes
Allowed in nodes: no
Default value: 900
Syntax:  microtime = <milliseconds>
Available since: 1.3

This command specifies how long the mouse must hover over a node before its microhelp is displayed. The value must be specified in milliseconds (1/1000 of a second). The default value is 900, which is 0.9 seconds. 

target command

Allowed in top level: yes
Allowed in nodes: yes
Default value: "_top"
Syntax:  target = <frame name>
Available since: 1.0

The target command specifies which target frame should be used  to display the link. The frame name can be the name of a user defined frame, or one of the following predefined strings:

"_top" : Display the link in the top level window, thus eliminating any frames the browser is currently displaying
"_parent": Display the link in the parent fram of the current frame.
"_this":  Display the  link in the current frame

If the target command is specified in the top level, it will be the default value of all nodes. If it is within a node definition, it will be valid only for that node, thus overriding the default.

tag command

Allowed in top level: yes
Allowed in nodes: no
Default value: <the name of the node>
Syntax:  tag = <tag name>
Available since: 1.1

This  command works together with the "show" and "select" applet parameters. Usually you can use the name of a node as the value  for these parameters, but if several node in the tree have the same name you can use this command to specify an alternate name for the node.

xsize command

Allowed in top level: yes
Allowed in nodes: no
Default value: 200
Syntax:  xsize = <size in pixels>
Available since: 1.0

This command specifies the horizontal size of the tree in pixels
 
 

ysize command

Allowed in top level: yes
Allowed in nodes: no
Default value: 400
Syntax:  ysize = <size in pixels>
Available since: 1.0

This command specifies the vertical size of the tree in pixels
 
 

xscale command

Allowed in top level: yes
Allowed in nodes: no
Default value: 23
Syntax:  xscale = <pixels>
Available since: 1.0

This command specifies the horizontal indent for child nodes in pixels
 
 

yscale command

Allowed in top level: yes
Allowed in nodes: no
Default value: 23
Syntax:  yscale = <pixels>
Available since: 1.0

This command specifies the vertical spacing between nodes in the tree.
 
 

background command

Allowed in top level: yes
Allowed in nodes: no
Default value: 255,255,255
Syntax:  background = <red>,<green>,<blue>
Available since: 1.0

This command specifies the background color of the tree in a comma seperated list with the red, green and blue component of the color. The components must be in the range 0-255. The default background color is white.
 
 

text command

Allowed in top level: yes
Allowed in nodes: no
Default value: 0,0,0
Syntax:  text = <red>,<green>,<blue>
Available since: 1.0

This command specifies the text color of the tree in a comma seperated list with the red, green and blue component of the color. The components must be in the range 0-255. The default text color is black
 
 
 
 

underline command

Allowed in top level: yes
Allowed in nodes: yes
Default value: false
Syntax:  underline = true | false
Available since: 1.0 (in nodes since 1.3)

This command specifies whether the text of the node should be undelined. An underlined link is more likely to be interpreted as a link by the user. If present in the top level of the definition file, it determines whether all nodes should be underlined. If present within a node definition, it determines whether that particular node should be underlined, thus overriding the default. The line is drawn whith the same color as the text (as specified by the "text" command)

 

highlight command

Allowed in top level: yes
Allowed in nodes: no
Default value: 0,0,120
Syntax:  highlight=<red>,<green>,<blue>
Available since: 1.0

This command specifies the color used to highlight the selected link. If you don't want the latest selected node highlighted, simply specify the background color as the highlight color. The default highlight color is dark blue.
 
 
 

raise command

Allowed in top level: yes
Allowed in nodes: no
Default value: n/a
Syntax:  raise = <red>,<green>,<blue>
Available since: 1.1

This command specifies the color to use when raising nodes. To raise a node means, that the node will change appearance whenever the mouse passes over the node. The name of the node will appear to rise up from the background, and the color surrounding the name will change. The tree used to browse this manual has the raise command set to a light gray color.

If this command is not present in the configuration file, the raise effect will be disabled.
 
 
 
 

scroll command

Allowed in top level: yes
Allowed in nodes: no
Default value: false
Syntax: scroll = true | false
Available since: 1.1

This command tells the Tree Navigator wheter to display scrollbars for the tree, if it grows larger than the specified size. In our opinion,  it is better to give the applet sufficient space in its frame, and let the browser generate the scrollbars, but that is a matter of taste.
 
 
 

showlines command

Allowed in top level: yes
Allowed in nodes: no
Default value: false
Syntax:  showlines = true | false
Available since: 1.0

This command specifies whether  the icons in the tree should be connected by lines. This behavior is familiar from Windows Explorer.  Whether connecting lines should be shown is largely a matter of taste.
 
 
 

openimage command

Allowed in top level: yes
Allowed in nodes: yes
Default value: build-in
Syntax:  openimage = <url to a gif or jpeg image>
Available since: 1.0

This command specifies the url to display for open nodes. The image will be displayed to the left of the node, whenever the nodes children are visible. If the command is specified in the top level, it will be the default value for all nodes. If it is within a node definition, it will be valid only for that node, thus overriding the default.
 
 
 

closedimage command

Allowed in top level: yes
Allowed in nodes: yes
Default value: build-in
Syntax:  closedimage = <url to a gif or jpeg image>
Available since: 1.0

This command specifies the url to display for closed nodes. The image will be displayed to the left of the node, whenever the nodes children are invisible.  This is not the same image, which is displayed when the node has no children. In this case, the leaf imafe is shown. See below. If the command is specified in the top level, it will be the default value for all nodes. If it is within a node definition, it will be valid only for that node, thus overriding the default.
 
 

leafimage command

Allowed in top level: yes
Allowed in nodes: yes
Default value: build-in
Syntax:  leafimage = <url to a gif or jpeg image>
Available since: 1.0

This command specifies the url to display for nodes which has no children. The image will be displayed to the left of the node. If the command is specified in the top level, it will be the default value for all nodes. If it is within a node definition, it will be valid only for that node, thus overriding the default. 

 

autoclose command

Allowed in top level: yes
Allowed in nodes: no
Default value: false
Syntax:  autoclose = true | false
Available since: 1.3

This command can be used to force all other nodes to be closed whenever the user opens a new node. If the space on the screen is limited, this can be usefull to prevent the tree to grow too large. If this is set to true, all nodes, (except the ancestors of the newly opened node,) are closed.

 

fontname command

Allowed in top level: yes
Allowed in nodes: no
Default value: SansSerif
Syntax:  fontname = <Font name>
Available since: 1.3

This command specifies the font used to display the labels of the nodes. The following fonts are garanteed to be available in all browsers: "SansSerif", "Serif", and "Monospaced".

 

fontstyle command

Allowed in top level: yes
Allowed in nodes: no
Default value: plain
Syntax:  fontstyle = plain | bold | italic
Available since: 1.3

This command specifies the font style used to display the labels of the nodes. The following styles are available: plain, bold, and italic.

 

fontsize command

Allowed in top level: yes
Allowed in nodes: no
Default value: 12
Syntax:  fontstyle = <point size of font>
Available since: 1.3

This command specifies the point size of the font used to display the labels of the nodes.

 

backgroundimage command

Allowed in top level: yes
Allowed in nodes: no
Default value: n/a
Syntax:  backgroundimage = <URL of image>
Available since: 1.3

This command specifies an image to display in the background of the tree. The nodes are superimposed on to of this image. Beware: using a large image considerably slows down the Tree Navigator.

 

scalebackground command

Allowed in top level: yes
Allowed in nodes: no
Default value: false
Syntax:  scalebackground = true | false
Available since: 1.3

This command determines whether the background image (if any) should be streched to fill the entire client area of the tree, or if it should be left in it's original size.

 

revealurl command

Allowed in top level: yes
Allowed in nodes: yes
Default value: false
Syntax:  revealurl = true | false
Available since: 1.3

This command determines whether the URL of a node should be displayed in the browsers status bar when the mouse hovers over a node. This is default browser behavior, but off by default in Aves Tree Navigator. If the command is specified in the top level, it will be the default value for all nodes. If it is within a node definition, it will be valid only for that node, thus overriding the default.