dhtmlxMenu 2.0 Guide

So, in our case the code will look like this:

<script>
var menu = new dhtmlXMenuObject("menuObj");
</script>

It should be noted that with the way of menu creating described above, the system will first clear the menu container (<div>), and then create the menu.

3.1.2 Contextual Menu

The user needs to create an object to which dhtmlxMenu 2.0 will be attached later. In this example the object is a <div> element on page, which is placed in the <body> tag.

<div id="contextArea"></div>

For a contextual menu the user should:

Create a new dhtmlxMenuObject attached to "contextArea";
Set the name of the necessary skin as the second argument for dhtmlXMenuObject (optional; if the name of the skin is not indicated, the default one will be used);
Use renderAsContextMenu() method:

<script>
menu = new dhtmlXMenuObject("contextArea");
menu.renderAsContextMenu();
</script>

It should be noted that with the way of menu creating described above, the system will first clear the menu container (<div>), and then create the contextual menu. To prevent container data from clearing, the user should use the method described in Contextual menu zones section.

3.1.3 Contextual Menu Zones

A contextual menu zone is the area the user needs to click for a contextual menu to appear. The previous snippet shows us initialization of a contextual menu with the predefined contextual zone: when the user indicates contextual zone id while creating a new menu object, it means that this area is set to be a contextual menu zone automatically by script.

In other way, the user can initialize a contextual menu without indicating a contextual zone initially. And use addContextZone() method later, which parameter is id of the object that will act as a contextual zone:

<script>

menu = new dhtmlXMenuObject();

menu.renderAsContextMenu();

menu.addContextZone(contextZoneId);

</script>

A contextual zone can be easily removed with the help of the following method:

<script>
menu.removeContextZone(contextZoneId);
</script>

There is also the possibility to check whether an object is a contextual menu zone:

<script>
var isZone = menu.isContextZone(objectId); // returns true|false
</script>

3.1.4 Initialization Recommendation

The recommended way of menu initialization is the following:

<html>
<head>
<script>
var menu;
function doOnLoad() {
menu = new dhtmlXMenuObject("parentId");
}
</script>
...
</head>
<body onload="doOnLoad();">
<div id="parentId"></div>
...
</body>
</html>

3.2 Setting Image Path

Methods setImagePath() and setIconsPath() should be used to set the full paths to the directories, where menu image files are located. The following code strings should be placed before any of data loading methods:

setImagePath() - in this method the user should set path to 'codebase/imgs/' directory, where menu skin images are stored. Skin images are grouped by skin name in the directories inside this imgs one. The user shouldn't indicate a certain skin images directory inside imgs one in setImagePath() method, as the system will do it itself;
setIconsPath() - by means of this method the user is able to set path to the directory, where menu icons images are stored.

<script>
menu.setImagePath("[full path to this directory]/codebase/imgs/");
menu.setIconsPath("[full path to icons image files directory]");
</script>

3.3 Setting Skin

We recommend users to choose and set menu skin before data loading. If the user wants to set a menu skin or change the current/default menu skin to, let's say, clear_blue one, he should take the following steps:

Set/Change the link to the required skin by the chosen style menu CSS file in the <head> tag of html:

<head>
<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxmenu_clear_blue.css">
</head>

Write the name of the skin as the second parameter for dhtmlXMenuObject:

<script>
var menu = new dhtmlXMenuObject("menuObj", "clear_blue");
//or
menu = new dhtmlXMenuObject("contextArea", "clear_blue");
menu.renderAsContextMenu();
</script>

Note: there's no need to write the name of the skin as the second argument for the default menu skin (dhx_blue).

3.3.1 Available Skins

The following predefined skins are available in dhtmlxMenu 2.0:

dhx_blue (the default one)

dhx_black

aqua_dark

aqua_orange

aqua_sky

clear_blue

clear_green

clear_silver

modern_black

modern_blue

modern_red

standard

It should be noted that some skins can be available as addons, and they are not included into the package. But they can be downloaded from the site.

