Menu

Try moving the mouse over the items and clicking different items. Any number of items can be defined for an individual menu. Items can also have submenus that appear when moused over (indicated by an arrow graphic). Submenus can have items with their own submenus. In fact, menus can be nested as deep as you want.

You can also click anywhere on the page to make the menu appear at your mouse pointer. Try it near the edge of the window, you'll notice that the menus are automatically positioned to fit within the viewable region of the window.

Each item can have a link associated with it or it can be set to execute JavaScript code, useful for linking in framesets or opening links in new windows.

You can also change the look of the menus. The sizes, fonts and colors of each are all configurable. Top-level menus can optionally be placed in a fixed position on the page, and/or made static, so that they remain visible all the time.

Using the Script

You'll need to include the dhtmllib.js and popupmenu.js files in your page then add some menu definitions. You'll also need some images for the arrows if you use submenus. The default images are in a subdirectory named "graphics/" and can be copied from this site (see the Source section and notes at the end of this article).

Defining Menus

Creating menus is easy. The script provides two new objects, PopUpMenu and PopUpMenuItem. The addItem() method adds a PopUpMenuItem to a PopUpMenu while addSeparator() inserts a separator bar. Here's a simple example.

  var myMenu = new PopUpMenu(120);
  myMenu.addItem(new PopUpMenuItem("Item 1 Text", "page1.html"));
  myMenu.addItem(new PopUpMenuItem("Item 2 Text", "page2.html"));
  myMenu.addItem(new PopUpMenuItem("Item 3 Text", "page3.html"));
  myMenu.addSeparator();
  myMenu.addItem(new PopUpMenuItem("Item 4 Text", "page4.html"));

Note that PopUpMenu() takes one argument which determines the width of the menu, in pixels. Also note that the items and separators will be displayed in the order that they are added to a menu.

PopUpMenuItem() takes two arguments, the first is the text to display and the second is either a URL to link to or a string of JavaScript code to execute (see below).

Configuring the Menu Appearance

Several methods are provided to change the sizes, font, colors and arrow images used in a menu.

• setSizes(border, padding, spSize, spPadding) - Sets the size of the border around the menu, the amount of spacing around menu item text and the thickness and amount of padding around separator bars respectively. All values are in pixels.

• setColors(fgColor, bgColor, hiFgColor, hiBgColor, bdHiColor, bdShColor, spHiColor, spShColor) - Sets the item text and background colors, the highlighted item text and background colors, the highlight and shadow colors for the menu border and the highlight and shadow colors for the separator bars. Standard HTML RGB values and color names are allowed.

• setFont(family, style, weight, size) - Defines the font used for the item text. Standard CSS values are allowed.

• setImages(none, norm, high, width, height) - When a item has a submenu, an arrow image is displayed on the far right of the item text. This method allows you to change the images used. The values should be URLs pointing to the images that will replace the defaults along with the width and height to use in displaying those images.

• copyAttributes(menu) - Provides an easy way to set one menu's appearance to match another. It will copy the current size, color, font and image settings of the given menu to this one. Note that any or all of the menu's attributes can still be changed individually using the above methods after calling this one.

You will probably want to change the the arrow images if you use something other than the default font size and menu colors. The default none image is a singe-pixel, transparent gif used as a spacer for items without a submenu. The default norm and high images are small arrows 8x12 pixels in size. They are identical except in the colors used The default images are expected to be in a subdirectory named "graphics/" but that can be changed via setImages().

Here's an example of how to configure a menu. In this case, we make the highlight and shadow colors of the border and separator bars the same, essentially creating a solid border around each item for a 'flat' appearance. The arrow images are replaced with ones that better match the larger font size and colors and are located in the same directory as the page.

  myMenu.setSizes(2, 4, 2, 0);
  myMenu.setFont("Verdana", "italic", "bold", "12pt");
  myMenu.setColors("#ffffff", "#000099", "#ffff00", "#000000",
    "#00cccc", "#00cccc", "#00cccc", "#00cccc");
  myMenu.setImages("transparent.gif", "whiteArrow.gif", "yellowArrow.gif",
    12, 16);

Setting Up Item Links

