The function DynarchMenu.setup, called at body.onload, actually accepts the following form:
DynarchMenu.setup(element_id, config);
The config parameter is optional; if present, it must be a JavaScript object containing configuration info. Currently it accepts the following parameters:
(boolean or number) which specifies wether the horizontal menu items will open the submenus at mouseover or on click. If “electric” is true or a number other than zero, then submenus will be opened at mouseover (thus, upon hover) and will automatically close at mouseout, otherwise all the above happens upon click. Default: false.
If a non-zero number is specified, then it configures the submenu hide timeout, in milliseconds. For instance if you specified “500” then submenus will close in 500 milliseconds after the mouse cursor leaves them. If during this timeout the mouse returns in the submenu, then the hiding action will be canceled.
(number) which specifies the timeout, in milliseconds, for opening/closing submenus. The default is “150” and we think it's a sane value. Don't make it too big nor too small, as it can get annoying.
Basically this means that an item which has a submenu will open the submenu after this timeout has elapsed. Also, after leaving an item having a submenu which is visible, that submenu will close after this timeout has elapsed; if, during this time, the cursor returns to the item or to it's submenu, then the submenu will be “reactivated” and its closing will be cancelled.
(boolean) default: false. If this parameter is specified as “true”, then the base menu will appear as a vertical menu, instead of the horizontal bar.
This parameter also implies “electric: true”, unless otherwise specified by the calling script.
(boolean) default: false. When "context: true" is specified, the main menu bar will never appear, and all submenus defined within it can act as context menus for different elements. More details in the context menus sample.
Note that you can setup context menus even without passing this configuration option (but in this case the main menu bar will be visible, like in this very page).
If specified, the given string will be added to the menu's and submenus' CSS class attributes. This is useful for customizing different color themes for different menus within the same page.
(boolean) specifies if the menu should display tooltips. Default: false.
(array or null) default: [2, 2]. If “null” then the popup menus will not display shadows. If an array is passed then it must have 2 elements, integers, and they signify the shadow displacement relative to the popup menu position (i.e. [4, 2] means “show shadows of width 4 and height 2 pixels”).
Of course, you can specify [0, 0] if you want no shadows. But using this instead of null will add a slight performance penalty (it might not be noticeable at all, but we know that it will be there) so if you don't want shadows, better pass null here.
Note: as of version 2.5, the shadows parameter can be a 4 elements array, in which case they will have the following meaning:
[ dx, dy, dw, dh ]
Using the variant above you can specify negative values for dx, dy and get shadows closer to shadows in Mac OSX, i.e. bigger than the popups. Example values:
[-2, -1, 6, 6]
(boolean) default: true, unless the browser is IE 5.0 in which case this will be false. This parameter takes effect only if “shadows” are enabled, and if its value is true then the displayed shadows will be “smooth”, meaning, they will have smooth edges and corners, just like WinXP menus. When false the default shadows are used (a simple background of dark color).
Smooth shadows look better, but requires loading of a (small) image from server. The image will normally be cached, so one should not worry about this.
(boolean) default: false. If true is specified, menu items will blink for a short time when they're clicked, resembling menus found in NeXT interfaces.
Note: as of version 2.5, this parameter can also be specified as a number. If 0, no blinking takes place. If a positive integer, items will blink that many times before the action is triggered. We recommend 3 or 5 if blinking is desired.
(boolean) default: false. If “lazy” is passed true, the menu will use a technique called “lazy initialization” in order to display a long menu instantly.
(boolean) default: false. If you pass “true” to this parameter, the menu will be assigned some special CSS bits that make it more suitable to create a toolbar.
(HTMLElement) default: document.body. You can specify here an element of your choice to contain the submenu elements. This defaults to document.body (by default all popups are created as direct children of the BODY tag). The only reason why you would want to overwrite this is when you have inline HTML containing form fields, so you'll normally want them to appear inside some FORM element. This feature is experimental. You will have problems if the container element that you supply has for instance the style "position: relative", or if any of its parents have "position: relative".
In order to pass something here, you need to retrieve a reference to the element in the DOM tree. For example:
DynarchMenu.setup("menu", { container: document.getElementById("form1") });
and assign id="form1" to your FORM element.
(boolean) default: false. For performance reasons, DynarchMenu doesn't clone the contents of the elements used to initialize the menu—instead it just reuses the same DOM nodes. This means that if you assign an ID to some IMG element used as an icon, for instance, you will later be able to change that icon by looking the element up with document.getElementById. On the downside though, if you want to clone a submenu in multiple menus, icons and HTML-based popups will onlt display correctly in the first instantiation. If that's the case you need to pass "clone: true" to all DynarchMenu.setup calls.
(function). This function handler will be called each time a submenu or a context menu is displayed. Example:
function onPopup(target, item, pos) { alert(this.id); // the ID of the submenu, as assigned to <ul> alert(item.label); // label of the parent item alert(pos.x + "," + pos.y); // requested position of the submenu }
This handler allows you to modify the submenu right before it is displayed, for instance to hide/show certain items, or disable/enable, etc. See an example here.
(object). You can use this parameter to tell DynarchMenu to use 2 frames for the menus. You must pass 2 properties: the name of the “main” frame (where the main menu will appear), and the name of the “popups” frame, where the popup menus will appear.
DynarchMenu.setup("menu", { frames: { main: "top_frame", popups: "bottom_frame" }, clone: true });
As you can see in the above example, we're passing to DynarchMenu.setup the names of the two frames. Then, DynarchMenu will magically know to lookup the "menu" ul in the "top_frame" frame, and will create the menu in such a way that popups will display in "bottom_frame".
An important note is that we need to pass "clone: true", because in cross-frame mode the menu must not destroy the original elements.
Please see the frames sample for more information.
(boolean or object). When you have really long menus and you want they to fit on the screen with scroll arrows, you can pass here true or an object of the following form:
{
step1: 5,
step2: 10,
speed: 30
}
The above are the default values that are used when you pass "true". "step1" is the scrolling step in pixels when the mouse hovers a scroll arrow, "step2" is the step in pixels when the scroll arrow is pressed and "speed" is the timeout in milliseconds between consecutive scroll updates.
Setting a menu that opens submenus on “mouseover” and instantly closes them on “mouseout”:
DynarchMenu.setup("menu", { electric: true });
Setting a menu that opens submenus on “mouseover” and closes them after 250 milliseconds on “mouseout”; additionally, this one displays tooltips.
DynarchMenu.setup("menu", { electric: 250, tooltips: true });