3.4 Data Loading

The next step of initialization of dhtmlxMenu component is Data Loading. The user can choose one of 5 data loading possibilities:

From external XML file (with Ajax);
From XML string;
From HTML object;
From Script;
Dynamical loading (with Ajax).

3.4.1 Data Loading from XML File

loadXML() method loads menu data from an XML file. When the data is loaded into the object, a user-defined handler is called (onLoadFunction), if it was indicated by the user. All the data is loaded at once:

<script>
menu.loadXML("[path to this file]/file.xml", onLoadFunction);
onLoadFunction = function(){
// will be called if specified
}
</script>

The first parameter of loadXML() method is the path to the XML file, while the second parameter is an optional user-defined handler.

See here for XML Format Template.

3.4.2 Data Loading from XML String

loadXMLString() method loads menu data from the XML string. When the data is loaded into the object, a user-defined handler is called (onLoadFunction).
All the data is loaded at once:

<script>
menu.loadXMLString("<menu><item....>", onLoadFunction);
onLoadFunction = function(){
// will be called if specified
}
</script>

The first parameter for loadXMLString() method is the XML string from our html file, while the second parameter is an optional user-defined handler.

See here for XML Format Template.

3.4.3 Data Loading from HTML Object

loadFromHTML() method loads content from HTML object to the menu. First, the user should create this HTML object. For example:

<body>
    <div id="menuData" style="display: none;">
        <div id="m1" text="File"> // the first top menu item
	     <div id="m11" text="New" <hotkey>Ctrl+N</hotkey></div>// the first child item
	     <div id="ms1" type="separator"></div> // a separator
	     <div id="m12" text="Open"><hotkey>Ctrl+O</hotkey></div> // the second child item
        </div>
    </div>
</body>

Then loadFromHTML() should be applied with the following parameters:

objectId - id of data container ("menuData" in our case);
clear - true|false, removes HTML object after data was loaded, if this parameter is set to true;
onLoadFunction - a user-defined handler, which will be called, when the data is loaded (optional).

<script>
menu.loadFromHTML(objectId, clear, function(){});
</script>

So, in our example this code will look like this (without any user-defined handler):

<script>

menu.loadFromHTML("menuData", true);

</script>

3.4.4 Data Loading from Script

Loading data from script means that the user should write a special method for adding every menu item. In our example to add a new sibling item, a child item, a new separator and set a hotkey, we should write the following:

<script>

menu.addNewSibling(null, "file", "File", false); // adding the first item to the menu, "nextToId" param is null

menu.addNewChild("file", 0, "file_new", "New", false); // adding a new child item

menu.setHotKey("file_new", "Ctrl+N"); // setting a hotkey to a button

menu.addNewSeparator("file_new"); // adding a separator

</script>

Refer to the section Items Settings Manipulations to learn about the methods used in the above mentioned snippet.

3.4.5 Dynamical Loading

Dynamical loading means loading data on request. The user can split data into parts by levels and decrease loading time this way.
enableDynamicLoading() method should be used with the following parameters:

url - server-side script, transmitted parameters are action (set to "loadMenu") and "parentId" (will pass id of the selected complex item for loading its child items into sub-level polygon);
icon - true|false, replaces item's arrow icon while loading data with a "loading" icon to indicate the process of data loading.

<script>
menu.enableDynamicLoading(url, icon);
</script>

So, in our case we should write this line of code (without an icon):

<script>

menu.enableDynamicLoading("[script url]");

</script>

3.4.6 onLoadFunction()

onLoadFunction() is a user-defined handler that is called after the data was loaded into the object :

<script>

menu.loadXML("file.xml", function(){

alert(the data is loaded); // will be invoked after XML file was loaded (after onXLE, if specified)

});

</script>

3.5 Global Parameters

3.5.1 Setting Menu Mode

The user can choose what mode to set for the top-level items of the new menu object. There are two modes available:

