Hollsco Group - TreeMenu Documentation

TreeMenu is a web page module that allows you to quickly and easily create and maintain a menu tree system in your ASP pages, featuring pop-up text, boxes, rollover (mouseover) graphics, and more. All of this is done using the simple TreeMenu configuration utility instead of attempting to write arcane Javascript code by hand - TreeMenu does it all for you!

TreeMenu can automatically generate a full hierarchal menu tree system such as the one at the right as well as graphical animated menu tree systems (such as this one), and much more - with absolutely no manual coding!

Table of Contents

• Sample Code
• Sample Database Code
• Methods and Properties
• Configuration Utility
  • Editing Page Entries
  • FrontPage Integration
  • Creating Blank Menu Files
  • Custom Javascript Code
  • File Conversion
  • OverLib Pop-Up Capability
• Database
  • Creating the Database
  • Configuration Utility Database Use
• Registration
• FAQ

TreeMenu Code

The code required to insert a fully-functional menu can be very small:

<% Dim TreeMenu Set TreeMenu = Server.CreateObject("TreeMenu.nsTreeMenu") TreeMenu.CurrentURL = Request.ServerVariables("URL") TreeMenu.NavFile = Server.MapPath("/SiteMap.tmu") Response.Write TreeMenu.GenMenu Set TreeMenu = Nothing %>

Let's analyze possible lines used in this code:

Database Code

To generate a menu from a database source is just slightly different:

<% Dim TreeMenu Set TreeMenu = Server.CreateObject("TreeMenu.nsTreeMenu") TreeMenu.CurrentURL = Request.ServerVariables("URL") TreeMenu.ConnectionString = "driver={SQL Server Native Client 11.0};server=localhost;uid=UserName;pwd=Password;database=TreeMenu" TreeMenu.TableName = "Menus" TreeMenu.MenuName = "ThisMenu" Response.Write TreeMenu.GenMenu Set TreeMenu = Nothing %>

There are three different lines used in this code. When any of these three properties are set, TreeMenu will automatically attempt to retrieve its menu information from the database the next time GenMenu is called. Specifying the NavFile or NavString properties will cause TreeMenu to revert to the default (non-database) method the next time GenMenu is called.

TreeMenu Methods and Properties

Name	Type	Function
ConnectionString	String	Used for database functionality, specifies the ADO connection string used to connect to the database.
CurrentURL	String	Passes the full URL of the currently viewed page to TreeMenu before the page is generated. Allows TreeMenu to determine which menu item to show as "open"
GenMenu (Optional String FileNam)	Method	Generates the HTML code containing the menu according to the given parameters and the parameters in the configuration file. Returns the HTML code as a string. Can optionally be passed the location of the configuration file instead of using the NavFile property.
IconDir	String	Directory containing the TreeMenu icon image files. Relative to the directory of the page being displayed. Can be specified in the configuration file. Specifying the value with this property overrides the value in the configuration file.
ImageDir	String	Directory containing the images used for image-based menus. Relative to the directory of the page being displayed. Can be specified in the configuration file. Specifying the value with this property overrides the value in the configuration file.
MenuName	String	Used for database functionality, specifies the name of the menu contained within the table. Maximum 20 characters.
NavFile	String	Specifies the physical location on the disk of the server of the TMU configuration file that TreeMenu will read its configuration and menu definitions from.
NavString	String	String containing a full XML document in the standard TMU format from which TreeMenu will generate its menu. Specifying both a NavFile and NavString will cause TreeMenu to use the NavFile property and to ignore the NavString property.
RegisterKey (String Key)	Method	Deprecated, but included for backwards compatibility. No functionality.
SelectedColor	String	The color used to display the text of the currently selected page. Specifying a value in this property overrides values set in the TMU configuration file.
SetAllOpen	Boolean	When true, all items in the menu will be shown, and all trees will be open.
SetDebug	Boolean	Turns a special debug mode on, for use when debugging problems with technical support.
TableName	String	Used for database functionality, specifies the name of the table containing the TreeMenu menu information
Target	String	Default target page for all links generated by TreeMenu. Specifying a value in this property overrides values set in the TMU configuration file.

Configuration Utility

Previous versions of TreeMenu used a plain text configuration file. TreeMenu 4.0 and above use an XML format TMU configuration file which can be easily modified by any XML-aware application. TreeMenu reads its menu information from this file, which can be located anywhere on the server PC, or from within a FrontPage web, by double-clicking on the TMU file. Instead of manually modifying the text-based configuration file, TreeMenu now uses a full-featured configuration utility.

