Currently in: TreeView > Documentation

A tree for site navigation will open here if you enable JavaScript in your browser.

Using TreeView

TreeView is one of the easiest and fastest site navigation menus. This section offers
some tips on using a page containing a TreeView.

Typically, Web pages with a Treeview consist of two (or more) separate areas. These
areas are created using using tables (frame-less layouts) or frames (frame-based layouts).
The left area, typically, shows a tree of folder nodes and document nodes. This is the
navigation tree menu. The hierarchical structure can hold a very large number of links,
while still only showing a small number of them at a time. Clicking on the minus (-) or
plus (+) sign will expand or collapse the folder nodes immediately. Clicking on a
document node will load a new page on the right pane or on a new window.

Here are some tips for using a Web page containing a TreeView

On sites with frames, drag the vertical separator to control the space available
for the tree (and its nodes).

To access hidden links, click the plus sign (+) or the folder itself. This will open
the folder and expose subfolders and "documents" contained inside.

Folder nodes, themselves, may be associated with links. For such folder nodes, a
click will both expand its contents and load the associated page.

To collapse a folder node, click the minus (-) sign. This will let you look for
other links in other folders without having to scroll up or down.

Clicking on the topmost folder node will typically take you back to the entry page.

Installing TreeView

Download TreeView and extract the files from the ZIP onto
your computer.

Open index.html in your browser and try the demos.

Choose the demo that most closely matches your needs and edit the files for that demo.

See the readme.html file for a description of each file in the download.

When you are ready to test your edits, copy or upload the files to your Web server and
test.

Note: If you want to base your application on one of the demos in the free download
and you want to rename some of the files, you will need to take in account the file
dependencies when renaming files. For example, you may want to renamedemoFramesetRightFrame.html but then you will need to update bothdemoFramesetNodes.js and demoFrameset.html. The demoFrameset.html
file (the file that is most visible to visitors) can be renamed without any dependency
problems.

Structure of Web Page

There are many possibilities for including TreeView on your pages. Two obvious
possibilities are:

Place TreeView in a frame, and have that frame construct and show only the tree.

Place TreeView in a frame-less page with other content.

There are small differences between these two uses of TreeView. Those differences
involve how you include TreeView in the page and how you set the TreeView
configuration variables. However, regardless of the way you include TreeView in your
pages, TreeView uses the same structure. This common structure is now described.

In each file that contains a tree, the head block includes:

A style tag that specifies styles. You can use styles to change the
appearance of the tree. For more information, see the next section.

Of course, other statements unrelated to the tree may also be in the head
block.

In each file that contains a tree, the body block contains the statement
that actually renders the tree. This is the call to the initializeDocument
function. For frame-less pages that have other elements aside from the tree, the
relative position of the initializeDocument call within the body
block depends on the layout of your page.

Note that pages that construct trees from server-side code have a slightly different
structure, with the tree configuration statements being part of the HTML page and not
loaded from a separate JavaScript configuration file.

Configuration Variables

TreeView includes configuration variables that make it easy for you to enable or
disable certain functionality. The Treeview configuration variables appear in the
TreeView configuration file (which has a name like demo*Nodes.js).
The configuration variables appear above the actual definition of the nodes. If you
do not set any configuration variables, TreeView will use the default values for those
variables. The configuration variables are explained in the following table.

Variable Name

Description

Default

BUILDALL

Fast performance with large trees is obtained by deferring the construction
of nodes until the user expands the folder containing them. By default,
TreeView builds only the nodes needed to render the tree at first and then builds
nodes for other nodes when their folder is opened. Setting this variable to1 configures the TreeView to build all nodes when the page is loaded,
even those nodes that are not initially visible. You can assign any of the
following values to this variable:

0: Defers construction of hidden nodes

1: Constructs all nodes on page load

Currently, only one demo scenario sets this variable; the demo that shows
checkboxes and radio buttons has form elenents as nodes, and so the entire tree
must be built when the page is loaded to ensure that the entire form is built.

0

GLOBALTARGET

