Harness, section, and flow action forms forms
Completing the Layout tab — Adding a Menu Bar

Create an XML Stream rule in your application that defines the structure and elements of the menu.

1. Set the first key part to @baseclass. Enter a second key part of your choice. Set the third key part (XML Type) to Menus.

2. On the XML tab, clear the Auto-generated XML? option.

3. In the XML Source field, enter text to define a well-formed XML structure similar to the following:

<?xml version="1.0" ?>
<pagedata>
 <menu value="MenuHome" rows="2" Tooltip= "Return to Home" >
     <item value="HomePage" caption="Home"      OnClick="pega.desktopshowSpace('Home');" ></item>
     <item ...></item>
 </menu>
 <menu>
 ....
 </menu>
</pagedata>

Where:

• <menu ....> elements identify the top-level menu choices, and can appear only at the second level of the XML structure, as in this example. For each <menu > element, define a Tooltip text value and a positive integer rows value. The rows attribute controls the runtime vertical spacing of menu items; set it to at least the maximum number of subordinate menu entries.
• <item ...> elements identify second or deeper levels of menu choices. Each item has one of two types: it can surround other <item..> elements at a deeper level, or it can execute a JavaScript function. Items may have four attributes: value, Caption, Tooltip, and OnClick. (Bottom-level <item > elements must have an OnClick reference to a JavaScript function. (The JavaScript functions themselves are defined in a text file rule, specified elsewhere.)
• To allow users to switch to a specific space in a composite portal, use OnClick="pega.desktop.showSpace('Sname')" where Sname is the name of the space, as entered on the Spaces tab of the portal rule.
  

Items that do not include an onClick attribute define groupings of menu items at a subordinate level. Your menu many contain several levels; there is no imposed limit.

Ensure that the value attributes are unique within each level; these are keys for nodes in a key structure of other XML Stream rules with MenuItem as the final key part.

4. Save the XML Stream rule.

5. Create and save any additional XML Stream rules referenced through the value attribute of the primary menu. Set the third key part of these to MenuItem. A MenuItem XML Stream rule defines a (well-formed) XML fragment, not an entire document. The simple structure is:

<Item Value="myvalue" Caption="mycaption" onClick="function" />

where:

• mycaption is the user-visible text that appears in the menu choices.
• myvalue is a unique text string identifying this item .
• function defines a JavaScript call that defines the result of selecting the menu option. The onClick() target references a JavaScript function such as pega.desktop.showSpace(), or others in the standard text file rules webwb.DesktopWrapperAPI.js or — for advanced cases — webwb.MenuActionHandlers.js.

The XML Stream rule may contain JSP tags such as <pega:when >, <pega:reference > and <pega:include >. Menus may contain submenus up to five levels deep.

Examples

For examples of menu structure, review the XML Stream rules that define the Developer portal menus: @baseclass.DeveloperMenuTools.Menu, @baseclass.DeveloperMenuFile.Menu, and so on. Open the highest version of each rule. These top-level menus reference other standard XML Stream rules in the Pega-ProCom RuleSet with MenuOption as the final key part. (These are advanced, special-purpose examples and cannot be used directly in a composite portal.)

Create a section rule to hold the menu.

A new section contains an initial layout, in Smart Layout format. From the Layout tab, select an add a second layout, of type Free Form with one row and one column, below the Smart Layout. Delete the Smart Layout.

Drag to adjust the width and height of the cell to hold the expanded menu display. Using default styles, each menu row (or tab) requires about 30 pixels of height. You can fine-tune the cell size later.

Click the down-arrow () at the right end of the Advanced control group () and select the menu bar control (). Drag the control. When the pointer changes shape to indicate that you can drop the layout, release the mouse button.

Parameters to the standard HTML property rule MenuBar control the menu display.

Field	Description
Property	Retain the placeholder property pyTemplateMenuBar. (This property is not used.)
Display As	Retain the default HTML property rule MenuBar. Click the magnifying glass icon ( ) to enter parameters for the menu. Complete the following parameters: Parameter Description Render Mode Select simple to present each menu item in a cell. tabbed to present each menu item as a tab. Action Select XML. (The Activity option is reserved.) Class Name Optional. Identify the Applies To key part of the XML Stream rule that defines the top of the menu structure. If blank, the system uses the Applies To key part of the section rule. Name Identify the Stream Name key part of the XML Stream rule. XML Type Identify the XML Type key part of the XML Stream rule, usually Menus. Alignment Select: vertical — Top-level menu choices appear in a column, the second level and lower choices exploding to the right. (This value is ignored if the Render Mode parameter value is tabbed. horizontal — Top-level choices are presented horizontally. Second level and lower choices appear below (or above) the top-level choices. Style Prefix Optional. Leave blank unless you have defined custom styles for the menu using a prefix, as described below. Extension Class Optional. If your menus call custom JavaScript functions defined in an HTML rule, identify the Applies To key part of the HTML rule. Extension Name Optional. If your menus call custom JavaScript functions defined in an HTML rule, identify the Stream Name key part of the HTML rule.
Behavior	Leave blank. Not used.

The General tab controls when the menu is visible. In most cases, accept the default values; the menu is always visible.

Field	Description
Visible	Select to determine when the menu appears. Select: Always — To have the menu appear or be hidden based on the visibility of the enclosing section when the form is first presented or is refreshed. This condition is checked only once. Other Condition — To make the visibility depend on a when condition rule, a Boolean expression evaluated only once, or a test evaluated repeatedly upon JavaScript events. If Not Blank — Not used for menu bars. If Not Zero — Not used for menu bars.
Condition	If you selected Other Condition for the Visible field, complete this field. Enter an expression involving another property, or identify the When Name key part of a when condition rule. Specify one of three outcomes: When condition rule — Enter the When Name key part of a when condition rule that determines the visibility of this field at runtime. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule. Click the pencil icon () to review or create the when condition rule. Expression evaluated once — Enter an expression that returns true or false. This expression can involve multiple properties, function calls, and other syntax as supported by the <pega:when > JSP tag. Simple Java expression evaluated upon JavaScript events — To dynamically control the visibility of this property with a JavaScript event, enter a simple comparison involving a target property and select the Run on Client? box. The result at runtime determines whether the content of this cell appears in read-only mode or in the mode of the enclosing layout. For example, enter .Color =="Blue" in this field to make this field visible when the property Color has the value Blue, and invisible otherwise. Depending on the state of the Run on Client check box, the comparison can be executed only once as the form is initially displayed, or dynamically. See Implementing dynamic form actions and the Client Event Editor. A menu that is not visible is also disabled and cannot be accessed.
Required	Not used for menu bars.
Wrap Text	Not used for menu bars.
Read-Only	Not used for menu bars.

Style information on the Advanced tab is not meaningful for menu bars.

Field	Description
Default Value	Leave blank.
Width	This field appears only when the cell is not controlled by Smart Layout column restrictions. Enter a positive number for the width in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed width.) You can also adjust the width this column directly: Click a vertical wireframe cell border. Wait until the pointer shape changes (), then drag the border.
Height	Optional. This field appears only when all columns in the Layout are not controlled by Smart Layout column restrictions. Enter a positive number for the height in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed height.) You can also adjust the height of a row directly: Click a horizontal wireframe cell border. Wait until the pointer shape changes (), then drag the border.
Read-Write Style	Not used.
Read-Only Style	Not used.
Inline Style	Not used.
Use Heading Styles	Not used.