win - In this mode the user should click any complex item in the top-level polygon to expand it. The item will be expanded until the user clicks any top-level open item in the menu, or any other place on the page;
web (the default one) - In this mode items in the top-level polygon are expanded immediately, when the user hovers the mouse over any of them. When the mouse is moved outside the menu area, the open item collapses.

setOpenMode() method is used to set the menu mode:

<script>
menu.setOpenMode("win");
</script>

Note: setting of the web mode from the script is not required because it's already set by default.

3.5.2 Setting Timeout for Web Mode

When the Menu is set to the web mode, there is an opportunity to set the period of time, during which the menu will be held expanded, even if the user moves the mouse outside the menu area. By default this time is set to 400 msec.
To set this time period the user should use setWebModeTimeout() method:

<script>
menu.setWebModeTimeout(time);
</script>

3.5.3 Setting Visible Area

setVisibleArea() method sets the rectangle area in which sub-level polygon items will be able to appear. If this area is not set, sub-level polygon items can occupy any available visible space.
The parameters are:

x1, x2 - int, leftmost and rightmost coordinates by x axis;
y1, y2 - int, topmost and bottommost coordinates by y axis.

<script>
menu.setVisibleArea(x1,x2,y1,y2);
</script>

Usage example

When using dhtmlxGrid with Contextual menu you often meet some inconveniences. For example you need to read contextual menu of the record placed at the bottom of the grid, but the appearing of browser's scrollbars will disturb the impementation of this task. To avoid scrolling appearence set visible area and define menu position. (set grid's coordinates to acheive this).

3.5.4 Hiding Open Polygons

There is the possibility to hide all open polygons in a menu from script with the help of hide() method:

<script>
menu.hide();
</script>

3.5.5 Setting Overflow Height

By default there is no limits on the number of visible menu items in any sub-level polygon. However, the user can limit the number of visible items in a sub-level polygon using setOverflowHeight() method.

This method adds scroll-arrows to a sub-level polygon, if there are more visible menu items than it is allowed by setOverflowHeight() method. The following example shows how this method should be used as a function with any of data loading methods:

<script>
menu.loadXML("dhtmlxMenu/codebase/dhtmlxmenu.xml", function () {
menu.setOverflowHeight(4);
});
</script>

4. Items Settings Manipulations

4.1 First Menu Item Creation

The first menu item in the usual menu can be created with the help of addNewSibling() method. The parameters here are as follows:

nextToId - null should be indicated;
....

Other parameters of addNewSibling() method can be found here.

<script>
...

menu.addNewSibling(null, ...);
</script>

The first menu item in the contextual menu can be created with the help of addNewChild() method. The parameters here are as follows:

parentId - menu.topId should be indicated where menu is an instance of the menu object;
...

Other parameters of addNewChild() method can be found here.

<script>
...
menu.renderAsContextMenu();
menu.addNewChild(menu.topId, ...);
</script>

4.2 Sibling Item Creation

The user can create a new sibling item in any polygon. To do this addNewSibling() method should be used. The parameters here are as follows:

nextToId - id of the element after which the new item will be inserted.
itemId - id of the new sibling item;
itemText - the label of the new sibling item;
disabled - true|false, if this new sibling item is disabled or not;
img - path to image for the enabled state of the new sibling item;
imgDis - path to image for the disabled state of the new sibling item.

The new sibling item will be inserted right after the item chosen as "nextToId" one.

<script>
menu.addNewSibling(nextToId, ItemId, itemText, disabled, img,imgDis);
</script>

4.3 Child Item Creation

There is the possibility to create a child item for any item in the menu. The child item will be located in a sub-level polygon and won't be visible until its parent item is hovered over.
addNewChild() method should be called and the following parameters are to be passed:

parentId - id of the element that will contain the newly created item in its sub-level polygon;
position - position/order of the new child item in the polygon among other child items, whether it comes first, second, etc. (starts with 0);
itemId - id of the new child item;
itemText - the label of the new child item;
disabled - true|false, whether this new child item is disabled or not;
img - path to image for the enabled state of the new child item;
imgDis - path to image for the disabled state of the new child item.