If the tree is created using the addChildren API, this variable
specifies the target for the links in the tree. You can assign any of the
following values to this variable:

'B': Sets target to a new window

'R': Sets target to the right frame

'S': Sets target to the current frame (replacing the tree)

'T': Sets target to the current browser window (replacing entire
frameset if present)

'R'

HIGHLIGHT

This variable enables or disables the highlighting of nodes when they are
selected. Highlighting reverses the foreground and background colors for the
currently selected node. But you can customize this behavior (see theHIGHLIGHT_COLOR and HIGHLIGHT_BG variables). Note that
highlighting works only for nodes that load pages. You can assign any of the
following values to this variable:

0: Do not highlight the selected node

1: Highlight the selected node

0

HIGHLIGHT_BG

This variable specifies the color of the background when highlighting is
used. For more information about highlighting, see the HIGHLIGHT
variable. You can assign any valid HTML color string to this variable. For
example, 'blue' or '#ccff99'.

'blue'

HIGHLIGHT_COLOR

This variable specifies the color of the text when highlighting is
used. For more information about highlighting, see the HIGHLIGHT
variable. You can assign any valid HTML color string to this variable. For
example, 'white' or '#FFFF80'.

'white'

ICONPATH

If you want to place the TreeView images in a separate directory, you
can use this variable to specify the location of those images. The value
of this variable should either be an empty string ('') or
a valid URL that points to a directory and is terminated with a
forward slash (/). An empty string indicates that the images
are in the same directory as the TreeView files. Examples of possible
values include: '/tv/images/index.html', 'http://www.x.com/y/', and
so on.

''

PRESERVESTATE

The user changes the state of the tree in two ways: by opening and
contracting folders, and by highlighting nodes (if HIGHLIGHT=1).
Unless that state information is stored, reloading the tree will revert it
to its original state. With this variable set to 1, Treeview
stores information in cookies to preserve the tree state across page
loads. You can assign the following values to this variable:

0: Do not store the state of the tree across page loads

1: Store the state of the tree in cookies, and use that state on next visit

Do not use PRESERVESTATE=1 together withSTARTALLOPEN=1. These settings contradict each another.

Two scenarios that are typically not suitable for preserving the
state are pages with a frameless layout (see USEFRAMES), and
database driven applications. If the structure of your tree can change
between reloads (when a new folder is added in a database-driven application,
for example) and you want to use PRESERVESTATE, you will need
to have a constant means of identification for the nodes. Otherwise,
the script may try to use the wrong id and show an error. See the section
on Giving External IDs to Nodes below for more information.

If your site uses more than one TreeView, you will need a way to
identify the different TreeViews for the PRESERVESTATE mechanism.
See the section on Giving IDs to Trees below.

0

STARTALLOPEN

This variable configures whether, upon loading the page, the tree should
appear with all folders open. You can assign the following values to this
variable:

0: Expand only the root node. Do not open other folders.

1: Expand all folders, showing every node in the tree.

Do not use STARTALLOPEN=1 together with PRESERVESTATE=1.
These settings contradict each another.

Note that expanding all folders may be convenient for small or medium
trees, but defeats the optimizations introduced for very large tree (that is,
trees with hundreds or thousands of nodes.)

0

USEFRAMES

This variable specifies whether the tree will appear in a frame or in a
regular frame-less page. If you are using a frame-less layout, make sure to
explicitly set this variable. Otherwise TreeView will not work as expected.
You can assign the following values to this variable:

0: Use TreeView in a frame-less layout

1: Use TreeView in a frame-based layout where the tree is in
its own frame

1

USEICONS

This variable configures whether TreeView displays icons in the tree.
Setting this variable to zero removes the icons. Note, however, that the+ and - controls always appear. Only the appearance of
the folder and node icons can be configured. You can assign the following
values to this variable:

0: Do not display the icons

1: Display the icons

1

USETEXTLINKS

The icon for a node is a link to the destination for that node. This
variable configures whether the text for a node is also a link to that
destination. You can assign the following values to this variable:

