affordable web development services
| About Us | Services | Download | Order | Support | Subscribe to News Feed Follow us on Twitter Join us on Facebook |
 

Tigra Menu v2.1 - Documentation

Table of Contents

Description

Tigra Menu - is a popular JavaScript DHTML menu with rich feature set supported by the most modern browsers.

Features

Compatibility Table

Tigra Menu can work with any browser that supports DOM (Document Object Model). Here is a table of the application compatibility:

Platform Browser
MS IE Netscape Mozilla Firefox AOL Opera Safari
Windows 95/98/ME/2000/XP 5+ 6.0+ 0.9+ 5+ 5+ 3+
Mac OS 5+ 6.0+ 0.9+ 5+ n/a 1.0+
KDE on Linux/FreeBSD n/a 6.0+ 0.9+ n/a n/a n/a

Files

Although all data required for menu to function properly may reside in single html document it is not efficient in most cases. Dividing data into several files makes menu maintenance easier. This technique also reduces network load allowing clients to use cached files on sites with multiple pages.

Default configuration contains:

File indexes may be added to file names and structure names if multiple menus used. For example style sheet for menu with index 1 may have name menu_1.css.

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

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

<head>
	<!-- some header data -->
	<link rel="stylesheet" href="menu.css">
	<script language="JavaScript" src="menu.js"></script>
	<script language="JavaScript" src="menu_items.js"></script>
	<script language="JavaScript" src="menu_tpl.js"></script>
</head>

Compressed version

Compressed product version is available! You can find it in "compressed" directory of standard distribution package. It is identical with regular one, except of its size, i.e. it allows to speed up loading time and save your traffic. To use compressed version just copy file from mentioned above directory over any file of the same name from distribution package.

Building menu hierarchy

Menu items are JavaScript structure* that describes menu elements presented in the hierarchy.
Array value with list of root items is assigned to structure. Each item is array itself containing one or more elements. Those elements are:

Only the first element is required. All others are optional. Put null in place of skipped parameter to keep elements order. See code samples below.

var MENU_ITEMS = [
	['Home','http://www.your-site.com/'],
	['SoftComplex',  'http://www.softcomplex.com/', {'tw' : 'content'},
		['Services', 'http://www.softcomplex.com/services.html'],
		['Download', 'http://www.softcomplex.com/download.html'],
		['Order',    'http://www.softcomplex.com/order.html'],
		['Support',  'http://www.softcomplex.com/support.html'],
	],	
	['Level 0 Item 1', null, null,
		['Level 1 Item 0', 'another.html'],
		['Level 1 Item 1'],
		['Level 1 Item 2'],
		['Level 1 Item 3'],
	],	
];

Notes:

Caption

Caption defines text or html that will be printed within item's rectangle. Any applicable HTML is allowed within this parameter. For instance you can insert <img src="..> tag if you wish graphics within the item.

Link

Link defines text that will be inserted into href attribute of item's anchor tag. Usually this is page URL, but any appropriate value is possible.

var MENU_ITEMS = [ 
	['level 0 item 0', 'http://www.softcomplex.com/'], // Site URL 
	['level 0 item 1', 'ftp://ftp.softcomplex.com/'], // Link to FTP 
	['level 0 item 2', 'mailto:[email protected]'], // Mailto link 
	['level 0 item 3', "javascript:alert('Hello World!');"], // Script statement 
]; 

Sub Items

Any item may have unlimited number of sub items (child items). All sub items are defined the same way as containing item itself and listed after last item's parameter. To keep correct format of the structure if any optional parameters are omitted in parent item then make sure to put nulls in place of them before inserting any next level items. See first code sample in current main section.

Menu Level Scope Settings

By default Menu Template settings are located in menu_tpl.js file but they can be moved to any other JavaScript file linked to the HTML document containing the menu. This configuration code can also be inserted within <script> tag into HTML document itself.
Menu template structure is JavaScript associative array that describes how menu blocks and items are positioned and sized, how they look and behave at each level. Below is the list of supported keys with descriptions.

Configuration keys for menu instance scope settings
Key Description Accepted Values Default Value
 
