Developing Zen Applications
Client Side Menu Components
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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.

Note:
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.
File Drop Down Menu with Icons and Keyboard Shortcuts
<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.
Edit Drop Down Menu with Icons and Keyboard Shortcuts
Menu Picks or Choices
Zen client side menus support the following types of menu pick:
Type of Pick User Action Result
Regular menu Click
Zen invokes the callback specified by the onclick attribute.
You can define a regular menu pick with just a caption and an onclick callback, but you can also add an icon, or a keyboard shortcut using key or contextKey. For example:
For some images that you can use in menu picks, see the section Icons.”
Cascading menu Roll over
Zen displays a submenu.
You can cascade menus by nesting <contextMenu> elements within <csMenuItem> elements. See the examples in the sections Building Client Side Menus and Popup or Context Menus.”
Alternating caption Click
Zen invokes the callback specified by the onclick attribute. The toggleState property flips its value (from 0 to 1 or from 1 to 0) when the user clicks the menu pick. The caption label changes automatically, as in “Show” vs. “Hide.”
For an alternating caption pick, define both a caption and an alternate caption (altCaption) as shown in the following example:
Optionally, you can also specify an icon and altIcon so that the icon can be toggled along with the caption.
A toggleState of 0 displays the caption and icon; 1 displays the altCaption and altIcon. The toggleState changes only in response to user actions.
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.
Popup Menu with Submenus
Cascading Menus
You can cascade menus by nesting <contextMenu> elements within <csMenuItem> elements. This cascading technique works for regular menus as well as for popup or context menus. See the examples in the opening section of this chapter, Building Client Side Menus,” and in the previous section, Popup or Context Menus.”
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.
Button Bar with Icons
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"
Zen Icon Library
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 Print
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:
  1. The dark arrow over the light background:
  2. ...automatically changes to a light arrow when it is over a dark background:
  3. ...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.caption. 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.caption 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:
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.caption. 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.caption 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:
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:
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:
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.boolean. 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.”
<buttonBar>
The <buttonBar> component may appear inside any type of group container. <buttonBar> may contain as many sibling <buttonBarItem> components as are required to define the choices on the button bar. For an example, see the section Button Bars.”
<buttonBar> has the following attributes.
Attribute Description
Zen group attributes <buttonBar> 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.
<buttonBarItem>
The <buttonBarItem> component may appear only within a <buttonBar> container. Each <buttonBarItem> defines one choice on the button bar. For an example, see the section Button Bars.”
<buttonBarItem> has the following attributes.
Attribute Description
Zen component attributes
<buttonBarItem> has the same general-purpose attributes as any Zen component. For descriptions, see these sections:
caption
If defined, this is the rollover tooltip to display when button is enabled
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. 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.caption data type also enables you to use $$$Text macros when you assign values to the invalidMessage property from client-side or server-side code.
icon
URI of the image to display when the button is enabled. If it is a pathname on the local server, the URI is relative to the Caché installation directory, as in:
For some available icons, see the section Icons.”
iconDisabled
URI of the image to display when the button 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:
For some available icons, see the section Icons.”
onclick
Client-side JavaScript expression that runs each time the user clicks the mouse on this button. 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:
The JavaScript expression may contain Zen #()# runtime expressions.