DOM Menu Library HOWTO

Setup and Usage

This library offers a variety of ways to enable dynamic menus. In order to create a menu, you must first create a container element on your web page, such as a div tag. This container element becomes the bounding box for the menu. By controlling the dimensions of this element, you can control the area which the menu will occupy. The first listing shows an example of a container element. The contents of the container are generated by menu creation script.

<div id="domMenu_main"></div>

Immediately following this element, you will place the script that activates the menu. Alternatively, you could place the activation in the onload event of the browser. The activation block is show in the next listing.

<script type="text/javascript">domMenu_activate('domMenu_main');</script>

But wait! The menu cannot be activated without data! Alas, the value specified in the XHTML ID attribute of the container element must correspond to the name of a menu that is defined in the menu items data structure. Typically, you will store the definitions in a seperate file that is included in each page. The example below defines te two top level menu items, each with one child element.

domMenu_data.set('domMenu_main', new Hash(
	1, new Hash(
		'contents', 'First Parent',
		'uri', 'parent1.html',
		1, new Hash(
			'contents', 'First Child',
			'uri', 'child1.html'
		)
	)
	2, new Hash(
		'contents', 'Second Parent',
		'uri', 'parent2.html',
		1, new Hash(
			'contents', 'Second Child',
			'uri', 'child2.html'
		)
	)
));

This structure looks complex at first, but it is actually quiet strightforward. The Hash class takes alternating parameters of key -> value pairs. Each level of the menu is represented by a Hash object, with the numeric key representing the position of the item within that level. Pay very close attention to the location of the commas, as this is often the source of syntax errors.

Once created, the menu consists of a div element for the menubar and a div element for each menu item. Behind the scenes, there is actually a table inside the menubar and each item is inside of a table cell. However, this table is invisible and used merely for width distribution across the page.

The look and feel of the menu is controlled by the style definitions for each of these div elements. The style classes used are specified in the menu settings data structure. An example set of menu setting data is shown in the next listing.