0: The icon is the only link to a destination

1: Both the icon and the text are links to the destination

0

WRAPTEXT

This variable configures whether the text in each node is allowed to
wrap around to more than one line. You can assign the following values to
this variable:

0: The text portion of a node will appear on one line only

1: The text portion of a node will wrap to always be visible

Note: If you are basing your design on one of the demos that
uses frames, do not forget to remove the nowrap setting from thestyle tag at the top of the left-frame HTML file.

Using Favorites Manager

To save time building the tree, you can use the Favorites Manager application (by
GubuSoft). Favorites Manager is essentially a link management tool. Favorites Manager
allows you to use dialogs to enter the names and URLs for links. You can use the
Favorites Manager dialogs to add, edit, delete, and move both folders and links.
When you are ready to move the links to TreeView, you can export the links from
Favorites Manager in a special format that TreeView can use. Detailed instructions on
using Favorites Manager to visually build your tree are on theTreeView Developer's Resources page.

Manually Building Tree

gFld Function

The gFld function allows you to create a folder for the tree. A call to this
function takes two arguments and returns a folder:

Argument

Description

Title

Specifies the text that appears in the folder name. This text can include simple
HTML tags, such as enclosing formatting tags (i, b,div, and so on). It can even include an img tag if you want
to place a small icon in the node name, such as a "new!" icon for example.

Link

Specifies an optional URL. The URL can be a simple file name likedemoFramesetRightFrame.html or a string with protocol, domain, path, and file
name like http://www.treeview.net/treemenu/demopics/beenthere_europe.gif.

You may not want clicking on a folder node to open a page. In this case, you probably
want the click on the folder node to be the same as a click on the '+' sign. That is,
you only want clicking on the folder name to expand the folder. To do this, give the
value javascript:parent.op() to the second argument of the gFld function.
This second argument is a call to an empty function, which is needed in order to support
older browsers. An example follows:

aux1 = insFld(foldersTree, gFld("Test A", "javascript:parent.op()"))

If folders with the javascript:parent.op() argument are not working properly
for you, check to make sure that this function is defined in the header section of the
HTML file that defines the frameset containing the TreeView.

gLnk Function

The gLnk function allows you to create a link. This function is used only
to create links to documents. How those links appear in the tree is determined by other
functions. A call to this function takes three arguments and returns a link:

Argument

Description

Target

Configures the target location for the link. Specify one of the following
values:

"R": Open the document in the right frame (a frame namedbasefrm)

"B": Open the document in a new window

"T": Open the document in the current browser window, replacing
the frameset if one exists

"S": Open the document in the current frame, replacing the tree

Note: This argument is case sensitive; make sure to use uppercase
letters.

Title

Specifies the text that appears in the link. This text can include simple
HTML tags, such as enclosing formatting tags (i, b,div, and so on). It can even include an img tag if you want
to place a small icon in the node name, such as a "new!" icon for example.

Link

Specifies the URL of the document. This can be an absolute URL or a
relative URL. Do not enter any other information in this string; adding a
target parameter or an event handler will not work.

For example, the following function call creates a link with the textMy File in the tree, and clicking on this node displays thehttp://www.mysite.com/MyFile.doc file in a new window:

gLnk("B", "My File", "http://www.mysite.com/MyFile.doc")

You can extend the Target argument to also specify the protocol for the link
by adding one of the following lowercase characters immediately after the
uppercase character that indicates the target location:

"h": for http:// protocols

"s": for https:// protocols

"f": for ftp:// protocols

"m": for mailto:// protocols

Note: This argument is case sensitive; make sure to use lowercase
letters.

This allows you to omit the protocol from the string in the Link
argument, which helps keep the size of the file as small as possible. Using
this extension, the previous example can be rewritten as:

insFld Function

The insFld function places a folder node within another folder node.
The insFld function takes two folder node arguments and places one of
the folder nodes within the other folder node. That is, this function places a
child folder node within a parent folder node. This function takes two
arguments:

Argument

Description

Parent Folder

