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

Advanced feature In a composite portal, a menu bar can allow the user to switch among spaces. In a flow action or sections within a user form, a menu bar can execute activities or call JavaScript functions.

The structure of a menu bar is defined by a navigation rule. Because the navigation rule undergoes stream processing and can reference clipboard property values, the runtime menu choices available may differ based on user and context.

Menu Bar example

Follow these steps to include a menu bar in a composite portal. This facility depends on rules of various types:

One or more hand-crafted Navigation rules define the structure of the menu and the actions that result from leaf-level menu choices
The standard Control rule MenuBar.
JavaScript functions, saved as a text file rule.
Optionally, a style sheet saved as a text file rule.
A section or harness that contains the control
A composite portal that defines the spaces. (See How to create a composite portal.)

1. Define the menu structure with a Navigation rule

Create a new navigation rule in that defines the structure and elements of the menu. (See About Navigation rules)

2. Drag and drop the Menu control into a section

Create a section to hold the menu.

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

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.

3. Complete the Cell Properties panel — Top fields

Parameters to the standard Control rule MenuBar control the menu display.

Field

Description

Property

Retain the placeholder property pyTemplateMenuBar. (This property is not used.)

Control

Retain the default Control rule MenuBar. Click the magnifying glass icon ( Pencil ) to enter parameters for the menu. Complete the following parameters:

Parameter	Description
`ID`	Enter a unique alphabetic identifier for JavaScript use.
`Render Mode`	Select `simple` to present each menu item in a cell. `tabbed` to present each menu item as a tab.
`Action`	Select `Navigation.` (The `Activity` and `XML` options are reserved.)
`Name`	Required. Identify the Name key part of the Navigation rule.
`Content Page`	Required. Identify the page name that contains the output of the navigation rule.
`Menu 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.
`Sub-menu Alignment`	Select: `Left` — Submenus are aligned to the left of the main menu. `Right` — Submenus are aligned to the right of the main menu.
`Maximum Text Length`	Specify the maximum length in characters to be displayed for each menu node.
`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.

4. Complete the Cell Properties panel — General tab

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 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 checkbox, 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.
Edit Options	Select an edit mode for this control. The edit mode of the control takes precedence over section and harness settings. `Auto` — the control uses the edit mode of the section or harness in which it appears. If the section is set to Read Only, then the control is Read Only. If the section is set to Auto, then the control uses the edit mode of the harness. For example, a New harness is editable, while a Review harness is read only. `Editable` — the control is editable, regardless of the edit mode of the enclosing layout. For example, a search box on a Review harness. `Read Only` — the property value displays in read-only mode always, or based on a when condition rule or client-side test, even when the enclosing layout is in read-write mode.
Required	Not used for menu bars.
Wrap Text	Not used for menu bars.
Read-Only	Not used for menu bars.

5. Complete the Cell Properties panel — Advanced tab

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 SmartLayout 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 SmartLayout 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.

6. Test and refine

Test

Save the section.
Add this section to the harnesses that define the spaces of the composite portal. (Typically, the menu appears in the same panel location — for example Top — in each space.)
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:

Choose a short alphabetic code to serve as a consistent style prefix, for example MYCO.
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.
Edit the CSS files, adding the prefix to each class definition that starts with "menu". For example, change menuBar to MYCOmenuBar.
Update the class definitions as desired, adjusting fonts, colors, background and so on. Save the text file rule.
Return to the section. Access the Cell Properties panel of the menu. Open the parameters window for the MenuBar control. Set the Style Prefix parameter value. Save the panel and the section.
Update each harness that includes the section containing the menu bar. List the text file rule on the Scripts and Styles tab.
Retest to confirm that the updated, prefixed menu styles, not the default styles, are in use.

About Flow Actions

About Harnesses

About Sections

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

Field

Description

Parameter

Description

Field

Description

Field

Description

Test

Refine the menu structure

Refine menu styles

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