domMenu_settings.set('domMenu_main', new Hash(
	'openMouseoverMenuDelay', 100,
	'closeMouseoverMenuDelay', 300
);

Keep in mind that each menu block and menu item can be styled individually using the assigned ID attribute. The pattern is #menuName-n, #menuName-n-m, ... where n and m are the index values of the item in sequence, and each hyphen represents one level of nesting. For instance, the fourth item in the submenu of the second top level item would have the ID #menuName-2-4. The menu block is represented with an index value of 0. Hence, the menu block containing the item just mentioned would have the ID #menuName-2-0.

Finally, to complete the installation of your menu, you must import the menu script into your page. The distribution comes with the file domMenu_min.js, which is a compressed version of the library. The other two files, domLib.js and domMenu.js are the formatted sources contained in this combined file.

<script type="text/javascript" src="domMenu_min.js"></script>

Menu Definition Options

As mentioned above, the menu definition is specified using a nested Hash. The items must be numbered sequentially for each level starting with 1 (as opposed to 0). The contents of the Hash alternate between key and value, seperated by commas. The list below catalogs the available options.

contents [text|xhtml]: The contents of the menu item, which may be XHTML text.
contentsHover [text|xhtml]: The contents of the menu item when the mouse is hovering over it. This content may be displayed immediately, even if the rendering of the child menu is on a delay.
uri [uri|javascript]: The target location of this menu item when clicked. If the value begins with a forward slash (/), the baseUri will be prepended to the target. If this value begins with javascript:, the javascript code will be executed instead.
target [string]: The target window of this menu item when clicked. This value is the same as the target attribute of a link tag.
statusText [string]: The text that will be displayed in the browser status bar when the menu item receives focus.

Menu Settings

Each menu can be associated with a group of settings. The settings are also stored in a Hash data structure similar to the menu definition.

baseUri [uri]: The location that is prepended to the menu item uri if it begins with a forward slash (/).
menuBarClass (default: 'domMenu_menuBar'): The CSS style class used for the top level menu bar.
menuElementClass (default: 'domMenu_menuElement'): The CSS style class used for a top level menu item.
menuElementHoverClass (default: 'domMenu_menuElementHover'): The CSS style class used for a top level menu item with focus.
menuElementActiveClass (default: 'domMenu_menuElementHover'): The CSS style class used for a top level menu item when its child menu is open.
subMenuBarClass (default: 'domMenu_subMenuBar'): The CSS style class used for a child menu.
subMenuElementClass (default: 'domMenu_subMenuElement'): The CSS style class used for a child menu item.
subMenuElementHoverClass (default: 'domMenu_subMenuElementHover'): The CSS style class used for a child menu item with focus.
subMenuElementActiveClass (default: 'domMenu_subMenuElementHover'): The CSS style class used for a child menu item when its child menu is open.
subMenuElementHeadingClass (default: 'domMenu_subMenuElementHeading'): The CSS style class used for a child menu item serving as a heading (no link).
subMenuTargetFrame [string] (default: false): The frame in which to place the child menu. The menu can only jump frames for the first submenu level. Only east or south expansion is supported.
targetDocumentXOrigin [int] (default: 0): The horizontal offset for positioning a child menu in its target frame.
targetDocumentYOrigin [int] (default: 0): The vertical offset for positioning a child menu in its target frame.
menuBarWidth [px|percentage] (default: 100%): The width of the entire menu bar.
subMenuMinWidth (default: inherit): The minimum width of a submenu.
distributeSpace [boolean] (default: true): Whether or not to stretch the menu to occupy the entire container in which it is placed.
axis ['horizontal'|'vertical'] (default: 'horizontal'): The axis on which to render the top level menu.
verticalExpand ['north'|'south'] (default: 'south'): The direction in which to render the submenus that fall on the vertical axis.
horizontalExpand ['east'|'west'] (default: 'east'): The direction in which to render the submenus that fall on the horizontal axis.
expandMenuArrowUrl [uri] (default: 'arrow.gif'): The location of the image to use to indicate that a menu has children.
subMenuWidthCorrection [int] (default: 0): The number of pixels of correction to add to the submenu width.
verticalSubMenuOffsetY [int] (default: 0): The number of pixels of correction to add to the vertical offset of a submenu on the vertical axis.
verticalSubMenuOffsetX [int] (default: 0): The number of pixels of correction to add to the horizontal offset of a submenu on the vertical axis.
horizontalSubMenuOffsetY [int] (default: 0): The number of pixels of correction to add to the vertical offset of a submenu on the horizontal axis.
horizontalSubMenuOffsetX [int] (default: 0): The number of pixels of correction to add to the horizontal offset of a submenu on the horizontal axis.
screenPadding [int] (default: 0): Amount of padding applied to the body element, to avoid having to calculate it.
openMouseoverMenuDelay [ms] (default: 300): The delay for opening the first level submenu upon mouseover. (-1 to disable)
openMousedownMenuDelay [ms] (default: -1): The delay for opening the first level submenu upon mousedown. (-1 to disable)
closeMouseoutMenuDelay [ms] (default: 800): The delay for closing the first level submenu upon mouseout. (-1 to disable)
closeClickMenuDelay [ms] (default: -1): The delay for closing the first level submenu upon click. (-1 to disable)
openMouseoverSubMenuDelay [ms] (default: 0): The delay for opening the second level and descendant submenus upon mouseover. (-1 to disable)
openClickSubMenuDelay [ms] (default: 0): The delay for opening the second level and descendant submenus upon click. (-1 to disable)
closeMouseoutSubMenuDelay [ms] (default: 0): The delay for closing the second level and descendant submenus upon mouseout. (-1 to disable)
closeClickMenuDelay [ms] (default: 0): The delay for closing the second level and descendant submenus upon click. (-1 to disable)
baseZIndex [int] (default: 100): The starting z-index used to keep the vertical position of the menu items above other elements on the page.

Memory Usage and Leaks

Certain browsers, particularly Internet Explorer, can be very problematic when it comes to memory leaks. The use of event handlers and DOM manipulation can led to excessive memory usage if not done properly. Fortunately, DOM Menu takes the appropriate steps to ensure that memory does not leak. It does so by avoiding the use of inner functions and registering an unload event cache to clean out any event handler references left behind when leaving the page. DOM Menu has been checked using the Drip memory leak detector and verified that no memory leaks occur. That being said, DOM Menu does consume a fair amount of memory to render the menus via DOM manipulation.