Specifies the parent folder. That is, this argument specifies the folder
node in which you want to place the other folder node.

Child Folder

Specifies the child folder. That is, this argument specifies the folder
node that you want to place under the parent folder node.

For example, the following code places the gFld("Europe", "http...")
child folder node under the foldersTree parent folder node:

aux1 = insFld(foldersTree, gFld("Europe", "http..."))

insDoc Function

The insDoc function places a document node within a folder node. TheinsDoc function takes two arguments and places the document node argument
under the folder node argument. This function takes the following two arguments:

Argument

Description

Parent Folder

Specifies the parent folder. That is, this argument specifies the folder
node in which you want to place the document node.

Document Node

Specifies the document node. That is, this argument specifies the document
node that you want to place in the parent folder node.

For example, the following code places the gLnk("S", "Boston", "...")
document node under the aux2 parent folder:

insDoc(aux2, gLnk("S", "Boston", "..."))

Putting it all Together

The following steps tell you how to put together the calls needed to create a
TreeView:

Create the root folder. For example:

foldersTree = gFld("<i>Demo</i>", "demoFramesetRightFrame.html")

Place folders inside other folders by using the insFld function. For
example:

aux1 = insFld(foldersTree, gFld("Europe", "http..."))

Place documents inside folders by using the insDoc function. For
example:

insDoc(aux2, gLnk("S", "Boston", "..."))

Quote Characters

