Client Side Menu Components
This chapter describes built-in Zen components that are designed to make it easy to render a more “native application” look and feel for Zen pages through the use of a client side menu system. These menu components provide simple mechanisms for JavaScript post-processing on the client side, so that their appearance and layout can respond to user actions on the client side.
The style for more traditional menu components is defined with CSS and HTML, without the option for subsequent post-processing in JavaScript. For full information about those components, see the “Navigation Components” chapter of Using Zen Components.
Building Client Side Menus
The original <menu> component offers a simple HTML label in a box with all of its (limited) rendering done at the server with a little help from CSS preferences. It is perfectly serviceable as a menu, but its appearance has very little flexibility.
In contrast, the <csMenuBar> defers its rendering until it has actually been loaded by the client and has access to more information about the user’s machine (browser, operating system, available fonts, etc). The <csMenuBar> makes heavy use of JavaScript to do things that are difficult (or in some cases impossible) to do with CSS alone. It can render a menu that looks and acts more like a user might find in applications such as Microsoft Outlook or Word. This menu includes features such as icons, keyboard shortcuts, scrolling of long menus without scrollbars, and so on.
In general, the cs prefixed widgets such as <csMenuBar> form one set of tools, while the traditional menu widgets described in the “Navigation Components” chapter of Using Zen Components form another. These sets are not interchangeable. For example, a <csMenuBar> consists of <csMenuBarItem>, <contextMenu>, <csMenuItem>, and <csMenuSeparator> elements. A mixed specification in which <csMenuItem> elements are separated by <menuSeparator> elements causes the menu subsystem to break.
It is important to note that there is inconsistency in the naming conventions. Not all of the client side widget names start with cs. The cs prefix is used only when the newer, client side widget name conflicts with the older, original widget names. Unfortunately this means that <contextMenu>, the widget at the heart of the client side menu subsystem, does not use the cs prefix, but every element around it does.
The following is a summary of the nesting structure for the client side menu elements:
<csMenuBar>
<csMenuBarItem>
<contextMenu>
<csMenuItem />
<csMenuItem />
<csMenuSeparator />
<csMenuItem />
<csMenuItem>
<contextMenu>
<csMenuItem />
<csMenuItem />
</contextMenu>
</csMenuItem>
</contextMenu>
</csMenuBarItem>
</csMenuBar>The next several sections describe how to work with client side menu components to provide:
For a syntax guide to specific components, see the later sections in this chapter:
Drop Down Menus
The following sample <csMenuBar> element defines a horizontal menu bar with two picks: File and Edit. Each of these picks displays a different <contextMenu>. The <csMenuItem> components in this example illustrate a variety of options for setting associated icons, alternate captions, keyboard shortcuts, and so on. The following figure illustrates the File pick from this menu.
<csMenuBar id="mainMenu" width="100%">
<csMenuBarItem caption="File" contextKey="f" >
<contextMenu id="fileMenu" >
<csMenuItem icon="images/file.png" caption="New" key="Ctrl-N"
contextKey="n" onclick="alert('New requested');" />
<csMenuItem icon="/csp/broker/images/open.png" caption="Open..."
key="Ctrl-O" contextKey="o"
onclick="alert('Open requested');" />
<csMenuItem caption="Close" key="Ctrl-W"
contextKey="c" onclick="alert('Open requested');" />
<csMenuSeparator />
<csMenuItem id="savePick" icon="/csp/broker/images/save.png"
iconDisabled="/csp/broker/user/images/save_g.png"
caption="Save" key="Ctrl-S" contextKey="s"
onclick="alert('Save requested');" />
<csMenuItem icon="/csp/broker/images/saveas.png" caption="Save as..."
contextKey="a" />
<csMenuItem icon="/csp/broker/images/saveall.png" caption="Save All"
contextKey="l" />
<csMenuSeparator />
<csMenuItem icon="/csp/broker/images/print.png" caption="Print"
key="Ctrl-P" contextKey="p"
onclick="alert('Print requested');" />
<csMenuItem caption="Print Preview..." contextKey="v" />
<csMenuItem caption="Print Setup..." contextKey="r" />
<csMenuSeparator />
<csMenuItem caption="Recent Files" contextKey="e" />
<csMenuSeparator />
<csMenuItem caption="Exit" contextKey="x" />
</contextMenu>
</csMenuBarItem>
<csMenuBarItem caption="Edit" contextKey="e">
<contextMenu id="editMenu" >
<csMenuItem id="undoPick" icon="/csp/broker/images/undo.png"
caption="Undo" key="Ctrl-Z" altCaption="Can't undo"
contextKey="u" onclick="alert('undo');" />
<csMenuItem id="redoPick" icon="/csp/broker/images/redo.png"
caption="Redo" key="Ctrl-Y" altCaption="Can't redo"
contextKey="r" onclick="alert('redo');" />
<csMenuSeparator />
<csMenuItem id="cutPick" icon="/csp/broker/images/cut.png"
caption="Cut" key="Ctrl-X" contextKey="t"
onclick="alert('cut');" />
<csMenuItem id="copyPick" icon="/csp/broker/images/copy.png"
caption="Copy" key="Ctrl-C" contextKey="c"
onclick="alert('copy');" />
<csMenuItem id="pastePick" icon="/csp/broker/images/paste.png"
caption="Paste" key="Ctrl-V" contextKey="p"
onclick="alert('paste');" />
<csMenuSeparator />
<csMenuItem caption="Fill" contextKey="i" onclick="alert('fill');" />
<csMenuItem caption="Clear" contextKey="a" onclick="alert('clear');" />
<csMenuItem caption="Delete..." key="delete"
contextKey="d" onclick="alert('delete');" />
<csMenuSeparator />
<csMenuItem caption="Select all" key="Ctrl-A"
contextKey="l" onclick="alert('select all');" />
<csMenuSeparator />
<csMenuItem icon="/csp/broker/images/find.png" caption="Find..."
key="Ctrl-F" contextKey="f" onclick="alert('find');" />
<csMenuItem caption="Find in Files" key="Ctrl-Shift-F"
onclick="alert('find next');" />
<csMenuItem caption="Replace..." key="Ctrl-H" contextKey="e"
onclick="alert('replace');" />
<csMenuItem icon="/csp/broker/images/goto.png" caption="Go to..."
key="ctrl-g" contextKey="g" onclick="alert('goto');" />
</contextMenu>
</csMenuBarItem>
</csMenuBar>The following figure illustrates the Edit pick from this menu.
Popup or Context Menus
You can use client-side menu components to define a popup or context menu for a region. To accomplish this, wrap a <contextMenu> definition inside a group of some kind. The wrapper component can be nearly anything, but is most often a reasonably significant portion of the page: a <vgroup>, <hgroup>, <form>, etc. Define the <contextMenu> as a child of the wrapper component, and a sibling of other elements within the wrapper. You can optionally specify exact bounds, as for the <group> shown in the next example, but this is not required.
Subsequently, when the user right-clicks the mouse anywhere within the wrapper component, Zen displays and activates the <contextMenu> child component, rather than the browser’s default right-click menu.
<group width="400" height="800" enclosingStyle="background:#aaffaa;" >
<contextMenu id="rightPopUp" >
<csMenuItem caption="Fido Cascade" >
<contextMenu >
<csMenuItem caption="Sit" />
<csMenuItem caption="Stay" />
<csMenuItem caption="Play dead" />
</contextMenu>
</csMenuItem>
<csMenuItem caption="Scout Cascade" >
<contextMenu >
<csMenuItem caption="Whoa" />
<csMenuItem caption="Giddy Up" />
</contextMenu>
</csMenuItem>
<csMenuItem caption="Kitty Cascade" >
<contextMenu >
<csMenuItem caption="Ignore me" />
<csMenuItem caption="Do as you please" />
</contextMenu>
</csMenuItem>
</contextMenu>
</group>
The following figure displays the popup menu that the previous example defines.
Button Bars
The <buttonBar> component is closely related to the client side menu components. A <buttonBar> may appear inside any sort of group container, and may contain one or more <buttonBarItem> components. The following <hgroup> element defines a button bar with three buttons, rollover tool tips, and selection actions (the alert code).
<hgroup id="bbArea" >
<buttonBar id="editStuff" >
<buttonBarItem icon="images/cut.png" caption="Cut"
onclick="alert('Cut requested');" />
<buttonBarItem icon="images/copy.png" caption="Copy"
onclick="alert('Copy requested');" />
<buttonBarItem icon="images/paste.png" caption="Paste"
onclick="alert('Paste requested');" />
</buttonBar>
</hgroup>The style for this bar is defined in the XData Style section as follows:
#bbArea {
background:#bbbbbb;
background-image: url(images/grad-halfgray-10x30.png);
background-repeat:repeat-x;
}
The following figure displays the button bar that this example defines.
For some image files that you can use as icons in button bars, see the section “Icons.”
Icons
The following table lists the icons that are available in the csp/broker/images directory, which is a subdirectory of the Caché installation directory. The gray background color shown for icons in the table is just an example; the icons display over whatever background color the designer chooses for the containing component.
Icon images may be referenced using the icon, altIcon, or disabledIcon attributes in Zen components such as <buttonBarItem> or <csMenuItem>. When you reference these images, the prefix csp/broker is automatically implied. Reference them using this syntax:
images/filename
For example:
altIcon="images/cut.png"
| Icon | File Name | Meaning |
|---|---|---|
 |