<script>

menu.addNewChild(parentId, position, itemId, itemText, disabled, img, imgDis);

</script>

4.4 New Separator Creation

Separators can be created with the help of addNewSeparator() method. A separator provides kind of a logical grouping of menu items.

addNewSeparator() method has the following parameters:

nextToId - id of the element after which the new separator will be inserted;
itemId - id of the new separator.

<script>
menu.addNewSeparator(nextToId, itemId);
</script>

4.5 Removing Item

The user can choose to remove any item from a menu. The item will be removed with all its sub-items/sub-polygons.
An item can be removed in the following way:

<script>
menu.removeItem(Id);
</script>

4.6 Getting Parent Id

There is the possibility to get parent id of any menu item. This can be done by means of getParentId() method:

<script>
var parentId = menu.getParentId(id);
</script>

4.7 Enabling/Disabling Item

Any menu item can be enabled/disabled by user:

<script>
menu.setItemEnabled(id);
menu.setItemDisabled(id);
</script>

Also the user has the possibility to check whether an item is enabled. This can be done by calling the following method:

<script>
var isEnabled = menu.isItemEnabled(id); // returns true|false
</script>

The user should pass id of the item that will be checked. The method returns true if the item is enabled.

4.8 Showing/Hiding Item

Any item in a menu can be shown/hidden. To do this the user should pass this item's id to the following methods:

<script>
menu.showItem(id);
menu.hideItem(id);
</script>

The user has the possibility to check whether an item is hidden. The method returns true if the item is hidden:

<script>
var isHidden = menu.isItemHidden(id);
</script>

4.9 Setting Item's Text

The user can set text for any menu item. This item's id and text are passed as parameters to the following method:

<script>
menu.setItemText(id, text);
</script>

The user can get item's text using getItemText() method. The method returns the current text of the item:

<script>
var text = menu.getItemText(id); // returns item's text
</script>

4.10 Setting Item's Positing

Item's position in the polygon can be set applying the method setItemPosition() and passing item's id and item's position number (starting with 0) as parameters:

<script>
menu.setItemPosition(id,pos);
</script>

There is the possibility to get items' position. The method returns item's position number:

<script>
var pos = menu.getItemPosition(id); // returns item's position
</script>

4.11 Setting User Data

The user has the possibility to set, store, and pass values set for a certain menu item. One menu item can have several different user data stored in it.
User data can be set to any menu item. The user just needs to pass this item's id, name of the data and its value to setUserData() method:

<script>
menu.setUserData(id, name, value);
</script>

An easy way to get user data is to use getUserData() method passing the item's id and data name:

<script>
var value = menu.getUserData(id, name);
</script>

4.12 Setting Item's Image

Any item in a menu can have its own image displayed in the left part of item display area. setItemImage() method allows the user to set image to an item by passing the following parameters:

id - id of the item to which the image will be set;
img - path to the image for the enabled state of the item;
imgDis - path to the image for the disabled state of the item.

<script>
menu.setItemImage(id,img,imgDis);
</script>

getItemImage() method gets current item images for enabled and disabled states and returns array(img, imgDis) that will contain URLs to images:

<script>
var imgs = menu.getItemImage(id); // returns array
</script>

Item's image can be easily removed/cleared by means of clearItemImage() method to which the user should pass item's id:

</script>
menu.clearItemImage(id);
</script>

4.13 Setting Item's Tooltip

The user can specify the supplementary information regarding the item - tooltip. setTooltip() method takes the following parameters:

id - item id;
tip - this parameter sets the text that appears when user hovers the mouse over the item.

<script>
menu.setTooltip(id,tip);
</script>

The following method can return current item's tooltip text:

<script>
var tip = menu.getTooltip(id);
</script>

4.14 Setting Item's Hotkey

Hotkey is a short-cut to a menu option. In our menu it's just a label (text) written in the item display area. A hotkey can be set to any menu item by calling setHotKey() method and passing item's id and setting hotkey label:

<script>
menu.setHotKey(id, hkey);
</script>

getHotKey() method returns current item's hotkey text:

<script>
var hkey = menu.getHotKey(id); // returns hotkey text
</script>

4.15 Checkbox Creation

An item of this type has a small, square box (in the left part of item display area) in addition to item's title. Any other icons can't be added to this type of items.
This item can be created by calling addCheckBox() method that takes the following parameters:

mode - sibling|child, determines whether the checkbox is a sibling or a child;
nextoId - id of the element,after which the new checkbox will be inserted as a sibling (parentId for a child);
pos - item's position in the child mode (null for sibling);
itemId - id of the new checkbox;
itemText - the text of the new checkbox;
state- true|false, true and false mean "checked" and "unchecked" respectively;
disabled- true|false, true and false mean "disabled" and "enabled" respectively.

<script>
menu.addCheckbox(mode, nextToId, pos, itemId, itemText, state, disabled);
</script>

New state (checked/unchecked) of the checkbox can be set by the following method:

<script>
menu.setCheckboxState(id,state);
</script>

A simple way to get the current state of a checkbox is presented below:

<script>
var state = menu.getCheckboxState(id); // returns true|false
</script>

4.16 Radio Button Creation

Item of this type has a small selectable circle (in the left part of item display area) in addition to item's title. Any other icons can't be added to this type of items.
This item can be created by calling addRadioButton() method that takes the following parameters:

mode - sibling|child, determines whether the radio button is a sibling or a child;
nextToId - id of the element, after which the new radio button will be inserted as a sibling (parentId for a child);
pos - item's position in the child mode (null for sibling);
itemId - id of the new radio button;
itemText - the text of the new radio button;
group - name of the radio group;
state- true|false, true and false mean "checked" and "unchecked" respectively;
disabled- true|false, true and false mean "disabled" and "enabled" respectively.

<script>
menu.addRadioButton(mode, nextToId, pos, itemId, itemText, group, state, disabled);
</script>

Any unchecked radio button can be made checked while currently checked radio button automatically changes its state to unchecked:

<script>
menu.setRadioChecked(id,state);
</script>

An easy way to get id of the current checked radio button in a radio group is presented below:

<script>
var idChecked = menu.getRadioChecked(group);
</script>

4.17 Iterator

Method forEachItem() calls a user-defined function for every existing item in the menu passing item's id into it. Using iterator can be very useful in case the user wants all the items to be subjects for the same changes.

<script>
menu.forEachItem(function(itemId){});
</script>

5. Event Handling

5.1 Available Events

There are the following available events in dhtmlxMenu:

onClick - occurs when the user clicks the left mouse button on an enabled, not complex menu item;
onTouch - occurs when the user first hovers over any menu item by a mouse cursor (is not applicable for the contextual menu);
onCheckboxClick - occurs when the user clicks any checkbox item;
onRadioClick - occurs when the user clicks any radio item;
onXLS - occurs before data loading from XML has started;
onXLE - occurs after data loading from XML has finished;
onBeforeContextMenu - occurs before the moment when a contextual menu appears (can be used only for a contextual menu);
onAfterContextMenu - occurs after the moment when a contextual menu appears (can be used only for a contextual menu).

5.2 Attaching Event Handler

The user can add any user-defined handler to available events.

To do this, he can use attachEvent() method with the following parameters:

evName - name of the event;
evHandler - user-defined event handler.

<script>

attachEvent(evName, evHandler);

</script>

Note: the names of the events are case-insensitive.

5.3 onClick and onTouch Events

These events call user-defined handlers (if there are any) and pass the following parameters:

id - id of the clicked/hovered menu item;
zoneId (only for onClick event in case of a Contextual Menu) - id of the contextual menu zone;
casState(only for onClick event) - whether the key "Ctrl", "Alt", or "Shift" was pressed with click or not.

dhtmlxMenu 2.0 Guide and Code Samples