User's Manual Revision: March 25, 2009
An advanced, cross-browser, simple-to-use and accessible list-based DHTML Menu / JavaScript Menu
©2009 Vadikom - Bulgarian company settled in Plovdiv
This is a quite detailed manual and you most probably do not need to read everything. A good approach is to initially read carefully just the next couple of sections ("2 Glossary" and "3 Basic installation & configuration steps") before setting up the script on your pages and use all other parts of the manual as a reference - only when you need something. Note that everything you may need to set in the configuration file (c_config.js) is also well commented.
You will meet the following terms on many places in this manual. Please take a look at these short descriptions so that you know what is referred to when these terms are used.
Below are described the basic steps to setup the SmartMenus 6 script.
First you need to create the menu definition unordered list structure on your page. Please take a look at the source of the example page "example.html" to see how a valid structure looks like. Note that you have to use A elements inside all LI tags.
If you want to leave any menu item without link, just don't set the A element's href attribute and set its class attribute to "NOLINK" - e.g.:
<li><a class="NOLINK">text</a>...
You can also forbid the rollover effect for any menu item if you set the A element's class attribute to "NOROLL" - e.g.:
<li><a class="NOROLL" href="URL">text</a>...
Combination is also possible - e.g.:
<li><a class="NOLINK NOROLL">text</a>...
After you have created the unordered list structure set the id and class attributes of the root UL element to a desired value (it is better to use rather short values). Also if you plan to use separators between the menu items of your main menu(s) (not the sub menus), set the "NOSEPARATOR" class to the last LI element of the root UL element - e.g.:
<li class="NOSEPARATOR"><a href="URL">text</a>...
Please leave at least one new line or white space symbol after the closing </ul> tag of the root UL element of the menu tree. This will allow the browsers to initialize the menu tree as soon as it is loaded and not wait for the page load event to start the initialization.
Make sure you have linked the SmartMenus config (c_config.js) and script core (c_smartmenus.js) files in the head section of your page (preferably just before the closing </head> tag). Only in case you are using the "onload" attribute of the BODY element, you need to put the links to "c_config.js" and "c_smartmenus.js" after the opening <body> tag in the source.
The SmartMenus 6 configuration file (c_config.js) has 3 sections.
In the first section there are some variables controlling global functions of the script (like show/hide timeouts, highlight behavior etc.). There are 3 variables that may be a bit confusing for you (c_findCURRENT, c_findCURRENTTree and c_overlapControlsInIE) - if you like, you can learn what they can be used for in "5.4 About the c_findCURRENT and c_findCURRENTTree..." and "5.5 About the c_overlapControlsInIE...".
In the second section you will find some JS arrays that represent the CSS classes to be used for the menus. Here is where you can tweak the style of your menu tree(s).
Please note that the menu box styles are not applied to the main menus, they are only applied to the sub menus. This is due to some browser bugs and cross-browser inconsistencies (like the box-model differences). You can try setting the desired properties (e.g. border, padding, background) to the container of your main menu instead.
You can add new CSS classes if you need - just copy/paste one of the already defined. The CSS classes are assigned globally to the specific menu tree(s) in the third section of the configuration file "MENU TREE FEATURES". If you like, you can also set a custom class to any sub menu - please take a look at the "4.3 Setting custom style (CSS class) for any sub menu" howto if you would like to learn how you can do this.
The third section is where you can set the specific features of your main menu(s) and their sub menus. Here you can set their position, item's arrangement, CSS classes etc. One thing deserves special attention in this section - make sure the CSS class you set for your main menu(s) is the same as the one you have set to the root UL element of your menu tree(s) in the page source.
The configuration file includes many useful comments so, hopefully, you should not have problems with it.
Q: What is this and why you may want to use it?
A: The core CSS for your main menu(s) is generated from the settings in the configuration file (c_config.js) and is the minimum required CSS code to make the main menu(s) look the same in all modern browsers. When included on the page this CSS code will ensure that your main menu(s) will remain styled for the users that have JavaScript support disabled in their browsers. If you do not include this CSS code on your page, your menu tree(s) will appear completely unstyled (as an unstyled list) for the users that have JavaScript support disabled in their browsers.
When you have finished tweaking the appearence of your menu tree(s), use the button below to display the core CSS. Please note that the file of the manual (manual.html) must be placed in the same directory as your configuration file (c_config.js) and the SmartMenus script core file (c_smartmenus.js) in order this button to function correctly.
Once the core CSS is generated just put it in an external .css file and link it in the head section of your page - just make sure it is placed before the link to the SmartMenus script core file (c_smartmenus.js) in the page source.
Normally you would probably need just one menu tree (i.e. one main menu with sub menus) on your pages. But you are actually not limited to just one - you can have as many menu trees as you like because the SmartMenus script supports adding unlimited number of menu trees on the same page.
If you would like to add a new menu tree, you will just need to copy/paste one of the config blocks from the third section "MENU TREE FEATURES" of the configuration file (c_config.js) and configure it for another menu tree. For instance, let's say the UL element that you want to transform into your new menu tree has the "MyMenu" id - e.g.:
<ul id="MyMenu" class="someClass">
...
</ul>
this means that you should simply update the config block you copied for your new menu tree like this:
c_menus['MyMenu']=[ // the UL element with id="MyMenu"
[
// MAIN-MENU FEATURES
...
and then configure the rest of the config block as you like.
Please note that you are allowed to include in your configuration file (c_config.js) config blocks for menu trees that don't exist on all of your pages. If a given menu tree is defined in the configuration file but its UL element is not available on the current page, the script will simply neglect the menu tree definition in the configuration file and will not produce a JavaScript error.
Removing a menu tree is as simple as deleting its config block from the third section "MENU TREE FEATURES" of the configuration file (c_config.js).
The CSS classes that can be used for the menu tree(s) are defined in section 2 of the configuration file (c_config.js). In the example found in the SmartMenus 6 download file there are just 2 style classes defined by default ("MM" is used for the main menu and "SM" is used for the sub menus). The CSS classes are assigned globally to the specific menu tree(s) in the third section of the configuration file "MENU TREE FEATURES".
However, you are not limited to just these global style classes for all menus. If you like, you can set custom style class for any sub menu. For the purpose, you will first need to define a new class in the configuration file - just copy/paste one of the already defined and update it as you prefer. Let's say you have defined the new "MyClass" style class - e.g.:
c_styles['MyClass']=[
[
// MENU BOX STYLE
...
You can assign this new class to any sub menu you like by setting the class attribute to the UL element that represents the sub menu:
<ul class="MyClass"...
Please note that this new custom style class will also be inherited by all sub menus of the menu it has been applied to.
Regardless of the global setting for width of the sub menus you have in the configuration file (c_config.js) - e.g.:
],[
// SUB-MENUS FEATURES
5, // X SubMenuOffset (pixels)
1, // Y SubMenuOffset
'auto', // Width ('auto',values in CSS valid units - px,em,ex)
...
you can still set custom width for any sub menu by using the "width" CSS property for the UL element that represents the sub menu:
<ul style="width:10em;"...
If you would like to customize any menu item (e.g. set it a different background, color, padding etc.), you can do this by setting an id to the item's A element - e.g.:
<li><a id="myItem" href="URL">text</a>...
and using some additional CSS - for the item's normal state:
#myItem, #myItem:visited {
/* any declaration(s) here */
}
If you would like to set different style for the visited state, you can, of course, create separate rules for #myItem and #myItem:visited. And for the item's hover/focus state:
#myItem:hover, #myItem:focus, #myItem:active, #myItem.XXO, #myItem.XXO:visited {
/* any declaration(s) here */
}
The interesting part here is the "XXO" class. This is the class that the SmartMenus script uses for highlighting the items when c_keepHighlighted is set to true. The name of this class is generated from the name of the style class that is used for the menu that contains the item we are customizing and the letter "O" suffix. This means that if you are customizing an item from the main menu, you should replace "XXO" with "MMO" and if you are customizing an item from a sub menu, you should replace "XXO" with "SMO" as the classes for the main menu and the sub menus are named "MM" and "SM" by default. If you have changed the default names of the menu classes or you are using a custom class for the menu that contains the item you are customizing, you should change "XXO" accordingly.
If you would like to add an icon to a single menu item, you can do this by customizing the menu item (please take a look at the previous howto "4.5 Customizing any menu item") - setting it a custom background-image and some padding to free space for the icon. Just set an id to the item's A element - e.g.:
<li><a id="myItem" href="URL">text</a>...
and use some additional CSS:
#myItem, #myItem:visited {
padding-left:24px;
background-image:url(source_of_the_icon_image);
background-repeat:no-repeat;
background-position:4px 50%;
}
If you like, you can also set a rollover for the icon:
#myItem:hover, #myItem:focus, #myItem:active, #myItem.XXO, #myItem.XXO:visited {
background-image:url(rollover_source_of_the_icon_image);
}
The interesting part here is the "XXO" class. You can find a description about it in the previous howto above "4.5 Customizing any menu item".
When you use rollover for the icon, you may want to preload the image for the "on" state of the icon to make the rollover effect fast and smooth even the first time. You can use some JavaScript like this:
img1 = new Image;
img1.src = "rollover_source_of_the_icon_image";
If you want to add icons to more than one menu item, it is more practical to create a CSS class for the purpose to reduce the size of the CSS code needed. For instance, like this:
.hasIcon {
padding-left:24px !important;
background-repeat:no-repeat;
background-position:4px 50%;
}
The "!important" declaration is used for padding-left to make it take precedence over the default padding for the items. Then you need to set it to the menu items that you want to have icons:
<li><a id="myItem1" class="hasIcon" href="URL">text</a>...
<li><a id="myItem2" class="hasIcon" href="URL">text</a>...
After that you just need to set different background-image for the different items:
#myItem1, #myItem1:visited {
background-image:url(source_of_the_icon_image_for_myItem1);
}
#myItem2, #myItem2:visited {
background-image:url(source_of_the_icon_image_for_myItem2);
}
Adding a rollover for the icons can be done just like in the example above for adding an icon to a single menu item.
You can easily add tooltips to any menu item by setting the A element's title attribute - e.g.:
<li><a title="Tooltip for this menu item" href="URL">text</a>...
Please take a look at this example/tutorial. It includes detailed step-by-step instructions for building a main menu from images with rollovers instead of text.
By default the items of any horizontal main menu have auto width/height. The easiest and most cross-browser compatible way of setting custom width/height for the items of a horizontal main menu is by using additional SPAN element in the main menu items and then setting explicit dimensions to that SPAN element instead of directly to the menu item's A element. For example:
<ul id="Menu1" class="MM">
<li><a id="home" href="URL"><span class="item">Home</span></a></li>
<li><a id="about" href="URL"><span class="item">About</span></a></li>
...
If you want to set custom dimensions to the specific items, you can also set ids to the A elements of these items (e.g. "home" and "about" in the example above).
Then you can apply the custom dimensions to the main menu items with some CSS code like this:
/* for all items */
span.item {
display:block;
width:80px;
height:20px;
}
/* for the specific items */
#home .item {
width:100px;
}
#about .item {
width:110px;
}
/* and so on... */
Please just note that items that have sub menus are applied a bit additional padding to make room for the sub menu indicator image. So you should be aware of this when you set their custom width. This is relevant, of course, if you have the sub menu indicator images activated for your main menu.
By using additional SPAN element in the main menu items and not applying the dimensions directly to the A elements you don't have to worry about cross-browser incompatibilities caused by the different box models in some old browsers. So this is probably the neatest solution.
If you would like to embed a main menu (horizontal or vertical) in a table cell or a DIV element on your page, you just need to set its Position to 'relative' in the third section "MENU TREE FEATURES" of the configuration file (c_config.js) - e.g.:
'relative', // Position ('relative','absolute','fixed')
'0', // X Position (values in CSS valid units- px,em,ex)
'0', // Y Position (values in CSS valid units- px,em,ex)
When you set the above properties for a given main menu, it will be positioned naturally inside its parent element in the page source (no matter whether it is a table cell or a DIV element). You can, of course, still define some offsets from its natural position by using the X Position and Y Position properties if you need.
Only in case you would like to embed a horizontal main menu in a DIV element (not a table cell) on your page, please also take look at the "6.1 For relatively positioned horizontal main menus clear the root UL element" section of the manual.
Note: For live downloadable main menu positioning examples/templates please take a look at the Online Samples section of the SmartMenus site.
Changing the following settings for any menu tree in the configuration file (c_config.js):
false, // RightToLeft display of the sub menus
false, // BottomToTop display of the sub menus
would not only change the direction at which the sub menus pop up but would also change the alignment of the main menu. This means that, for instance, if you use absolute or fixed positioning for any main menu, changing any of these settings may allow you to position the main menu against the right/bottom edges of the window instead of the left/top edges. But this works for relatively positioned menus too. You can, of course, still use the X Position and Y Position settings to specify offsets.
There is one exception though - you cannot right-align a horizontal main menu. This is because the items of a horizontal main menu are left-floated and there is no way to make them align to the right automatically. You can manually achieve right alignment for a horizontal main menu by setting a X Position value that will produce an appropriate left offset for the main menu and will shift it to the right - e.g.:
'300px', // X Position (values in CSS valid units- px,em,ex)
Note: For live downloadable main menu positioning examples/templates please take a look at the Online Samples section of the SmartMenus site.
To use the script with RTL text, you just need to set the following variable in the first section of the configuration file "GLOBAL SETTINGS":
c_rightToLeft=true;
This will tell the script to take care of everything - like right-aligning your main menu(s), making the sub menus pop up from right to the left (instead of the normal left-to-right) and, of course, setting "rtl" direction for the text in the menu items. Please note that this variable is applied globally and will change the direction for all menu trees you might use on the page.
RTL text is supported in SmartMenus 6 in all browsers that support RTL text.
There is just one small difference in the script configuration when using RTL text - if you have a horizontal main menu and use separators between the main menu items, you do not have to add the "NOSEPARATOR" class to the last LI element of the root UL element but you have to add it to the first LI element - e.g.:
<ul id="MyMenu" class="someClass">
<li class="NOSEPARATOR"><a href="URL">text</a>...
...
</ul>
This is needed because the items of a horizontal main menu when using RTL text are right-floated (instead of left-floated) and their order is reversed visually.
Note: If you would like, you can also take a look at this live example in the Online Samples section of the SmartMenus site.
Fixed positioning is well supported in most modern browsers. This means that the following setting for any menu tree:
'fixed', // Position ('relative','absolute','fixed')
will work in most browsers. However, there are some notable exceptions which include IE prior to version 7 on all platforms, browsers powered by Gecko prior to 20030312 (Mozilla<1.3) and iCab 3. In these browsers any menu tree that has "fixed" position set will appear as absolute-positioned by default.
If you would like to make these browsers emulate fixed positioning for any menu tree, you can use a small add-on script for SmartMenus 6. Please take a look at the following online sample:
Please note that the menu box styles are not applied to the main menus, they are only applied to the sub menus. This is due to some browser bugs and cross-browser inconsistencies (like the box-model differences). You can try setting the desired properties (e.g. border, padding, background) to the container of your main menu instead.
SmartMenus 6 includes few features that particularly affect the performance of the script. If you are not happy with the script's speed, you may consider tweaking the settings that control these features to improve the performance.
When activated this feature affects the initial load speed. However, it is pretty good even on pages with really many menus/items so you probably don't need to worry much about it.
This feature may also affect seriously the runtime speed (i.e. opening the sub menus) if configured in a particular way and if you have menus with many arrow images (i.e. with many sub menus). The runtime performance of the script is seriously affected particularly when SubMenuImageVAlign is set to 'middle' in the style arrays in "c_config.js" - i.e.:
'middle', // SubMenuImageVAlign ('pixels from item top','middle')
Simply setting this to a pixel value:
'7', // SubMenuImageVAlign ('pixels from item top','middle')
will significantly improve the runtime speed of the script when sub menu indicator images are used. You can, of course, adjust the value so that the arrow image would appear vertically centered on most menu items. It will not be centered only on items that have 2 or more lines of text (but this is not a big issue and is even actually how the menus function in most Operating Systems).
If you are not happy with the script's speed as a whole when this feature is activated, you can disable it completely (although this is not recommended) by setting the following in the style arrays in "c_config.js":
false, // UseSubMenuImage (true,false)
When the width for the sub menus is set to 'auto' (which is the default setting in "c_config.js" as it is appropriate in most cases) sub menus that have pretty many items (e.g. 15+) will open with a notable delay.
To avoid this delay for any particular sub menu with many items you can set it a fixed width by following the instructions in the "4.4 Setting custom width for any sub menu" howto.
You may also prefer to set global fixed width for all sub menus in the MENU TREE FEATURES section of the configuration file - e.g.:
'15em', // Width ('auto',values in CSS valid units - px,em,ex)
Please note that even when you set global fixed width for all sub menus, you can still set custom width for any sub menu by following the instructions in the mentioned howto above.
The c_overlapControlsInIE variable controls a special feature of the SmartMenus script (to learn more about this feature you can take a look at the "5.5 About the c_overlapControlsInIE variable in c_config.js" section of this manual). When this feature is activated (it is by default) the runtime speed of the script might be affected on specific very large/complex pages in IE/Windows (the sub menus might start to open with a notable delay of a few seconds). In such case, the only solution would be to turn off this feature by setting the c_overlapControlsInIE variable to false.
"CURRENT" is a special style class that can be used to highlight the item that links to the current location. The script can be configured to find that item automatically (if c_findCURRENT is set to true) or you can manually set the class to any menu item - e.g.:
<li><a class="CURRENT" href="URL">text</a>...
If c_findCURRENT is set to true, a special function will find the item that links to the current location of the window and will automatically apply it the "CURRENT" style class. The c_findCURRENTTree variable controls whether the parent items of the menu that contains the "CURRENT item" should also be applied the "CURRENT" style.
This variable controls a special feature of the SmartMenus script that solves a common problem in IE5/6 on Windows - the SELECT boxes in IE/Windows are special OS controls and DHTML layers cannot be displayed over them. This means that if any menu is to be displayed on a position where a SELECT box is placed, it will be partially hidden beneath the SELECT box.
To make sure this doesn't happen SmartMenus 6 relies on a couple of workarounds. In IE5.5+ the menus will simply appear on top of the SELECT boxes thanks to a built-in fix for the issue. However, in IE5.0x this is not possible and a function will hide all SELECT boxes found on the page when a menu is shown and will show the SELECT boxes again when the menu is hidden.
The following is only needed if you are using a CSS-based layout - you do not need to follow these instructions if you have your horizontal main menu embedded in a table cell.
The menu items (the LI elements) of a horizontal main menu are floated. This means that if you have a horizontal relatively positioned main menu (i.e. that has Position set to 'relative' in its menu tree features array in "c_config.js"), you will have to clear the root UL element so that the main menu box takes its place correctly. You can do this by putting your root UL element inside a DIV element with the "clearFix" class set - e.g.:
<div class="clearFix">
<ul id="Menu1" class="MM">
...
</ul>
</div>
and using the following CSS:
.clearFix:after { /* for modern browsers */
content:".";
display:block;
height:0;
clear:both;
visibility:hidden;
overflow:hidden;
}
.clearFix { /* for IE7/Win */
min-height:1px;
}
* html .clearFix { /* for IE5-6/Win */
height:1px;
}
* html>body .clearFix { /* for IE5/Mac */
height:auto;
display:inline-block;
}
The above CSS code is a slightly modified version of the great technique for clearing floats without structural markup published on Position Is Everything and originally developed by Tony Aslett, of csscreator.com.
If you are using the "onload" attribute of the BODY element for some handler, it will overwrite the SmartMenus 6 onload event handler, which is crucial for some browsers.
An easy solution for this issue is to place the links to the SmartMenus 6 script files (c_config.js and c_smartmenus.js) after the opening <body> tag instead of in the head section of the page. This should solve the problem and will not harm any onload event handlers you currently use, as the SmartMenus script registers its onload event handler by preserving any previous existing event handlers.
Although it's not very likely to happen, if you have global CSS rules defined for any of the UL, LI and A elements in the stylesheets on your pages, you may have some troubles with the style of the menus due to possible style conflicts. Most probably, this may happen with the UL and LI elements - e.g.:
ul {
...
}
To prevent such CSS conflict, instead of using global style rules for these elements, you may use style classes - e.g.:
ul.classname {
...
}
Another possible solution is to narrow down your global rules to a container element on your page that does not contain your menu tree(s) - e.g.:
#containerID ul {
...
}
If the menus are displayed beneath Flash movies on your pages, you will have to add the following parameter inside the Flash movie <object> tag:
<param name="wmode" value="opaque" />
and also add the following attribute to the Flash movie <embed> tag:
<embed wmode="opaque"...
This should solve the issue in all browsers supported by the SmartMenus script except the following old versions - Mozilla<1.0, Opera<8.0, Safari<1.2 and Internet Explorer 5.1 on Mac Classic.
Most probably your menu tree UL/LI/A structure is not correctly defined. Most often the problem lies in the incorrect position of some of your closing </li> tags for the items that have sub menus (i.e. sub UL elements). For instance, the following structure is not valid:
<li><a href="URL">Item without sub menu</a></li>
<li><a href="URL">Item with sub menu</a></li>
<ul>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
<li><a href="URL">Item without sub menu</a></li>
The valid structure would look like this:
<li><a href="URL">Item without sub menu</a></li>
<li><a href="URL">Item with sub menu</a>
<ul>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
</li>
<li><a href="URL">Item without sub menu</a></li>
As you can see, the closing </li> tag for items that have sub menu (i.e. sub UL element) should be placed after the UL element and not before it. Although Internet Explorer on Windows seems to neglect this, most other browsers don't allow such invalid structure.
Most probably you have not changed the VISITED styles. The VISITED styles are useful in case you would like to set different style for the items that have been visited by the users (the :visited pseudo-class in CSS). However, if you do not want different style for the visited items, just set the VISITED values in your style arrays in "c_config.js" to be equal to your values for the normal state of the items:
VISITED BorderStyle = BorderStyle
VISITED BorderColor = BorderColor
VISITED Background = Background
VISITED Color = Color
...
If you see a "+" symbol inside the menu items that have sub menus, this means that:
To fix the issue, check the following:
c_imagesPath variable is set correctly in section 2 "MENU STYLES (CSS CLASSES)" of the configuration file (c_config.js). Its value should be set to the directory on your server that contains your sub menu indicator images. For example, if your images are located in the "images" sub directory in the root directory on your server, you should set the variable like this:
c_imagesPath="/images/"; // path to the directory containing the menu images
'[h_arrow.gif]', // SubMenuImageSource ('[image_source]')
'[h_arrow_over.gif]', // OverSubMenuImageSource
...
'[h_arrow.gif]', // VISITED SubMenuImageSource
...
'[h_arrow.gif]', // CURRENT SubMenuImageSource
Of course, you can also completely disable the sub menu indicator images if you like. To do this, simply set the following in the style arrays in section 2 "MENU STYLES (CSS CLASSES)" of the configuration file:
false, // UseSubMenuImage (true,false)
RightToLeft or BottomToTop is set to true in the menu tree features array for a given main menu). In many cases sub menus will be displayed but the user will not be able to interact with the menu items (e.g. hover or click). This serious bug is fixed as of Mozilla 0.9.9 and Netscape 7.BottomToTop is set to true in the menu tree features array for the given main menu). It positions such menus against the bottom edge of the whole BODY element instead of the bottom edge of the window like all other browsers.c_rightToLeft is set to true) any horizontal main menu you may have will not display the sub menus. But this is really not a big problem, because this browser doesn't even support RTL text anyway and this means that most probably no-one would use it to visit your site.Please don't hesitate to contact us if you have any questions, comments or suggestions.
For support, please use our dedicated support request form or visit the SmartMenus JavaScript menu forums.
Thank you!