Adobe ColdFusion 8

Using menus and toolbars

The cfmenu and cfmenuitem tags let you create vertical menus and horizontal toolbars.

Defining menus

You define menus and toolbars as follows:

  • You use a single cfmenu tag to define the general menu characteristics.
  • You create a horizontal (toolbar) menu or vertical menu by specifying a cfmenu type attribute value of horizontal or vertical (the default).
  • Menus can have submenus, but only the top menu can be horizontal. All children of a horizontal menu are vertical.
  • The top-level menu shows initially, a submenu shows when the user moves the mouse over the menu root in the parent menu.
  • You use cfmenuitem tags to specify individual menu items.
  • To create submenus, you nest cfmenuitem tags. The parent tag becomes the root of the submenu.
  • All cfmenuitem tags, except tags for dividers, must have a display attribute, which defines the text to show on the menu item, and can optionally have an image attribute.
  • A horizontal menu has dividers between all items. You put dividers in vertical menus by specifying a cfmenuitem tag with a divider attribute.
  • To make a menu item active, you specify a href attribute with a URL or a JavaScript function to call when the user clicks the menu item.

The following example shows a simple horizontal menu with submenus that uses JavaScript to change the display contents. When the user selects an end item in a menu, the text in the div block below the menu shows the path to the selected menu.

<html>
<head>
</head>
<body>

<!--- The selected function changes the text in the selectedItemLabel div block to show the
        selected item. --->
<script type="text/javascript">
    function selected(item) {
        var el = document.getElementById("selectedItemLabel");
        el.innerHTML = "You selected: " + item;
    }
</script>

<!--- A horizontal menu with nested submenus. Clicking an end item calls the selected
        function. --->
<cfmenu name="hmenu" bgcolor="##9999ff" selectedfontcolor="##0000dd" 
        selecteditemcolor="##ddddff">
    <cfmenuitem display="Home" href="javascript:selected('Home');" />
    <cfmenuitem display="File">
        <cfmenuitem display="Open...">
            <cfmenuitem display="Template" href="javascript:selected('File &gt; 
                Open... &gt; Template');" />
            <cfmenuitem divider="true" />
            <cfmenuitem display="CSS" href="javascript:selected('File &gt; Open... &gt;
                CSS');" />
        </cfmenuitem>
        <cfmenuitem display="Close" href="javascript:selected('File &gt; Close');" />
    </cfmenuitem>
    <cfmenuitem display="Help">
        <cfmenuitem display="About" href="javascript:selected('Help &gt; About');" />
    </cfmenuitem>
</cfmenu>

<!--- A div with initial text.
        The selected function changes the text by resetting the innerHTML. --->
<div style=" margin-top: 100; margin-left: 10;"><span id="selectedItemLabel">
    Please select an item!</span></div>

</body>
</html>

Styling menus

The cfmenu and cfmenuitem tags have several attributes that let you easily control the menu appearance. These attributes consist of two types: basic and CSS style. Basic attributes, such as the cfmenu tag fontColor attribute, control individual menu characteristics. CSS style attributes let you specify a CSS style specification for a whole menu or part of a menu. The following information describes how the CSS style specifications interact and affect the menu style. For descriptions of all style-related attributes, see the cfmenu and cfmenuitem descriptions in the CFML Reference.

The cfmenu and cfmenuitem tags provide a hierarchy of CSS style attributes that affect different parts of the menu. The following table describes these attributes in hierarchical order:

Attribute

Description

cfmenu attributes

menuStyle

Applies to the menu, including any parts of the menu that surround the menu items. If you do not override this style in a cfmenu tag childStyle attribute or by specifying style information in the cfmenuitem tags, this attribute controls the style of the top-level items.

childStyle

Applies to the items in the top level menu and all child menu items, including the children of submenus. This attribute lets you use a single style specification for all menu items.

cfmenuitem attributes

style

Applies to the current menu item only. It is not overridden by the childStyle attribute.

menuStyle

Controls the overall style of any submenu of this menu item. This attribute controls the submenu of the current menu item, but not to any child submenus of the submenu.

childStyle

Applies to all child menu items of the current menu item, including the children of submenus.

In addition to these styles, you must consider any style-related attributes, such as bgcolor, that you set on the cfmenu tag.

When you design your menu, you should keep the following issues in mind:

  • Keep font sizes at 20 pixels or smaller. Larger sizes can result in menu text in vertical menus exceeding the menu boundaries.
  • Consider how the style attributes interact. Because each menu and submenu consists of a surrounding menu area and individual child items, you must particularly careful when you choose background colors. For example, if you specify different background-color styles in the cfmenu tag's menuStyle and childStyle attributes, the menu items are one color and the surrounding menu area are a different color.

For an application that shows some of the effects of menu style attributes, see the example in the cfmenuitem tag in the CFML Reference.

ColdFusion attributes provide most style options that you are likely to require. However, you can, if necessary, modify the basic menu styles for all menus by editing the menu-related styles in the CSS files in the yui.css file. This file is located by default in the web_root/CFID/scripts/ajax/resources/yui directory. For more information about these styles, see the Yahoo! User Interface Library menu documentation.