General
width Horizontal size of an item in a sub-menu block, pixels A positive integer number none
height Vertical size of an item in a sub-menu block, pixels A positive integer number none
top Vertical offset between the items within level in pixels An integer number none
left Horizontal offset between the items within level in pixels An integer number none
block_top Horizontal offset of the upper left corner of a block relatively to the upper left corner of the parent item, in pixels.
If for root level (the one with index 0) is menu offset from the document's left upper corner, so use it for menu positioning on the page
An integer number none
block_left Vertical offset of the upper left corner of a block relatively to the upper left corner of the parent item, in pixels.
If for root level (the one with index 0) is menu offset from the document's left upper corner, so use it for menu positioning on the page
An integer number none
Delays
expd_delay A time delay between item mouseover corresponding sub-menu block expanding. The delay prevents from flashing sub-menus when the mouse crosses the menu. If negative value is provided then items are opened on click only. A positive integer number or null 0
hide_delay A time delay between moments of mouse pointer goes from above an item and of corresponding sub-menu block collapsing. Menu items may have some spacing between so the delay is applied before menu collapses after mouse pointer left the item. The bigger distances the more delay may be required.
Is not taken into account for root level (the one with index 0)
A positive integer number or null 0
Styles
css An associative JavaScript array for defining item styles   no styles
  outer A style class(es) for an outer tag for each state of an item.
Can be defined as a scalar value or an array of 1 to 3 elements, note that values are inherited from left to right if value set is not complete.
If defined as a JavaScript array then contains style class names for each item's state: [mouseout, mouseover, mousedown];
If defined as a string then is style class name for all item's states
An array of any (maximum three) valid style class names
or
any valid style class name
no style(s)
inner A style class(es) for an inner tag for each state of an item.
Can be defined as a scalar value or an array of 1 to 3 elements, note that values are inherited from left to right if value set is not complete.
If defined as a JavaScript array then contains style class names for each item's state: [mouseout, mouseover, mousedown];
If defined as a string then is style class name for all item's states
An array of any (maximum three) valid style class names
or
any valid style class name
no style(s)

Setting menu geometry

Picture and code sample below show how menu parameters are set with menu level scope settings structure. Cases illustrated are highlighted in code sample with blue background.

var MENU_TPL = [
{ 
	'width' : 100, 
	'height' : 25, 
	// C. Horizontal Offset between the items within level in pixels 
	'left' : 101,
	'top' : 0,
	'block_left' : 5,
	'block_top' : 50
},
{ 
	// A. Item's width in pixels 
	'width' : 130,
	// B. Item's height in pixels 
	'left' : 0,
	'top' : 26,
	'block_left' : 0,
	'block_top' : 26
},
{ 
	'width' : 160,
	'block_left' : 120
},
{ 
	'width' : 190,
	// D. Vertical Offset between the items within level in pixels 
	'top' : 26, 
	'block_left' : 140 
},
{ 
	'width' : 220, 
	// E. Horizontal Offset between adjacent levels in pixels 
	'block_left' : 160,
	// F. Vertical Offset between adjacent levels in pixels 
	'block_top' : 10
}
]

Notes:

Setting styles

Any menu item may have three states: when mouse pointer is out of the item ("mouseout"), over the item ("mouseover") and item click ("mousedown"). With Tigra Menu it is possible to define styles for a whole block and for any state for any level of any menu on the page.

Caption of any item is printed within two tags basically like this:

<div class="some_class_for_outer_tag">
<div class="some_class_for_inner_tag">
caption text
</div>
</div>

Styles may be defined for both tags. Usually attributes for item rectangle are assigned to outer tag (i.e. background, border etc.) and attributes for text to inner tag (i.e. font, size, color etc.)

Each level can have css key in its configurational structure. This key may contain sub-keys described in Configuration keys for menu instance scope settings table.

Any of css key sub-keys can be omitted as well as the whole css key.

Here is a sample of css structure:

  'css' : {
'outer' : ['menu0outo', 'menu0overo', 'menu0downo'] // item's outer tag: [mouseout, mouseover, mousedown],
'inner' : 'menu0inner' // item's inner tag, the same class for all states
}

