affordable web development services

Tigra Tree Menu v1.1 - Documentation

Tigra Tree Menu Documentation
Table of Contents
Features
Compatibility Table
Files
Building Tree Hierarchy
Tree instance scope settings
Tree styles
Initialization
Terms and Conditions
Glossary
Links and References

Description

Tigra Tree Menu is a free JavaScript DHTML navigation system for web sites and web applications. Product looks and acts exactly as Microsoft Windows Tree Control. Offering the best performance on the market, script can manage hierarchies containing thousands of items.

Features

unlimited tree menu depth
unlimited number of tree menus on single page all independently configurable
easy items text styles setup
any icons set can be used
small script file (~5KB)
highly optimized code guarantees incredible performance (good results on trees containing 10,000+ items)
can be used either inline or with frames
future browser's versions ready
simple configuration file structure, easy to generate dynamically from database
object oriented JavaScript implementation for those who want to learn DHTML programming
best choice for site maps, online documentation and intranet applications

Compatibility Table

Note: For Tigra Tree Menu to work JavaScript and CSS support should be enabled in browser's settings.

Here is a table of the application compatibility:

Platform	Browser
Platform	MS IE	Netscape	Mozilla Firefox	Opera	Safari
Windows 95/98/ME/2000/XP	4.0+	6.2	0.9+	7.0+	3+
Mac OS 8/9/X	5.2	7.0+	0.9+	7.0+	1.3+

Other less popular browsers are supported by Tigra Tree Menu PRO

Files

Tigra Tree Menu script consists of several files. This makes script maintenance easier and reduces network load.
Default distribution package contains:

