Currently in: TreeView > Documentation

Javascript Tree Menu

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.

Back To Contents

Installing TreeView

  1. Download TreeView and extract the files from the ZIP onto your computer.
  2. Open index.html in your browser and try the demos.
  3. 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.
  4. 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 rename demoFramesetRightFrame.html but then you will need to update both demoFramesetNodes.js and demoFrameset.html. The demoFrameset.html file (the file that is most visible to visitors) can be renamed without any dependency problems.

Back To Contents

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.
  • A script tag that loads the browser detection code (ua.js).
  • A script tag that loads the Treeview engine code (ftiens4.js).
  • A script tag that loads your tree configuration file (demo*Nodes.js, for instance.)

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.

Back To Contents

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 to 1 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.
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)
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 the HIGHLIGHT_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
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: 'images/', '', 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 with STARTALLOPEN=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.
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.)
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
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
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
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 the style tag at the top of the left-frame HTML file.

Back To Contents

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 the TreeView Developer's Resources page.

Back To Contents

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 like demoFramesetRightFrame.html or a string with protocol, domain, path, and file name like

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 named basefrm)
"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 text My File in the tree, and clicking on this node displays the file in a new window:

gLnk("B", "My File", "")

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:

gLnk("Bh", "My File", "")

Back To Contents

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. The insDoc 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:

  1. Create the root folder. For example:
    foldersTree = gFld("<i>Demo</i>", "demoFramesetRightFrame.html")
  2. Place folders inside other folders by using the insFld function. For example:
    aux1 = insFld(foldersTree, gFld("Europe", "http..."))
  3. 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:

foldersTree = gFld("jack's", 'javascript:alert("jack" + String.fromCharCode(39) + "s")')
insDoc(foldersTree, gLnk("R", "jack\'s", 'javascript:alert(\\\'jack\\\' + String.fromCharCode(39) + \\\'s\\\')'))
insFld(foldersTree, gFld("db quote:\"", 'javascript:alert("db quote:" + String.fromCharCode(34))'))
insDoc(foldersTree, gLnk("R", "db quote:\"", 'javascript:alert(\\\'db quote:\\\' + String.fromCharCode(34))'))

Back To Contents

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, the insDoc 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 the addChildren 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*.*.

Back To Contents

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:

aux1 = insFld(foldersTree, gFld("Other icons", "javascript:parent.op()"))
aux1.iconSrc = ICONPATH + "diffFolder.gif"
aux1.iconSrcClosed = ICONPATH + "diffFolder.gif"

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. The diffFolder.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:

docAux = insDoc(aux1, gLnk("B", "D/L Treeview", ""))
docAux.iconSrc = ICONPATH + "diffDoc.gif"

For document node icons, it is the iconSrc attribute that specifies the icon.

Back To Contents

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 special span 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.

Back To Contents

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:

newObj = insDoc(aux1, gLnk("B", "Item 5", "..."))
newObj.prependHTML = "<td valign=middle>not part of link</td>"

Or more to the point:

newObj.prependHTML = "<td valign=middle><input type=checkbox id='CB1'></td>"

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.

Back To Contents

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.

Back To Contents

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:

foldersTree = gFld("Three years", "demoLargeRightFrame.html")
foldersTree.treeID = "t3"

Back To Contents

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. The PRESERVESTATE 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 the demoLargeNodes.js file (that is part of the free download):

foldersTree = gFld("Root", "a.jpg")
foldersTree.xID = "B8A4"
  aux1 = insFld(foldersTree, gFld("Folder 1", "b.jpg"))
  aux1.xID = "1A2"
    aux2 = insDoc(aux1, gLnk("R", "Doc 1", "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 use xId 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.

Back To Contents

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 our Web 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 and Advanced 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 the Alternative 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.asp 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.

Back To Contents

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.

Back To Contents