buildall.png | Build all or compile all files |
 |
compile.png | Compile current file |
 |
copy.png | Copy |
 |
cut.png | Cut |
 |
DownArrow.png | Down arrow, larger size, for light background colors |
 |
DownArrowInv.png | Down arrow, larger size, for dark background colors |
 |
SmDownArrow.png | Down arrow, smaller size, for light background colors |
 |
SmDownArrowInv.png | Down arrow, smaller size, for dark background colors |
 |
file.png | File or document |
 |
find.png | Find or search |
 |
goto.png | Go to |
 |
inspect.png | Inspect |
 |
SmLeftArrow.png | Left arrow, smaller size, for light background colors |
 |
SmLeftArrowInv.png | Left arrow, smaller size, for dark background colors |
 |
open.png | Open file, folder, or document |
 |
output.png | Output |
 |
paste.png | Paste |
 |
print.png | |
 |
redo.png | Redo previous operation |
 |
redo_g.png | Redo previous operation, grayed out |
 |
reload.png | Reload |
 |
RtArrow.png | Right arrow, larger size, for light background colors |
 |
RtArrowInv.png | Right arrow, larger size, for dark background colors |
 |
SmRightArrow.png | Right arrow, smaller size, for light background colors |
 |
SmRightArrowInv.png | Right arrow, smaller size, for dark background colors |
 |
