COOLjsMenu Documentation

Foreword

This document covers most of the creation and initialization process for COOLjsMenu and COOLjsMenu Professional from CoolDev.Com. While this document describes data structures needed by these scripts and the way all these things can be glued together to fit in your pages, you will not find wide variety of complete samples here: you can find them in your COOLjsMenu or COOLjsMenu Professional package in the "demos" or "samples" subdirectories. Also, this document does not cover license, support and purchase issues - answers to these questions you can find in the FAQ.

COOLjsMenu Professional has all the functions that are included in COOLjsMenu, and offers many additional, but generally scripts are compatible. Input data and format specifications for both these scripts are very alike, and all farther references to "menu" will mean both COOLjsMenu and COOLjsMenu Professional if not specified otherwise.

Authors

Author of this document is Alex Kunin (alx@cooldev.com), representative of CoolDev.com technical support team (jssupport@cooldev.com). If you have comments, questions, brilliant ideas, more brilliant ideas, or you want to criticize something then don't hesitate contacting me.

Contents

  1. General information
  2. Required components and installation process
  3. Complete samples
  4. Reference
    1. Menu definition file format
    2. API

General information

Scripts covered in this document allow you to create and use menu-like visual representation of hierarchical data - most close analogies are menu bar and popup menu which can be found in almost every visual application. The most natural way to use these scripts is to build site navigation system, but there are some other variants how menus can be used: context menus, rollover-enabled buttons, compact document outline, etc. Galleries of samples for the COOLjsMenu and COOLjsMenu Professional are available online - they will help you to get general idea of the possibilities that menu provides.

Basically menu is a program written in JavaScript - programming language commonly used in web development. No JavaScript knowledge is required to use the menu - this is not too hard to modify existing sample (e.g. complete sample which is explained in this document) to get working menu which will suit your needs. But for advanced menu usage it is strongly recommended to have basic JavaScript skills.

To create and test menu you need some text editor and some browser. Menu runs on most of the available browsers that provide JavaScript and CSS support. These browsers are: Internet Explorer 4 and above, Netscape Navigator 4.x, Netscape Navigator 6 and above, Mozilla 0.9.4 and above, Opera 5 and above. To create and/or modify menu definition you need some text editor (Notepad for Windows' users is a good one to start). More complex systems for site management such as FrontPage, InterDev, and Dreamweaver also can be used.

Required components and installation process

To get the menu working you need following components:

  • menu script itself (coolmenu.js or coolmenupro.js; these files are can be found in the "js" subdirectory in the corresponding packages);
  • menu structure definition - captions and URLs for every item, styles, position, offsets, sizes, etc.;
  • HTML page which will include the menu.

You can place these components into separate files (next section tells how to do this) or put them into a single HTML document. No matter what way you will choose initialization sequence must be in the HTML code. This sequence is different for COOLjsMenu and COOLjsMenu Professional.

COOLjsMenu's initialization sequence presented below.

<script type="text/javascript">
var myMenu = new COOLjsMenu("menu1", MENU_ITEMS);
</script>

This code snippet must be placed somewhere in the HTML code, but not inside any containers other than <BODY> - this is very important. By not following this rule you'll get displaced submenus. The best place for this code is immediately before the closing </BODY> tag - it is safe to place initialization there. (Technical details: COOLjsMenu's constructor will generate HTML code - set of DIVs, and then this code will be written to the document flow using "document.write()" method. So, putting the constructor call in a wrong place will lead to undesirable side effects.)

Initialization sequence for COOLjsMenu Professional looks like the this:

var myMenu = new COOLjsMenuPRO("menu1", MENU_ITEMS);
</script>
...
<script type="text/javascript">
myMenu.initTop();
</script>
...
<script type="text/javascript">
myMenu.init();
myMenu.show();
</script>
</body>
</html>

As you can see code contains three custom elements (this applies to both COOLjsMenu and COOLjsMenu Professional):

  • myMenu - name of the variable that will hold reference to the newly created menu; this variable can be used to access menu at runtime, e.g. to hide or show submenus or to set up event handlers;
  • "menu1" - name of the menu; if you have several menus on the page then you have to name them differently, e.g. "menu1", "menu2" and so on; it is recommended to compose these names using alphanumeric characters because there are many places where names will be used: CSS class names, images' and layers' identifiers - some browsers do not allow to have fancy symbols here (e.g. Opera 5 does not understand CSS class names with underscores); it's Ok if menu name and menu variable name will match;
  • MENU_ITEMS - JavaScript array with items (you can find sample farther in this section, reference is in the corresponding section); because this is a JavaScript construct it's definition must be placed into <SCRIPT> tag or into the separate .js file.