tree.js - Tree menu JavaScript code.
tree_items.js - Tree hierarchy file. All items of the tree component are defined here. See Building Tree Hierarchy section for more details.
tree_tpl.js - Tree instance scope template settings such as default icons, default target etc. are defined in this file. See Tree instance scope settings section for more details.
icons/*.gif - Default tree icons - this is standard set of icons supplied with the product. These icons can be replaced with custom ones.
- Tigra Tree Menu demo page
*.gif - Image files used by demo page

Where * is wildcard for any substring.

Script files should be attached to HTML document with appropriate tags in header:

<head>
	<!-- some header data -->
	<script language="JavaScript" src="tree_items.js"></script>
	<script language="JavaScript" src="tree_tpl.js"></script>
	<script language="JavaScript" src="tree.js"></script>
</head>

There are no naming or location requirements for script files. Main script file and dependent files can reside anywhere on the server in the folder accessible from the web. If the same files are used by several pages of the site then make sure links are correct for all of them.

Examples of correct script file links

Document	Location	Correct Links
Tree Menu Script	http://www.domain.com/tree_menu/tree.js	-
Page #1	http://www.domain.com/tree_menu/doc1.html	http://www.domain.com/tree_menu/tree.js (Absolute w. domain) /tree_menu/tree.js (Absolute w/o domain) tree.js (Relative)
Page #2	http://www.domain.com/dir1/doc2.html	http://www.domain.com/tree_menu/tree.js (Absolute w. domain) /tree_menu/tree.js (Absolute w/o domain) ../tree_menu/tree.js (Relative)
Page #3	http://www.domain.com/dir1/dir2/doc3.html	http://www.domain.com/tree_menu/tree.js (Absolute w. domain) /tree_menu/tree.js (Absolute w/o domain) ../../tree_menu/tree.js (Relative)

Notes:

If some file is linked incorrectly you'll receive JavaScript Error saying something like 'tree is undefined' or 'TREE_ITEMS is not defined'. Click on the icon in the browser's status bar to see the message.
It is possible to put the code from configuration files of the script directly in HTML document. Just copy the text from the tree_items.js and/or tree_tpl.js files into <script> tag and from tree.css file into <style> tag. You're not allowed to copy or use the code from tree.js anywhere except original file provided.

Building Tree Hierarchy

Tree Menu hierarchy is JavaScript structure that describes the content of navigation component, all its items and their links. Normally tree hierarchy resides in separate file: tree_item.js.

Items variable is associative array with list of root items. Each item is array itself containing one or more elements. Those elements are:

0 - Caption (required)
1 - Link (optional)
2+ - Child items (optional)

Below find example structure and the tree menu it creates:

var TREE_ITEMS = [
	['Home', '/',
		['Services', '/services.html'],
		['Download', '/download.html'],
		['Order',    '/order.html'],
		['Support',  '/support.html'],
	],
	['Level 0 Item 1', null,
		['Level 1 Item 0', 'another.html'],
		['Level 1 Item 1', 0,
			['Level 2 Item 0'],
			['Level 2 Item 1', 0],
		],
		['Level 1 Item 2'],
		['Level 1 Item 3'],
	]
];

Notes:

Only the first element is required. All others are optional, so you can omit them if no fields are behind them. Example is item with caption 'Level 1 Item 2': it has neither link nor options nor child items, so all those fields are just omitted. Otherwise missing fields should be replaced with 0's or null's to keep proper order. Example is item with caption 'Level 0 Item 1': it has neither link nor options but because of children items one null is specified in their place so child items are at correct offset in the array.
Commas after the last element of the array are ignored. This eases writing server side components that generate this structure dynamically. This also saves from errors when items are added, removed, copied in the blocks.
Item structure of Tigra Tree Menu is optimized for space efficiency so there is minimal formatting overhead. This makes pages load as fast as possible.
Be careful with quotation marks and apostrophes inside the strings, escape them properly to avoid syntax errors. Quotation mark within the string defined with the same character will be " for caption and \" for the link. Another solution is to reverse the order the quotes and apostrophes appear in the structure, i.e. if you need apostrophe within the string then you can define that string with quotation marks.
If you receive JavaScript errors double check the syntax of hierarchy structure. Try linking original unchanged tree_items.js file from the distribution package instead of your file to see if this is the reason.
Any HTML can be inserted into item's caption so you can apply text formatting settings just with regular HTML tags
Any code appropriate for HREF attribute of the anchor (<a ..>) can be specified in link field of tree item (http://, ftp://, javascript:, etc.)

Tree instance scope settings

By default Tree Template settings are located in tree_tpl.js file but they can be moved to any other JavaScript file linked to the HTML document containing the tree. This configuration code can also be inserted within <script> tag into HTML document itself.
Tree template structure is JavaScript associative array which defines default links target, default icons and default styles. Below is the list of supported keys with descriptions.

Configuration keys for tree instance scope settings

Key	Description	Accepted Values	Default Value

General
target	Name of the target frame or window for all item's links	some_name - in framed layout pages will be opened in the frame with this name, if there is no frame with such name or if in non-framed layout pages will be opened in newly created window. Following links will reuse same window.	_self
		_self - in framed layout the link will be opened in the same frame where tree menu appears. In non-framed layout same window will be used for linked documents. This setting is normally used as default target for non-framed layouts
		_blank - each link will be opened in new window
		_parent - in framed layout targeted document will be loaded in main window of the frameset, in non-framed layout it is equivalent to _self target
Icons (Root)
icon_32	Icon for a normal leaf root	path to the image	icons/base.gif
icon_36	Icon for a selected leaf root	path to the image	icons/base.gif
icon_48	Icon for a root	path to the image	icons/base.gif
icon_52	Icon for selected root	path to the image	icons/base.gif
icon_56	Icon for opened root	path to the image	icons/base.gif
icon_60	Icon for selected opened root	path to the image	icons/base.gif
Icons (Node)
icon_16	Icon for a node	path to the image	icons/folder.gif
icon_20	Icon for selected node	path to the image	icons/folderopen.gif
icon_24	Icon for opened node	path to the image	icons/folderopen.gif
icon_28	Icon for selected opened node	path to the image	icons/folderopen.gif
Icons (Leaf)
icon_0	Icon for a leaf	path to the image	icons/page.gif
icon_4	Icon for selected leaf	path to the image	icons/page.gif
Icons (Junctions)
icon_2	Junction Icon for leaf	path to the image	icons/joinbottom.gif
icon_3	Junction Icon for last leaf	path to the image	icons/join.gif
icon_18	Junction Icon for closed node	path to the image	icons/plusbottom.gif
icon_19	Junction Icon for last closed node	path to the image	icons/plus.gif
icon_26	Junction Icon for opened node	path to the image	icons/minusbottom.gif
icon_27	Junction Icon for last opened node	path to the image	icons/minus.gif
Icons (Misc)
icon_e	Path to transparent image	path to the image	icons/empty.gif
icon_l	Path to image with vertical line	path to the image	icons/line.gif

Below is the example of tree_tpl.js file content:

/*
	Feel free to use your custom icons for the tree. Make sure they are all of the same size.
	If you don't use some keys you can just remove them from this config
*/

