Cascading Popup Menus v5.2


This file explains how to go about creating and editing menus using the "Cascading Popup Menus" JavaScript menu system, and contains a reference for the syntax of each of the main commands.

Need extra help? If you're not familiar with JavaScript syntax (or can't get the effect you want), you may find the Syntax Helper script useful, which can create the relevant commands listed here from selections in forms. And be sure to read the regular Help! document if you're stuck.

Colour coding used in this document: Variable or Object Name, 'String value', Number value, Boolean value (true or false), File Name.

Script License Agreement

You may use this script only if you agree that:

  1. You must EITHER:
    1. Donating Users: This script is "donation-ware". If you can make a donation to support this script, it may be used on a website without a crediting link. Please consider making a donation! I have spent a lot of time developing, debugging and documenting scripts, and any support is welcome. More info...
    2. Free Users: All websites using this script for free must contain somewhere a visible crediting link to TwinHelix Designs, e.g. 'DHTML / JavaScript Tree by TwinHelix Designs'.
  2. You must leave the "Script Name/Author/URL" comment in the source of the script file.
  3. This script is provided on an "AS-IS" basis, without any warranties, and you use it entirely at your own risk.
  4. This script may not be redistributed, sold, rented, leased or sublicensed to third parties without my prior consent.

If you have another use for the script (for example, within a web application) or wish to arrange alternate licensing terms, please contact me for more information.

Quickstart Guide

The main script is split over several files:

To edit this script, open up either the pop_data.js file (for the single-frame script) or the index.html file in the /FRAMESET folder (for the cross frame script) in a plain text editor like Windows Notepad or SimpleText. Don't use a HTML editor like FrontPage.

Then, read the rest of this file to understand the syntax needed to create your own menu arrangement. Frameset users should pay special attention to the Frameset Readme section of this file.

Once you have the menu setup the way you want, you need to add it to your pages. For single-frame usage, every page that will contain menus must include the 4 files listed above in order, using <SCRIPT> and <LINK> tags like in the example menu demonstation file. For frameset usage, the CORE and DATA script must be in the frameset file itself, and the CSS and EVENTS files must be included in each page you load in the frameset (see the example pages provided).

Other files included with this script are commented versions of the CORE and EVENTS script files, in case you need to edit them or are interested in how they work. They can be safely deleted as they're not required. Also, I have supplied a pop_extras.js file that contains optional menu extensions, it too can be deleted if you don't require it.

POP_DATA.JS: File Structure

var ItemStyleName = new ItemStyle(...parameters...);

var ObjectName = new PopupMenu('ObjectName');
with (ObjectName)

An optional "Menu Effects" section, including:

* Whole menu borders
* Menu dropshadows
* Menu animation settings
* Functions called by the above options

First, you create ItemStyles, which are collections of sizes, colours, and CSS classnames (for fonts and borders) to be applied to menus and items. This allows you to give different menus a consistent look and feel.

Then, you create one or more menu objects, giving each a unique name. The example script includes one named pMenu. Each menu object must be passed its own name in quotes.

To these menu objects, you add individual menus using the startMenu and addItem commands. Each menu object must have one or more menus that start with the letters 'root', which means it's always visible.

Finally, the Menu Effects section at the bottom of the file is optional, and can be removed entirely if you do not wish to use these extra effects. Otherwise, it contains comments and syntax notes itself, so read it if you're interested.

Script Syntax Reference


var ItemStyleName = new ItemStyle( Length, Spacing, 'Popout Indicator', Indicator Position, Padding, 'Out Background', 'Over Background', 'Out Font Class', 'Over Font Class', 'Out Border Class', 'Over Border Class', Out Opacity, Over Opacity, 'Link Cursor', 'Default Cursor');


startMenu( 'Menuname', Orientation, Left Offset, Top Offset, Menu Breadth, Default ItemStyle, 'Parent Frame', Show onclick);