COOLjsMenu Professional has couple of additional initialization statements (see Fig. 2). If your menu is positioned absolutely (see "Menu definition file format" reference for details) then you can place all these code pieces into single <SCRIPT> statement just before the </BODY> - outside of any containers. For relative positioning mode following rules must be honored: "new COOLjsMenuPRO(...)" part can be placed anywhere before the "initTop()"; at the place where you want to see your menu (e.g. inside a TD cell) "initTop()" part must be placed; "init()" and "draw()" should be at the very end of file before the closing </BODY> tag.

Here is minimum HTML document with COOLjsTree inside:

<html>
    <head>
        <script type="text/javascript" src="coolmenu.js"></script>
    </head>
    <body>
        <script type="text/javascript">
// Part 1 - Styles
var STYLE = {
    border:1,              // item's border width, pixels; zero means "none";
    shadow:2,              // item's shadow size, pixels; zero means "none"
    color:{
        border:"#666666",  // color of the item border, if any;
        shadow:"#DBD8D1",  // color of the item shadow, if any;
        bgON:"white",      // background color for the items;
        bgOVER:"#B6BDD2"   // background color for the item
                           // which is under mouse right now;
    },
    css:{
        ON:null,           // CSS class for items;
        OVER:null          // CSS class  for item which is under mouse;
    }
};

// Part 2 - Menu structure
var MENU_ITEMS = [
    {pos:[10,10], itemoff:[0,99], leveloff:[21,0], style:STYLE, size:[22,100]},
    {code:"Item 1", url:"item1.html",
        sub:[
            {"itemoff":[21,0]},
            {code:"SubItem 1", "url":"subitem1_1.html"},
            {code:"SubItem 2", "url":"subitem1_2.html"},
            {code:"SubItem 3", "url":"subitem1_3.html"},
            {code:"SubItem 4", "url":"subitem1_4.html"}
        ]
    },
    {code:"Item 2", url:"item2.html",
        sub:[
            {itemoff:[21,0]},
            {code:"SubItem 1", "url":"subitem2_1.html"},
            {code:"SubItem 2", "url":"subitem2_2.html"},
            {code:"SubItem 3", "url":"subitem2_3.html"},
            {code:"SubItem 4", "url":"subitem2_4.html"}
        ]
    }
];

// Part 3 - Initialization code
var m1 = new COOLjsMenu("menu1", MENU_ITEMS);
                </script>
        </body>
</html>

Initialization sequence is denoted by blue background. Menu definition has been split into two parts - style definition (red border) and structure definition (green border ). That was done only for convenience, and piece of code which references style definition can be solid:

var MENU_ITEMS = [
    {
        pos:[10,10],
        itemoff:[0,99],
        leveloff:[21,0],
        style:{
            border:1,
            shadow:2,
            color:{
                border:"#666666",
                shadow:"#DBD8D1",
                bgON:"white",
                bgOVER:"#B6BDD2"
            },
            css:{
                ON:"clsCMOn",
                OVER:"clsCMOver"
            }
        },
        size:[22,100]
    },
    {code:"Item 1", url:"item1.html",
    ...
];

But average menu usually contains more than one style, and there can be more then one reference to the same style. So, to have clean, non-garbled code we recommend you to split styles and structure.

COOLjsMenu Professional has same inclusion scheme, but with some additional statements in the initialization sequence:

var m1 = new COOLjsMenuPRO("menu1", MENU_ITEMS);
m1.initTop();
m1.init();
m1.show();

Style definitions and structure definitions are basically the same.

Detailed information about style and structure definitions are given in the "Reference" section.

Complete samples

If you plan to include same menu into many pages from your site then it is good idea to split samples from previous section into several files. Here is typical set of files:

  • menuitems.js - contains MENU_ITEMS variable - menu's styles and structure;
  • style.css - CSS classes for the menu;
  • coolmenu.js or coolmenupro.js - the menu itself;
  • images - your menu will contain at least blank 1x1 image (it is used internally by the script), and also there can be additional images like icons and arrows.

Some HTML code is also needed, of course.

Here are two complete samples which contain all the files listed above: COOLjsMenu and COOLjsMenu Professional. These are good points to start from: .js files are commented, and you will not get lost. So, download these .zip files, unpack them somewhere, add coolmenu.js and coolmenupro.js, and then run the samples.

Reference

This section consists of two parts: menu definition file format and API - list of available functions, methods, properties, and event handlers.

  1. Menu definition file format
  2. API

Menu definition file format

Menu definition file format consists of two parts: styles and structure.

// styles
var STYLE1 = {
    border:1,
    ...
};

var STYLE2 = {
    border:1,
    ...
};

// structure
var MENU_ITEMS = [
    {pos:'relative', style:STYLE1, ...},
    {code:'Item 1', ...},
    ...
];

"MENU_ITEMS" is the name of the variable which holds full menu definition - that name will be used during menu initialization. Style names "STYLE1", "STYLE2" will be used only within menu definition file. Styles' definition are separated from the structure only for convenience - "MENU_ITEMS" actually holds united array of styles and structure.

Style definition

Menu style defines colors for item background (1), shadow (2), border (3), icon background (4). Also, it defines colors for item and icon backgrounds in rollovered state, size of the shadow and border, and CSS classes for the item's text in rollovered state.

Here is typical style definition:

var STYLE1 = {
    border:1,
    borders:[1,1,2,1],
    shadow:2,
    color:{
        border:"#666666",
        shadow:"#DBD8D1",
        bgON:"white",
        bgOVER:"#B6BDD2",
        imagebg:'silver',
        oimagebg:'black'
    },
    css:{
        ON:"clsCMOn",
        OVER:"clsCMOver"
    },
    transition:{
        fadeIn:'progid:DXImageTransform.Microsoft.RandomDissolve(duration=0.3)',
        fadeOut:''
    }
};

Style definition's fields have following meanings:

Section Name Description
  border Specifies size of the border, in pixels. Zero means "no border".
  borders

Professional only: specifies individual sizes for border sides, e.g.:

borders:[4,5,6,7],

This means: left border will be 4 pixels, top - 5 pixels, right - 6 pixels, and bottom - 7 pixels. Zero value of "border" fields overrides "borders", i.e. there will be no border.
  shadow Specifies shadow size, in pixels. Shadow always goes to the right-bottom.
color border Defines border's color.
shadow Defines shadow's color.
bgON Defines item's background color for normal (bgON) and rollovered (bgOVER) states. If color is blank string (''), then menu item will be transparent.
bgOVER
imagebg Professional only: defines icon's background color for normal (imagebg) and rollovered (oimagebg) states.
oimagebg
css ON Defines item's CSS class for normal (ON) and rollovered (OVER) states.
OVER
transition fadeIn Defines transitions to use for item's background. This feature is available under Internet Explorer only. Empty string means "no transition", and "progid:..." specifies some filter to be used.
For more information on filters and transitions, please read this article at MSDN: Introduction to Filters and Transitions.
fadeOut


All colors can be specified as #XXXXXX (where X is hexadecimal digit) or as color name (red, green, blue, etc.).

Structure definition

Generally, menu structure definition looks like the following:

var MENU_ITEMS = [
    { pos:'relative', leveloff:[b,a], itemoff:[d,c], size:[e,f], ... },
    { ...Item 1... },
    { ...Item 2... ,
        sub:[
            { ...level format... },
            { ...Item 1... },
            { ...Item 2... },
            { ...Item 3... ,
                sub:[
                    { ...level format... },
                    { ...Item 1... },
                    { ...Item 2... },
                    { ...Item 3... },
                    { ...Item 4... }
                ]
            },
            { ...Item 4... },
        ]
    },
    { ...Item 3... }
];

Instead of "...level format..." following fields can be used:

Name Where can be specified? Description
Top-level Sublevels Individual
items
position Mandatory    

Specifies positioning mode of the menu. To place menu at absolute coordinates x=100, y=200 following code can be used:

var MENU_ITEMS = [
    { pos:[100,200], ... },
    ...
];

Professional also can be positioned relatively, i.e. it will be inserted instead of "initTop()" call:

var MENU_ITEMS = [
    { pos:'relative', ... },
    ...
];
size Mandatory Optional Optional

Defines item's size, e.g. item size 100x20 pixels will look like this:

{..., size:[20,100], ...
itemoff Mandatory Optional Optional

Specifies distance between top-left corners of the neighbor items. Horizontal offset - 10 pixels, vertical offset - 5 pixels:

{..., itemoff:[5,10], ...
leveloff Mandatory Optional  

Specifies distance between top-left corner of the item and it's submenu. Following code will make submenu appear under the item:

{..., leveloff:[20,0], ...
delay Optional     Specifies timeout in milliseconds before menu will reset after last roll out event. Default is 600 ms.
style Mandatory Optional Optional

Associates style with submenu or item, e.g.:

var STYLE1 = {
    border:1,
    shadow:2,
    ...
};

...

var MENU_ITEMS = [
    { ..., style:STYLE1, ... },
    {code:'Item 1', ...
];
image Optional Optional Optional

Professional only: defines icon image ("image" - path to "normal" image, "oimage" - path to optional "rollovered" image") and it's size (which is mandatory), e.g:

{...,
    image:'icon1_normal.gif',
    oimage:'icon1_rollover.gif',
    imgsize:[10,15], ...

To stop inheritance, you can specify "null" value:

{..., image:null, ...

Image will be aligned to the left side of the item. If you want to have item with no text, but with image, then you can use item's "code" fields (and optionall "ocode" for rollover effect) with <img src="..."> tag inside.
oimage Optional Optional Optional
imgsize Optional Optional Optional
arrow Optional Optional Optional Professional only. Mostly same as "image", "oimage", and "imgsize", but icon will be aligned to the ritght side, and it will present only when item has associated submenu.
oarrow Optional Optional Optional
arrsize Optional Optional Optional
https_fix_blank_doc Optional    

Professional only: built-in form elements issue fix for Microsoft® Internet Explorer needs to create <iframe> elements with some blank document inside. Default value "about:blank" in HTTPS environment will result in annoyng messages about insecure elements on the page. To get rid of these messages menu definition file must include this field, and value must be path to empty HTML file on the same server where page is. E.g.:

var MENU_ITEMS = [
    {..., https_fix_blank_doc:'/blank.html', ...},
    ...
];

This code expects that secure server will contain empty file blank.html in the root directory.
forms_to_hide Optional    

Professional only. Built-in form elements issue fix works only with Microsoft® Internet Explorer, and other browsers like old Opera should work this around. One of the possible ways is to hide form elements when submenu gets shown, and to show them again when submenu becames hidden again - this can be done by adding IDs of these elements to this field, e.g:

var MENU_ITEMS = [
    {..., forms_to_hide:['combo1', 'combo2'], ...},
    ...
];

And HTML code with form elements:

<html>
    <head>
    ...
    </head>
    <body>
        <!-- menu initialization;
        other HTML code -->
        <form name="..." action="...">
            <select name="combo1" id="combo1">
                <option>Option 1</option>
                <option>Option 2</option>
                <option>Option 3</option>
            </select>
            <select name="combo2" id="combo2">
                <option>Option 1</option>
                <option>Option 2</option>
                <option>Option 3</option>
            </select>
        </form>
    </body>
</html>

To see working demo, click here.
popup Optional     Professional only: popup menus must have "popup" field set to "1" or "true". Working sample with additional information is here.
popupoff      
hidden_top       Professional only: this parameter is used only when menu is in special "cross-frame" mode, and it must be equal to "1" or "true". Working sample is here.
fadeIn, fadeOut Optional Optional   This parameter allows to specify a transition(s) for the whole level. Transitions are available only under Internet Explorer. More information can be found here: Introduction to Filters and Transitions.
filters Optional Optional   Every level can have one or more filters assigned. Multiple filters must be separated with spaces. This feature are available only under Internet Explorer. More information can be found here: Introduction to Filters and Transitions.


All these values are inherited "in depth", i.e. if submenu defines style and size of it's items, then all submenus recursively will have items with same style and size, unless specified otherwise.

Every item can contain following fields:

Name Description
code "code" contains item's caption for normal state, and "ocode" - for rollovered state. Almost any HTML code can be used here, but only simple formatting instructions (DIV and SPAN with "class" or "style" attributes, B, I, U, etc.) and images will be useful enough. If "ocode" is ommited, "code" will be used for rollovered state.
ocode
url Associates URL with item. Fully compatible with <a href="..."> (including "javascript:" protocol).
target Specifies optional target frame, same as <a target="...">.
format

Allows to use formatting instructions individually, e.g. following code assigns icon image to the item (and all submenus of that item, if any):

{code:'Item 1', format:{image:'images/icon.gif', imgsize:[15,15]}, ...

See table above to find out what fields can be used here.
sub

Defines submenu, e.g.:

{code:'Item with submenu',
    sub:[
        {style:SOME_STYLE},
        {code:'Item 1'},
        {code:'Item 2'}
    ]
},
hasControls

Professional only: allows to use form controls as content for the item, e.g.:

{
    code:'Some memo:<br /><textarea></textarea>',
    hasControls:true,
    format:{size:[78,170]}
},

When this attribute presents, menu behaves differently: it will allow you to focus control without hiding itself. Also, "ocode" attribute will not work for items with "hasControls" set to "true".