You should note that not all browsers render style sheets the same. Always test your configuration with all versions expected.

Item Scope Settings

Tigra Menu item scope settings are defined locally for particular item. Item scope settings are defined in form of associative array which defines local settings for item target, window status bar message. This structure is inserted as third parameter of the item in hierarchy structure. Below there is a list of supported keys with their descriptions.

Configuration keys for menu item scope settings
Key Description Accepted Values
 
General
tw 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 - in framed layout the link will be opened in the same frame where 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 the 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
_top - in framed layout targeted document will be loaded in most outer window of the frameset, in non-framed layout it is equivalent to _self target
sb Status bar message - the text that will appear in the status bar of the window when mouse moves over the item Any text
tt Tooltip - the text that appears in the small (usually yellow) pop-up box when mouse stops over the menu item Any text

Note: Keys in item scope settings are shorter (2 chars) to keep this hierarchy structure compact.

Using inner HTML

Any HTML is allowed within item's caption (see Building menu hierarchy). Feel free to add complex table formatting and/or images to the menu items.

['<img src="icon.gif">&nbsp;SoftComplex', 'http://www.softcomplex.com/'],

Writing wrappers

When using inner HTML feature many items can have same or similar HTML formatting. In such cases using wrapper functions reduces download time and eases menu maintenance.

Wrappers are simple JavaScript function that you write to generate HTML around the items caption. With wrapper defining color for the item may look like this:

function wrap_grn (text) {
	return '<span style="color: green;">' + text + '</span>';
}
function wrap_org (text) {
	return '<span style="color: orange;">' + text + '</span>';
}
function wrap_red (text) {
	return '<span style="color: red;">' + text + '</span>';
}
var MENU_ITEMS = [
	// level 0 item 0
	[ wrap_grn('level 0 item 0'), "javascript:alert('Click on level 0 item 0!')"],
	// level 0 item 1
	[ wrap_org('level 0 item 1'), "javascript:alert('Click on level 0 item 1!')"],
	// level 0 item 2
	[ wrap_red('level 0 item 2'), "javascript:alert('Click on level 0 item 2!')"],
];

or even better solution:

function wrap (text, color) { 
	return '<span style="color: ' + color + ';">' + text + '</span>';
} 
var MENU_ITEMS = [ 
	// level 0 item 0 
	[ wrap('level 0 item 0', 'green'), "javascript:alert('Click on level 0 item 0!')"], 
	// level 0 item 1 
	[ wrap('level 0 item 1', 'orange'), "javascript:alert('Click on level 0 item 1!')"], 
	// level 0 item 2 
	[ wrap('level 0 item 2', 'red'), "javascript:alert('Click on level 0 item 2!')"], 
]; 

This technique doesn't pay much on small menu hierarchies or if only few items have HTML decoration, but it definitely should be used on large menus with rich items formatting. Code of the wrappers can be saved together with menu items structure in the same file, keeping clear logical structure of menu configuration.

Styles vs. inner HTML

In most simple cases it is possible to achieve the same look of the item with either styles or inner HTML. Although styles are easier to manipulate and experiment with, inner HTML can provide wider browser compatibility.

Adding menus to page

In order menu to work all required files should be linked to HTML document. Then construction is called for each menu instance on the page. Constructor for each menu receives two parameters:

  1. Menu Hierarchy structure (see Building menu hierarchy section)
  2. Menu Geometry structure (see Menu Level Scope Settings section)

Menu initialization block is normally placed before closing tag of the HTML's body:

	<!-- some html -->
	<script language="JavaScript">
		new menu (MENU_ITEMS, MENU_TPL); 
	</script>
</body>
</html>

Case with three menus on the page may look like:

	<!-- some html -->
	<script language="JavaScript">
		new menu (MENU_ITEMS1, MENU_TPL1); 
		new menu (MENU_ITEMS2, MENU_TPL2); 
		new menu (MENU_ITEMS3, MENU_TPL3); 
	</script>
</body>
</html>

Note: Inserting menu initialization block within relatively positioned HTML element (table cell for example) will not change menu positioning. Use Menu Geometry structure for that.

Terms and Conditions

Tigra 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 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:

Links and References