var TREE_TPL = {
	'target'  : '_blank',	// name of the frame links will be opened in
							// other possible values are: _blank, _parent, _search, _self and _top

	'icon_e'  : 'icons/empty.gif', // empty image
	'icon_l'  : 'icons/line.gif',  // vertical line
	
	'icon_32' : 'demo1/icons/base.gif',   // root leaf icon normal
	'icon_36' : 'demo1/icons/base.gif',   // root leaf icon selected
	
	'icon_48' : 'icons/base.gif',   // root icon normal
	'icon_52' : 'icons/base.gif',   // root icon selected
	'icon_56' : 'icons/base.gif',   // root icon opened
	'icon_60' : 'icons/base.gif',   // root icon selected
	
	'icon_16' : 'icons/folder.gif', // node icon normal
	'icon_20' : 'icons/folderopen.gif', // node icon selected
	'icon_24' : 'icons/folder.gif', // node icon opened
	'icon_28' : 'icons/folderopen.gif', // node icon selected opened

	'icon_0'  : 'icons/page.gif', // leaf icon normal
	'icon_4'  : 'icons/page.gif', // leaf icon selected
	'icon_8'  : 'icons/page.gif', // leaf icon opened
	'icon_12' : 'icons/page.gif', // leaf icon selected
	
	'icon_2'  : 'icons/joinbottom.gif', // junction for leaf
	'icon_3'  : 'icons/join.gif',       // junction for last leaf
	'icon_18' : 'icons/plusbottom.gif', // junction for closed node
	'icon_19' : 'icons/plus.gif',       // junctioin for last closed node
	'icon_26' : 'icons/minusbottom.gif',// junction for opened node
	'icon_27' : 'icons/minus.gif'       // junctioin for last opended node
};

Notes:

Specify '_self' as default target in non-framed layout.
Make sure there is no comma after the last value. If one left browser will report JavaScript error: 'tree_tpl is undefined'

Tree styles

Styles used in tree

Style	Description	Accepted Values	Default Value

General
t*i	Style for caption of an item.	Name of CSS class defined for document	none
t*im	Style for image of an item.	Name of CSS class defined for document	none

Where * - zero based index of the tree in 'trees' array.
Notes: trees are indexing in the same order as their constructors are called in the document.

Initialization

Script initialization block creates navigation tree menu. This block can be located relatively, i.e. you can put it into table's cell and tree will be positioned on the page accordingly.

<script language="JavaScript">
<!-- //
	new tree (TREE_ITEMS, TREE_TPL);
// -->
</script>

Constructor accepts two parameters - tree hierarchy structure (see section Building Tree Hierarchy) and instance scope settings structure (see section Tree instance scope settings)

Notes:

You can have as many tree instances on your page as your wish. Each tree should be initialized separately
Several tree instances can share the same structure(s), i.e. different hierarchies, but same template
When adding more trees to the page don't forget to copy and rename CSS classes, for instance, with new index. (see Tree styles section for details)

Terms and Conditions

Tigra Tree Menu is FREE for any kind of applications. There is no license fee or royalty fee to be paid at any time for using the Tigra Tree Menu
You may include the source code or modified source code within your own projects for either personal or commercial use but excluding the restrictions outlined below. The following restrictions apply to all parts of the component, including all source code, samples and documentation:

The above items CAN NOT be sold as are (i.e. as JavaScript Tree Menu Component), either individually or together
The above items CAN NOT be modified and then sold as a JavaScript Menu component, either individually or together
Credits and product information CAN NOT be removed from the script. Add your version comments below that.

Glossary

Below is provided explanation for JavaScript Tree Menu related definitions that are used in this documentation. Descriptions are given in context of this document.

Instance - Independently configured and initiated JavaScript Tree Menu object.
Hierarchy - A logical tree structure that organizes the items such that each item has one parent item and zero or more child items. See Building Tree Hierarchy section for details.
Item - Basic element of the tree hierarchy with its own caption and optional link. Visually item is represented as the row with icon and text caption.
Parent - An item in the next higher level in a hierarchy that directly contains the current item.
Child - An item in the next lower level in a hierarchy that is directly contained by current item.
Node - An item having some child items.
Leaf - An item having no child items.
Root - An item with no parent item. The root is usually used as the label for whole tree hierarchy.
Instance scope settings - Global settings for tree instance and all its items. See Tree instance scope settings section for details
State - Settings applied to the item after some event occurred. Currently supported states are: opened, closed, selected, deselected.

Tigra Tree Menu v1.1 - Documentation

Table of Contents

Description

Features

Compatibility Table

Files

Building Tree Hierarchy

Tree instance scope settings

Tree styles

Initialization

Terms and Conditions

Glossary

Links and References