As mentioned before, when you add an item to a menu you have to specify a PopUpMenuItem object, which is built from a string of text and a string denoting the link.

The link can be one of three things. A URL, a null string ("") or a string of JavaScript code (any string beginning with "javascript:").

For a URL, the link is loaded into the current window or frame when the item is clicked on. When a null string is specified, it creates a 'dead' link. Clicking on the item does nothing, but it will still be highlighted and any submenu will pop up when moused over.

Menu items are not like normal HTML links (<A HREF="...">). So you cannot specify a target frame or window or event handlers like onmouseover. You can, however, use JavaScript code to achieve some of the same effects.

Any link string that begins with "javascript:" is executed using the built-in eval() function when the item is clicked. This means that you can load pages in frames like this.

  var myItem = new PopUpMenuItem("Table of Contents",
    "javascript:top.frames['main'].location = 'toc.html'");

Which loads the URL 'toc.html' into a frame called 'main' (be sure to see the notes on Using Menus in Frames if you intend to use the script in a frameset).

You can open a link in a new browser window using the window.open() method. The code below produces the same result as using TARGET="_blank" in a link.

  var myItem = new PopUpMenuItem("Table of Contents",
    "javascript:window.open('toc.html')");

Adding Submenus

To create a submenu, just create another PopUpMenu as before, then add it to the parent menu with the addSubmenu() method.

  var mySubmenu1 = new PopUpMenu(100);
  mySubmenu1.addItem(new PopUpMenuItem("Item 1A Text", "page1a.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1B Text", "page1b.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1C Text", "page1c.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1D Text", "page1d.html"));

  var mySubmenu2 = new PopUpMenu(100);
  mySubmenu2.addItem(new PopUpMenuItem("Item 2A Text", "page2a.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2B Text", "page2b.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2C Text", "page2c.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2D Text", "page2d.html"));

  var myMainmenu = new PopUpMenu(120);
  myMainmenu.addSubmenu(
    new PopUpMenuItem("Item 1 Text", "page1.html"), mySubmenu1);
  myMainmenu.addSubmenu(
    new PopUpMenuItem("Item 2 Text", "page2.html"), mySubmenu2);
  myMainMenu.addSeparator();
  myMainmenu.addItem(new PopUpMenuItem("Item 3 Text", "page3.html"));
  myMainmenu.addItem(new PopUpMenuItem("Item 4 Text", "page4.html"));
  myMainmenu.addItem(new PopUpMenuItem("Item 5 Text", "page5.html"));

The addSubmenu() method works just like the additem() method except that it takes a second parameter, the menu that should be displayed when the item is highlighted.

Note that you need to create a submenu before you can add it to a menu. You can, however, add items or submenus at any time up until you actually build the menu on the page with the create() method (see below). This examples results in the same menu as above.

  var myMainmenu = new PopUpMenu(120);
  var mySubmenu1 = new PopUpMenu(100);
  var mySubmenu2 = new PopUpMenu(100);

  myMainmenu.addSubmenu(
    new PopUpMenuItem("Item 1 Text", "page1.html"), mySubmenu1);
  myMainmenu.addSubmenu(
    new PopUpMenuItem("Item 2 Text", "page2.html"), mySubmenu2);
  myMainmenu.addSeparator();
  myMainmenu.addItem(new PopUpMenuItem("Item 3 Text", "page3.html"));
  myMainmenu.addItem(new PopUpMenuItem("Item 4 Text", "page4.html"));

  mySubmenu1.addItem(new PopUpMenuItem("Item 1A Text", "page1a.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1B Text", "page1b.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1C Text", "page1c.html"));
  mySubmenu1.addItem(new PopUpMenuItem("Item 1D Text", "page1d.html"));

  mySubmenu2.addItem(new PopUpMenuItem("Item 2A Text", "page2a.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2B Text", "page2b.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2C Text", "page2c.html"));
  mySubmenu2.addItem(new PopUpMenuItem("Item 2D Text", "page2d.html"));

After a menu and its submenus have been defined and configured, they need to be built by creating the necessary DHTML elements and added those to the page.

Page 1 - Page 2 - Page 3