Use of the single quote (') and double quote (") characters
requires extreme care. You can run into trouble with TreeView when you use
quote characters in the following scenarios:

When the node text includes one of these characters

When the HREF link has the javascript:function... format and the
function takes string arguments where one of the arguments includes quote
characters.

You can use the String.fromCharCode() function to make sure that
quote characters are interpreted correctly. Also, you can "escape" the quote
characters, by putting a backslash character () immediately before the
quote character. The following code shows both of these approaches:

Alternative API

If your tree has more than a thousand nodes, you are probably using server-side
code to generate the TreeView. In that case, the JavaScript generated by the server
should use a different API from the one described in the previous sections. This
alternative API, used for the creation of document links, speeds up the time it
takes for the tree to be rendered after a page-load. Since this API is harder to
program, and since benefits are only noticeable for very large trees, theinsDoc and gLnk API is the recommended one for small trees that
are manually configured.

The folder.addChildren function allows you to declare and construct all
document nodes in a folder using a single statement. If the folder has subfolders,
those subfolders must be built first and then passed to the addChildren
function. Because of this order dependency, tree-configuration files that use theaddChildren API are very different from those that use the insFld
and insDoc API. Actually, they reverse the order of folder creation.

addChildren is a method of the folder object. The folder
object must have been created before the addChildren method is called.
The only argument that the addChildren method takes is a list of children.
Each element in this list can be a folder object or a sub-list of two strings: the
label to use for a document node, and the link to use with that node. An example
of the addChildren API follows:

fldChild = gFld("FChild", "linkfld1.html")

fldParent = gFld("F", "linkfld2.html")

fldParent.addChildren([fldChild, ["Doc", "link.html"]])

With this code, the user will see a folder F with two nodes inside:
the sub-folder FChild and the document Doc.

To specify a target for links that are created using addChildren, you
can use the GLOBALTARGET configuration variable. For more information
about GLOBALTARGET, see TreeView Configuration
Variables above.

The addChildren API hides the construction of the document objects.
However, you can still use those objects to change properties such as xID
and iconSrc. In order to get access to the document object, use the
children array member of the folder object. For example:

fldParent.children[0].xID = "foo"

The free TreeView download includes demo code for an ASP server-side
dynamically-generated TreeView that uses this API. See the files that are
named demoDynamic*.*.

Advanced Configuration

Changing Icons

TreeView comes with a set of default icons. However, if you want, you can create your
own icons for folders and nodes. When creating the images for the icons, you can use any
image file, provides the width is 16 pixels and the height is 22 pixels.

If you want to replace the folder icons, you will typically need two images: one image for
open folders, and the other image for closed folders. Of course, if you want, you can use
the same image for both. The iconSrc and iconSrcClosed attributes
can be used to override these icons.

If you look at the files in the free download, the demo for TreeView in a frame-based
layout shows how you can use alternative icons. Open the demoFramesetNodes.js
file in a text editor. The following code in that file overrides the folder icon:

In this code, ICONPATH is one of the TreeView environment variables. It
indicates the location of the TreeView images. If you are not setting this environment
variable in your application, it may be omitted from the above statements. ThediffFolder.gif file is the actual alternative folder icon (it is distributed
with TreeView).

Similarly, the following code in demoFramesetNodes.js overrides the node
icon for a document:

Configuring Styles

The styles for the tree are configured in the style tag (in the head
block of the file containing the tree).

If you are configuring styles for a tree appearing in a frame (where the frame contains
only the tree), you can apply styles to the a and td CSS selectors to
control the font, color, and so on.

If you are using a frameless layout and have other elements in the page (for example,
other anchor elements (a), you will want to specify styles that are applied only
to the tree. You can see how to do this in the files for the frame-less demos. In these
files, the style block is divided into two parts: the tree styles and the other
styles. To indicate the anchor tags for the links in the tree, we add a specialspan block with a class named TreeviewSpanArea. Using this span
block together with the contextual selectors rules of CSS, we can apply styles only to the
tree.

Specifying Extra HTML

You use the gFld and gLnk functions to specify the text for folder
and document nodes. You have some ability to specify HTML in the text that you pass to
these functions. You can use tags for bold, italics, and so on. You can even include
HTML for images. However, you are limited by the fact that this HTML you specify is
going to be part of an <a HREF="...">...</a> block.

This is a problem when you want to include check boxes or radio buttons in a tree.
To solve this problem, we have added a prependHTML member. This member allows
you to specify text to be added between the icon and the item's text.prependHTML applies to both to folder nodes and to document nodes. As with
other object members, prependHTML should be set right after the object is
created. For example:

There is one important rule to follow when using prependHTML. For compatibility
with older browsers, the tree is all built with tables, where each "row" (a folder or a
document) is a TR. For this reason the text used in prependHTML must
always start and end with the delimiters of a TD block.

It is also important to either use STARTALLOPEN or BUILDALL. All
the form elements contained in the tree must be created when the page is loaded for
the form to include them.

If you want to see an example of prependHTML, see the code for the TreeView
demo that shows checkboxes.

TreeView API

Nodes in the tree, folders or documents, are internally represented by JavaScript
objects, even before the tree starts to be rendered in HTML. These objects should not
be confused with the DOM objects they generate. One Treeview Folder object,
for example, will generate several DOM objects (images, text, etc.) once the tree is
rendered.

If you give external IDs to the nodes in the tree (see Working with
Node IDs), you will be able to obtain a node object by calling the function

myNode = findObj(id)

Once you have a JavaScript variable with a reference to a Treeview node, there are
several things you can do with it. You can, for example, highlight it by calling the
function highlightObjLink(myNode). Also, you can also find the parent of a
node (corresponding to the folder holding that node) by calling myNode.parentObj.

Working with Tree IDs

If you have more than one tree on your site, you will need to give unique
identifiers to each tree. This identifier will help the trees to keep their states
separately. Use the treeID attribute to assign an identifier to each tree.
For example, the following code assigns the t3 identifier to a tree:

Working with Node IDs

By default, nodes are identified by their order in the tree. Successive number
identifiers (IDs) are assigned to nodes in the tree in order. The first folder is
number 1, the first item inside that folder is number 2, and so on. ThePRESERVESTATE mechanism works by storing information associated with
these IDs in cookies.

If the structure of the tree changes (that is, nodes are added or deleted) during
a session, the IDs will also change. This means that the node IDs in cookies may no
longer be valid and the PRESERVESTATE mechanism may not work as expected. To ensure
this situation does not occur, you can instead hardcode the IDs. When you hardcode
static IDs, as opposed to using the default dynamic IDs, you avoid the possibility
of the IDs in cookies becoming out-of-synch. That is, the IDs will no longer be
dependent on the structure of the tree.

The xID attribute allows you to assign IDs to nodes. You can assign
a string or a number to the xID attribute. If you are using strings,
the strings cannot contain any of the following characters:

^ (if you need to be able to use this character, redefine the variable cookieCutter)

'

"

Here is an example of using the xID that is adapted from the code in thedemoLargeNodes.js file (that is part of the free download):

foldersTree = gFld("Root", "/tv/a.jpg")

foldersTree.xID = "B8A4"

aux1 = insFld(foldersTree, gFld("Folder 1", "/tv/b.jpg"))

aux1.xID = "1A2"

aux2 = insDoc(aux1, gLnk("R", "Doc 1", "/tv/c.jpg"))

aux2.xID = "XYZ"

Important notes:

If you are using xID, you must use it with all nodes in the tree.

If you are using xID, you must assign a value to the root node:

foldersTree.xID = ...

The capitalization of the variables and attribute names is important. If you usexId for example, it will NOT work.

The value of the xID of each node must be unique.

The value of the xID must be constant across the reload of the tree page.

The xID of one node should not depend on other nodes in the tree.

The PRESERVESTATE variable and, thus, the xID attribute are
important to preserve both the open/closed state of folder nodes and the highligh
state of nodes. If your tree does not require node highlighting, your work can be
simplified by assigning IDs only to folders.

If the structure of the tree can change during a visitor's session, it is probably
because the tree is being driven by a server-side application, and behind that
application there is a database. If that is the case, then it may be a good idea
to use the database keys for the xID values.

Creating from a Database

If you want to create a tree that shows directories and files on your server or
on your network, we have built a product specially for you: check out ourWeb File Browser.

If you want to create a Treeview that is built from the contents of a database,
read on.

Before you attempt any server-side coding with Treeview, it is important that
you read the Structure of Web Page andAdvanced Configuration sections.
The code for the dynamically generated TreeView will have the same general
structure as a static TreeView, and will be built using a subset of the functions
and configuration variables described above. If the TreeView you are creating will
have a large number of nodes, make sure to carefully read theAlternative API section.

After reading and understanding the above sections, you should examine the
code for the dynamic demo included in the free download. See the files that are
named demoDynamic*.*. This code provides you with a good starting point,
even if your project neither uses ASP nor Access databases. As you can see from
this code, the ASP file is fulfilling two roles: it generates the regular HTML
typical of a page that contains a tree, and it also generates the JavaScript that
is typically found in a separate, static demo*Nodes.js configuration file.

In order to generate the necessary gFld and gLnk statements,
the outputJavascript function in the demoDynamicLeftFrame.html
file queries the database. Please note how each call to response.write
is terminated by a new-line character. It is a common mistake to forget the
new-line characters between two JavaScript statements generated dynamically.

Debugging HTML Pages

When debugging HTML file containing a TreeView, the browser can be a very helpful
tool. Instructions for using the browser to debug follow:

Close your browser to clear any cached versions of TreeView or TreeView cookies
that are in memory.

Open the browser. If you are using Internet Explorer, make sure you have the
following settings (which are accessible from Tools > Internet Options > Advanced):

Disable script debugging: UNCHECKED (meaning enable script debugging)

Display a notification about every script error: CHECKED

Show friendly HTTP error messages: UNCHECKED ("friendly" is bad, in this case.)

If you are using Netscape or Mozilla, the log of error messages is available by
typing "javascript:" (without the quotes) in the Address bar. When you do this, a
window appears that provides a very powerful debugging environment.

If your Web page contains a static, client-side TreeView script, then the error
messages will indicate the line number in the configuration file that is causing the
problem. Note that a common cause of errors is related to the use of quotes in string
arguments. Make sure that all quotes are properly escaped.

Also note that the configuration, testing, or debugging of a TreeView script through
FrontPage or any other WYSIWYG HTML editor is not recommended.