addItem( 'Item HTML', 'URL / Menuname / Command', 'Item Type', Custom ItemStyle, Length, Spacing.....);

If you wish to add extra actions to items, like navigating to a file as well as popping out a submenu, please see the Extending section of this document.

Advanced Positioning (Centering menus etc.)

As mentioned above, the Left and Top positions for each menu can be strings containing JavaScript. I've provided several functions in this script using the page object, to detect window dimensions or the position of a named anchor, and use that to position menus. They are:

The values from these expressions are then set as the distance (in pixels) from the upper-left corner of the entire window/frame document, to the upper-left corner of the menu in question. You can write your own expressions if you want (and call your own functions perhaps), otherwise here are some cut-and-paste replacements for the standard root menu in the single-frame example:

Centre the menu by setting its "Left" position as half the window width minus half the menu width, so it straddles the page centreline:

startMenu('root', false, ' - menuW/2', 0, 17, hBar);

Scroll the menu with the page by setting its "Top" position to the window scroll position:

startMenu('root', false, 10, ' + 10', 17, hBar);

Position the menu relative to an anchor <a id="home" name="home"> in the page, positioned 20px below it. There are two steps to doing this. First, move the POP_EVENTS.JS script tag immediately before the closing </BODY> tag of your documents, after your document content. Then, use this as your menu position:

startMenu('root', false, '"home").x', '"home").y + 20', 17, hBar);

Are you using cross-frame menus? If so, include the name of the relevant frame in the expression like: '' for a frame named "content".

The script will attempt to reposition menus the fall outside the visible window/frame area. It will only do this to menus that are positioned relative to their parent menus, so if you wish to disable this behaviour, simply specify your menu position as a string 'in quotes'.

In the pop_extras.js there is a menu extension that can scroll menus larger than the current window size, you can add it to your menu if you want that behaviour.

Frameset Readme

This script supports displaying menus in different frames with a few tweaks -- see the demo frameset. To do this, you must include the pop_core.js and any pop_data.js files in the frameset, and include the .CSS and pop_events.js files in ALL documents loaded in the frames. Then, all you have to do is make sure you include a 'parent frame' value with each of your startMenu() commands, so menus will display in the correct frame. There are several restrictions however:

I also recommend you specify item filenames absolutely, e.g. '/folder/file.html', as relative navigation around framesets can get tricky. Item targets are measured relative to the frameset file, so addItem('a', 'b', '') will load 'b' in the whole frameset. Of course, you can set the frame target normally to load files in subframes, like addItem('a', 'b', 'content');

The example setup allows the menus in sub-frames scroll with their windows. All you have to do is use the 'page' object in that frame in a formula to get the current scrolling position of that frame, and then add or subtract pixels to position the menus from the scroll position, e.g. for a menu in a frame named 'xyz', we would set it to appear in that frame and appear near the top and 100px from the left:

startMenu('menuName', false, '', '', 17, hBar, 'xyz');

Relative positioning works too (that is, numbers as positions), but only really makes sense if the menus are in the same frame or the frames are aligned with each other in the frameset.

Extending The Script

Please load up the pop_extras.js file in a text editor if you're interested in making major script extensions -- it contains a list of all major extra functions bundled with the script, for effects like status messages, menu scrolling and more.

The addItem() and startMenu() commands return references to the objects they create. One practical use for this is to add an onclick action to an 'sm:' type menu item, which will allow them to navigate to a file when clicked. Events are set as evaluable strings, and you can add onmouseover, onmouseout, and onclick handlers to items. You can also put "return false" in them to disable any action that would normally occur on that event (e.g. stop menus hiding). Suggested syntax for navigating to files is:

with(addItem('Text', 'menuName', 'sm:')) onclick='window.location.href="file.html"';

In the frameset script of course, use frameName.location.href instead of window.location.href.

Another means of directing one item to point at both a menu and a file/script command is this:

with(addItem('Text', 'file.html', '')) sm='menuNameHere';

Good luck - Angus.