Test

1. Save the section rule.
2. Add this section rule to the harness rules that define the spaces of the composite portal. (Typically, the menu appears in the same panel location — for example Top — in each space.)
3. Add the composite portal to your access group.

Refine the menu structure

You can extend the XML Stream rules to take advantage of four features that make the menu bar facility flexible and powerful:

• The XML code can include JSP tags such as <pega:include > and <pega:when > to make the menu options depend on clipboard values.
• The XML code can contain Java expressions (within <% and %> delimiters ) that access parameters, call function rules and PublicAPI functions.
• The onClick= JavaScript code can construct and send a URL that executes an activity with supplied parameters.
• Rule resolution operates during stream processing of <pega:include> JSP tags to retrieve the appropriate XML rule depending on the user's RuleSet list.

Refine menu styles

Standard menu styles are defined by the text file rule webwb.pega_yui_menu.css, a final rule. To override these and use custom styles in your menu:

1. Choose a short alphabetic code to serve as a consistent style prefix, for example MYCO.
2. Copy this CSS file into a text file rule in an application RuleSet version. Use webwb for the first key party, MYCO_yui_menu for the File Name key part, and css for the File Type key part.
3. Edit the CSS files, adding the prefix to each class definition that starts with "menu". For example, change menuBar to MYCOmenuBar.
4. Update the class definitions as desired, adjusting fonts, colors, background and so on. Save the text file rule.
5. Return to the section rule. Access the Cell Properties panel of the menu. Open the parameters window for the MenuBar HTML property. Set the Style Prefix parameter value. Save the panel and the section rule.
6. Update each harness rule that includes the section containing the menu ba. List the text file rule on the Scripts and Styles tab.
7. Retest to confirm that the updated, prefixed menu styles, not the default styles, are in use.