save.png | Save file, folder, or document |
 |
save_g.png | Save file, folder, or document, grayed out |
 |
saveall.png | Save all files or documents |
 |
saveas.png | Save current file or document to a new file |
 |
undo.png | Undo previous operation |
 |
undo_g.png | Undo previous operation, grayed out |
 |
UpArrow.png | Up arrow, larger size, for light background colors |
 |
UpArrowInv.png | Up arrow, larger size, for dark background colors |
 |
SmUpArrow.png | Up arrow, smaller size, for light background colors |
 |
SmUpArrowInv.png | Up arrow, smaller size, for dark background colors |
 |
viewother.png | View other, such as the compiled routine for a class |
 |
watch.png | Watch |
 |
workspace.png | Workspace |
 |
world.png | World, as in World Wide Web |
The nameInv.png images are used automatically in place of their name.png counterparts when Zen detects that it is rendering the icon against a dark background color. name.png icons are intended for use against light background colors. This behavior can be seen in the system default color scheme for Zen, as follows:
-
The dark arrow over the light background:
-
...automatically changes to a light arrow when it is over a dark background:
-
...and changes back to a dark arrow when it is over a light background:
The switch to using light or dark icons happens automatically, as long as you define the foreground and background colors of both <csMenuItem> and <csActiveMenuItem> using CSS. This allows Zen to calculate which icon yields optimum contrast with the current color. This is important even if the foreground or background color is being created using an image to create a gradient effect, as seen in the dark blue selected items in the previous examples.
<csMenuBar>
The <csMenuBar> component may appear inside any type of group container. The <csMenuBar> element defines a horizontal menu bar with one pick for each <csMenuBarItem> that is its direct child. <csMenuBar> may contain as many sibling <csMenuBarItem> components as are required to define the choices on the menu bar. For a <csMenuBar> example, see the section “Building Client Side Menus.”
<csMenuBar> has the following attributes.
| Attribute | Description |
|---|---|
| Zen group attributes | <csMenuBar> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen. |
<csMenuBarItem>
The <csMenuBarItem> component may appear only within a <csMenuBar> container. Each <csMenuBarItem> defines one choice on the menu bar. For an example, see the section “Building Client Side Menus.”
<csMenuBarItem> has the following attributes.
| Attribute | Description |
|---|---|
| Zen group attributes | <csMenuBarItem> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen. |
| caption |
Text label to associate with this menu pick. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.captionOpens in a new tab. This makes it easy to localize its text into other languages, as long as a language DOMAIN parameter is defined in the Zen page class. The %ZEN.Datatype.captionOpens in a new tab data type also enables you to use $$$Text macros when you assign values to the invalidMessage property from client-side or server-side code. |
| contextKey | If defined, the contextKey is a single character that identifies which letter in the caption text can be pressed to invoke the functionality of the menu pick. contextKey is not case-sensitive. The contextKey character is underlined when the caption text is displayed. |
<contextMenu>
The <contextMenu> component may appear inside any type of group container, including <csMenuItem>, <vgroup>, <hgroup>, <form>, etc.
The group may contain other elements besides <contextMenu>, but to allow other elements to appear inside the group along with <contextMenu> you must set the containing group’s layout attribute to "none". In the following example, a <button> appears in addition to the <contextMenu>, so the <form> has layout set to "none":
<form height="600" width="400" layout="none" >
<button caption="MyButton"/>
<contextMenu id="cm1">
<csMenuItem caption="context"/>
<csMenuItem caption="menu"/>
<csMenuItem caption="1"/>
</contextMenu>
</form>
To understand more about how <contextMenu> may be used to specify various types of menus, see the examples in the sections “Building Client Side Menus” and “Popup or Context Menus.”
A <contextMenu> component may contain as many sibling <csMenuItem> and <csMenuSeparator> components as are required to define and organize the individual choices on the menu.
<contextMenu> has the following attributes.
| Attribute | Description |
|---|---|
| Zen group attributes | <contextMenu> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen. |
<csMenuItem>
The <csMenuItem> component may appear only within a <contextMenu> container. <contextMenu> may contain as many sibling <csMenuItem> and <csMenuSeparator> components as are required to define and organize the choices on the menu.
<csMenuItem> has the following attributes.
| Attribute | Description |
|---|---|
| Zen group attributes | In addition to its capabilities as a menu item, <csMenuItem> has the same style and layout attributes as other Zen groups. For descriptions, see “Group Layout and Style Attributes” in the “Zen Layout” chapter of Using Zen. |
| altCaption | Text to display for the menu item under alternate conditions, such as when the user toggles the menu item. The normal alternate to altCaption is caption. |
| altIcon |
URI of the image to display beside the caption text under alternate conditions, such as when the user toggles the menu item. If it is a pathname on the local server, the URI is relative to the Caché installation directory, as in: altIcon="images/cut.png" The normal alternate to altIcon is icon. For some available icons, see the section “Icons.” |
| altKey | If defined, the altKey is a keyboard shortcut that can invoke the functionality of the menu item under alternate conditions, such as when the user toggles the menu item. The normal alternate to altKey is key. |
| caption |
Text to display for the menu item under normal conditions. Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.captionOpens in a new tab. This makes it easy to localize its text into other languages, as long as a language DOMAIN parameter is defined in the Zen page class. The %ZEN.Datatype.captionOpens in a new tab data type also enables you to use $$$Text macros when you assign values to the invalidMessage property from client-side or server-side code. |
| contextKey |
If defined, the contextKey is a single character that identifies which letter in the caption text can be pressed to invoke the functionality of the menu item when it is active. contextKey is not case-sensitive: The contextKey character is underlined when the caption text is displayed. For detailed examples, see the section “Drop Down Menus.” |
| icon |
URI of the image to display beside the caption text under normal conditions. If it is a pathname on the local server, the URI is relative to the Caché installation directory, as in: icon="images/cut.png" For some available icons, see the section “Icons.” |
| iconDisabled |
URI of the image to display beside the caption text when this menu item is disabled but still visible (“grayed out).”. If it is a pathname on the local server, the URI is relative to the Caché installation directory, as in: iconDisabled="images/cut.png" For some available icons, see the section “Icons.” |
| key |
If defined, the key is a keyboard shortcut that can invoke the functionality of the menu item when it is active, bypassing the need for a mouse click: For detailed examples, see the section “Drop Down Menus.” |
| onclick |
Client-side JavaScript expression that runs each time the user clicks the mouse on this menu item. Generally this expression invokes a client-side JavaScript method defined in the page class. When providing a value for this attribute, use double quotes to enclose the value and single quotes (if needed) within the JavaScript expression. For example: <csMenuItem onclick="alert('HEY');"/> The JavaScript expression may contain Zen #()# runtime expressions. |
| toggleMode |
If defined, and true, a checkmark indicates the toggled state of the menu pick. The checkmark displays when toggleMode is true. The default for toggleMode is false. toggleMode has the underlying data type %ZEN.Datatype.booleanOpens in a new tab. It has the value "true" or "false" in XData Contents, 1 or 0 in server-side code, true or false in client-side code. |
<csMenuSeparator>
The <csMenuSeparator> component may appear only within a <contextMenu> container. <contextMenu> may contain as many sibling <csMenuItem> and <csMenuSeparator> components as are required to define and organize the choices on the menu. <csMenuSeparator> simply provides a horizontal line to separate sections of menu choices.
The <csMenuSeparator> component has no attributes. For example:
<csMenuSeparator />
For more detailed examples, see the section “Drop Down Menus.”