The first thing you will notice is the Static Configurations box at the top right of the screen. This allows you to set parameters to apply to your menu without having to do so every time you construct the menu in your ASP code.

• Generate indentation in menu: If this box is checked, then TreeMenu will utilize the standard indentation system as previous versions always have. When this box is left unchecked, TreeMenu will still function normally, but it does not use any indentation - all menu items will be flush left. This is useful if you are going to be using graphics rather than textual representations of your menus. If "Use menu tree icons" is selected, this option is disabled and selected, as it can not be turned off if icons are being used.
• Beginning at indent level: New in TreeMenu 4.2 is the ability to define at what indentation level the generated indentation will begin. If this is set at "2" for instance, any menu item at level 0 or 1 will be flush left, and indentation will be generated for any menu items at levels 2 or above. This can be used when combining graphical and textual menus. If "Use menu tree icons" is selected, this option is disabled, and automatically sets itself to the level set for the menu tree icon level.
• Use menu tree icons: If this box is checked, then TreeMenu will utilize the standard icon graphics as previous versions always have. When this box is left unchecked, TreeMenu will still function normally, showing only the menu options within the tree that you should be able to see, but it does not use any icon graphics or indentation. This is useful if you are going to be using graphics rather than textual representations of your menus. Selecting this option disables the "Generate indentation in menu" option, which is required when menu tree icons are used.
• Beginning at indent level: New in TreeMenu 4.2 is the ability to define at what indentation level the generated icons will begin. If this is set at "2" for instance, any menu item at level 0 or 1 will be flush left, and indentation will be generated for any menu items at levels 2 or above. This can be used when combining graphical and textual menus.
• Use rollover graphics: If this box is checked, TreeMenu will use graphic images instead of textual descriptions in the menu display. The graphic files shown for each menu item are specified in the four "Image URL" boxes at the bottom of the screen. Simply specifying the same image filename in all four boxes will cause TreeMenu to show a single graphic for each menu item with no animated rollover functionality. If this box is checked and an individual menu item has no "Non-Current Normal Image URL" specified, TreeMenu will use the standard text description for that item only.
• Use Overlib pop up windows: TreeMenu version 2 introduced the support for the public-domain Overlib pop-up window library. This library is included in the TreeMenu distribution as overlib.js - you may wish to check the web site for an updated version. If this box is checked, TreeMenu will automatically generate Javascript code to support the Overlib pop-up windows.
• Use status bar descriptions: If this box is checked, TreeMenu will automatically generate Javascript code to make the Description text for each menu item appear in the bottom of the web browser frame.
• Default Icon Directory: In previous versions, the default image directory (where TreeMenu icon graphics were stored) was set in ASP code. This can now be set once in the XML configuration file, so that it does not have to be set repeatedly in the ASP code. It should be an absolute URL, rather than a relative URL, i.e. it should start with a forward slash and describe exactly where the files exist.
• Default  Image Directory: When using Rollover graphics, the default directory where these graphics are stored can be specified here. It should be an absolute URL, rather than a relative URL, i.e. it should start with a forward slash and describe exactly where the files exist.
• Default Target Frame: If you are using TreeMenu in a framed web site, you can set the default frame in which you wish selected pages to be opened. This should be the frame name, i.e. "MainFrame". Frame default names such as "_self" are also acceptable.
• Default Selected Color: If you are using the textual (non-graphic) option, the currently selected page can show up in a different color than the regular text color. You can specify the color here, in proper HTML form (i.e. #FF00FF)

Editing Page Entries

To the left of the page is the menu tree listing box, within which is a text representation of the menu tree being edited. The letter preceding the description indicates the icon used:

• H - Home
• F - Folder
• D - Document

Next to the letter is the description of the page. For readability, it is a good idea to use the description field even if you are having TreeMenu generate a graphics-only menu. To select the menu item you wish to modify or create, click on it in the menu tree listing box. Underneath the menu tree listing box are the menu modification buttons:

  Delete the currently selected menu item from the menu tree

  Insert a new menu item above the currently selected menu item

  Insert a new menu item below the currently selected menu item

  Move the currently selected menu item or tree up

  Move the currently selected menu item or tree down

Underneath the menu item up/down buttons is the option "Move Trees." When selected, clicking a menu item up or down button will move the entire tree (the currently selected menu item and every menu item with a lower level) rather than an individual menu item. This is useful for moving entire trees up and down within the menu structure without having to move each tree item individually.

When a menu item is currently selected, its values appear in the fields to the right of the menu tree listing box:

• Level: This is the indentation level of the menu item. Level 0 causes the menu item to be a top-level item, which is shown at all times. Level 1 causes the menu item to be a second-level item, which is shown only when its parent (Level 0) menu item is open. Level 2 items are shown when their parent Level 1 items are open, and so on.  If you wish, you can use the Icon level buttons to move individual items up and down a level.
• Icon: This is the name of the icon you wish to display for the menu item. The three defaults are Home, Folder and Document. If you have created icons you wish to use, you can type the name of the icon here instead of selecting a default icon. When typing your custom icon name, type only the filename, excluding the ".gif" portion (all icons are assumed to be in the .gif format).
• Description: This is the description of the menu item. It is shown in the menu tree listing box, and if the menu being generated is a non-graphical menu, it is shown next to the icon for the user to click on. If the Status Bar Descriptions option is selected, it is also shown in the bottom of the web browser frame.
• URL: This is the address of the page that the user will be taken to if he or she clicks on this menu option. It can be absolute, relative, or can point to a different web site altogether. It functions as a normal web page link would.
• Aliases: Any URL entered in this box will be identified as this menu entry. For instance, if we put "testing.html" in this box, and we visit the "testing.html" page, TreeMenu will open this menu entry as if it were the selected entry. Unlimited multiple aliases can be specified for each menu entry, one per line. This could be used in a situation where you have a "Funny Jokes" page. You don't want to have an entry on the TreeMenu system for every funny joke in the system, so you could list each of the joke URLs in the Alias box instead. This would cause the "Funny Jokes" entry to be selected when any of the joke URLs were opened in the browser. New in version 4.2 is the ability to use wildcards - instead of listing every joke URL, you could put all jokes in a "/jokes" directory, and insert the following alias: /jokes/*
• Frame Target: If this is left blank, the menu item target page will be opened in the "Default Target" target frame. If the "Default Target" field is left blank, TreeMenu will default to opening the page in the current browser page. If you are not using frames in your site, both this field and the "Default Target" field should be left blank. The only exception to this is if you wish a link to open a new browser instance, in which case you would select "_blank" in this field for that menu item. The defaults already available in this field are:
  • _self - Same frame as the TreeMenu generated menu
  • _top - Whole page, ignoring frame restrictions
  • _blank - New browser instance
  • _parent - Parent frame of the TreeMenu generated menu frame
• Overlib Pop-Up Text: This is the text that will be contained within the pop-up window when the user's mouse cursor hovers over this menu item. It can contain instructions, details, or any other text you want the user to see when he or she is contemplating selecting this menu item. This text is only used if the "Use Overlib Pop-Up windows" option is selected.

The next four fields are used if the "Use Rollover Graphics" menu item is selected. 

• NormStdImageUrl: This is the relative URL of the image shown when the page is not the currently shown page and the mouse cursor is not over top of the image. If this is left blank for an individual menu item, then TreeMenu will use the regular text description instead.
• NormRollImageUrl: This is the relative URL of the image shown when the page is not the currently shown page and the mouse cursor is over top of the image.
• NormStdImageUrl: This is the relative URL of the image shown when the page is the currently shown page and the mouse cursor is not over top of the image.
• NormRollImageUrl: This is the relative URL of the image shown when the page is the currently shown page and the mouse cursor is over top of the image.

The images can be the same - for instance, you may wish to make no distinction between whether or not the page is currently selected or not. In this case, the values for NormStdImageUrl and NormStdImageUrl would be the same, and the values for NormRollImageUrl and NormRollImageUrl would be the same. Similarly, you may wish to use images rather than text, but to not use any rollover functionality at all. In this case you would still turn "Use Rollover Graphics" on, but all four ImageURL values would point to the same image.

FrontPage Integration

If you are editing your TMU file from within FrontPage, you can use a new feature to quickly select the images to use in your rollover image setup. Before double-clicking on your TMU file inside your FrontPage web, select Tools, TreeMenu, and Make TreeMenu File List: 

Once this has completed, then open your TMU file by double-clicking on it within FrontPage. The TreeMenu configuration utility will launch, and the image list window will be populated with all available images. To move an image into the appropriate rollover image box, select the image in the list, and simply click on the button next to the box.

When you have finished creating or editing your menu tree, be sure to save your file by selecting File/Save. Changes you make to the XML format TMU file are not saved until you select File/Save. If working from within a FrontPage web, make sure you close the TreeMenu configuration utility before working on other files from within FrontPage.

Creating Blank Menu File Within FrontPage

In previous versions of TreeMenu, creating a blank TMU file and importing it into a FrontPage web was a bit of a hassle. Now it can be done quickly from within the FrontPage menu. Select Tools, TreeMenu, and Create Blank Menu File. That's It!

Custom Javascript Code

One of the most powerful new features of TreeMenu 4.2 is the ability to specify actual Javascript code that will be inserted into the generated menu. This allows you to extend the functionality of your menus far beyond what was capable with previous versions.

When editing a page that you wish to have Javascript inserted for, click on the "Edit" button next to the "Custom Javascript Code" indicator. This indicator will appear checked when there is custom code associated with the currently viewed page. When the "Edit" button is clicked, the following screen will appear:

Code added if item is currently selected page: The Javascript code specified here will be inserted into the beginning of the generated TreeMenu HTML code, before any menu handling code, only if the page associated with this code (listed in the heading) is the current page.

Code added if item is not currently selected page: The Javascript code specified here will be inserted into the beginning of the generated TreeMenu HTML code, before any menu handling code, only if the page associated with this code (listed in the heading) is NOT the current page.

If the same code is specified in both of the above fields, then it will be inserted into EVERY menu generated for the site, regardless of the current page. This is a simple way to have TreeMenu insert identical Javascript code into a web site that instantly updates on every page when the associated TMU file is changed. Note that in this case, it should be entered into only one page - i.e. the first page.

onMouseOver override code: Any Javascript code inserted here will be inserted into the onMouseOver event associated with that page. If you are using the OverLib routines to generate Javascript code automatically, this code will be appended to the OverLib generated code. This is a simple way to make other things on your web pages happen when the mouse moves over certain menu items.

onMouseOut override code: Any Javascript code inserted here will be inserted into the onMouseOut event associated with that page. If you are using the OverLib routines to generate Javascript code automatically, this code will be appended to the OverLib generated code. This is a simple way to make other things on your web pages happen when the mouse moves over certain menu items.

onClick override code: If any Javascript code is specified here, TreeMenu will create a onClick event associated with that page, and insert this code into that event. OverLib does not use onClick events, so if you are not using OverLib and no code is specified here, then code to handle an onClick event will not be created. This is a simple way to make other things on your web pages happen when the mouse moves over certain menu items.

Important: The code specified in the page above will be inserted verbatim into your web page. If there are errors in the Javascript code that you enter into this form, those errors will appear on your web page. Ensure you end your lines and commands with a semicolon!

Important: When saving data to a database rather than a TMU file, keep in mind you are limited to 7500 characters of data for the XML block containing each menu entry. If you are utilizing large custom javascript code and are saving the menu configuration to a database, you need to ensure it will be contained within the space limit. An error will occur during saving to the database if the configuration does not fit within the space restriction.

Conversion of old Site Map Files to TMU Format

Previous versions of TreeMenu used flat text files to store configuration information. These were complex to edit, were not extensible, and made the implementation of new features very difficult, while retaining compatibility with previous versions. TreeMenu 4.0 introduced XML format configuration files which are fully extensible and structured. You can look at the format of the generated TMU file by renaming the extension from TMU to XML, and opening it from within Internet Explorer. It will be opened in your web browser, and you will be able to see for yourself the new structure of the file.

However, existing web sites still use the old flat text configuration file. For this reason, a conversion utility was included in the new XML configuration utility. To access it, select File/Convert Old Configuration File from the configuration utility menu. 

You will be able to browse to find the file you wish to convert. Once you have selected the file to convert, click the Convert button to begin. The new XML file will be written out using the same filename, only with a .TMU extension. You will then be able to load this new XML formatted file into the configuration utility to make any modifications you wish.

Don't forget that your ASP files will now need to point the new version of TreeMenu to the new XML format TMU configuration file rather than the old text file! TreeMenu 4.0 and above will not work with the old text configuration file.

Overlib Pop-Up Text Capability

TreeMenu has the ability to use the public-domain Overlib, which produces the pop-up cursor windows that appear when the mouse cursor moves over items in the menu, as demonstrated on this site. Version 3.10 of the Overlib code is included in this version of TreeMenu, as "overlib.js". In order for the Overlib pop-up code to work properly, it is imperative that you follow these instructions:

1. Copy the overlib.js file into your web site.
2. Add these lines just above the TreeMenu insertion code on each page that uses TreeMenu:
     
   <SCRIPT LANGUAGE="JavaScript" src="images//JScript/overlib.js"></SCRIPT>
    
3. Replace the "/JScript/overlib.js" with the actual absolute path to the overlib.js file that you copied to the web in step 1. In this case, the overlib.js file exists in a directory called "JScript".

Overlib Configuration

The TreeMenu Configuration utility has the ability to generate Overlib-specific configuration code that allows you to specify exactly how you wish your pop-up windows to appear. This allows you to utilize such advanced features as background images, borders and other advanced options simply by filling in a few fields. To access the Overlib Pop-Up configuration screen, select Edit/Edit Overlib Pop-Up Properties from the main configuration utility menu.

Letting your mouse cursor hover over each field will cause a pop-up to come up and descript just what the field's purpose is. Leaving the field blank causes Overlib to use its default value. The Picture URL values should be absolute values (i.e. they start with a "/"). The text box to the right of the color selection buttons shows a sample of what the box will look like with the colors that are selected. If you require more information on just how the various parameters operate, you should refer to the Overlib documentation page.

Database

TreeMenu 4.3 introduced the capability to store menu information in a database as well as in the standard TMU files. Before attempting to use the database functionality, it is imperative that both the PC running the configuration utility and the PC running the web server/TreeMenu component have at minimum version 2.62 of Microsoft Data Access Components installed. These components can be downloaded for free from the Microsoft site: http://www.microsoft.com/data/download_26sp2.htm

TreeMenu knows how to connect to the database through use of an ADO connection string. Some example connection strings are shown below. Replace "ServerName" with the name of your server, "UserName" with your login name, "Password" with your password, and "DatabaseName" with the name of the database holding the tables you wish to access.

SQL Server:

driver={SQL Server Native Client 11.0};server=ServerName;uid=UserName;pwd=Password;database=DatabaseName

driver={Microsoft Access Driver (*.mdb)};DBQ=c:\Path\Filename.mdb
(replace "c:\path\Filename.mdb" with the path and filename of your Access database)

driver={Microsoft Access Driver (*.mdb)};uid=UserName;pwd=Password;DBQ=c:\Path\Filename.mdb
(for use with passworded Access databases)

DSN (for data sources listed in the ODBC configuration applet):

dsn=DSNName;uid=UserName;pwd=Password

Creating the Database

TreeMenu expects a standard database structure, as follows:

In SQL, this would appear as such:

CREATE TABLE [dbo].[TableName] (
    [MenuName] [char] (20) NOT NULL ,
    [MenuNum] [char] (60) NULL ,
    [XMLConfig] [varchar] (7500) NULL 
  ) ON [PRIMARY]

Configuration Utility Database Use

To access the database from within the configuration utility, select File/Load From Database or File/Save To Database from the main menu. You will be presented with the database interaction screen:

Enter the ADO connection string in the box provided. The ? button displays the required formats for the string.

The table name will be the name of the table you created to hold the menu. Once you have entered the table name and moved the focus away from that field, or if you click the "Update Menu List" button, the utility will connect to the database and populate the "Menu Name" box with all of the currently stored menus. Multiple menus can be stored within a single table, distinguished by their name. You can select one of the menus (Load or Save) or type in a new menu name (Save). Clicking the Load/Save button will then read the menu from the database (Load) or write the menu to the database (Save).

Utilizing a database menu source rather than a TMU file source from within the web page itself requires a minor change in coding, and is detailed here.

Registration

An unregistered version of TreeMenu will insert a reminder in each menu generated that you need to register in order to legally use TreeMenu on a production web site. Developers are welcome to run unregistered versions of TreeMenu on their development machines. To register TreeMenu, run the TreeMenu Configuration Utility, and select Help/Register TreeMenu from the main configuration menu. Make sure you do this on the production machine on which you wish to run the registered copy of TreeMenu!

Click the "Click here to visit the online registration page" line to be taken to the purchase page. It will ask you for your credit card details, and will then issue you a license key. SAVE THIS KEY! Type the key into the provided box and click the "Register License Key" button. It will respond by telling you that the registration has been completed. You will need to reboot the PC to allow the TreeMenu web component to read the registration information. From this point forward, TreeMenu will no longer insert its reminders into any generated menus.

Frequently Asked Questions

TreeMenu  is Copyright © 2000, 2001, 2002 Hollsco Group.
This page Copyright © 2002 Hollsco Group. All rights reserved.
All specifications subject to change without notice.