You are here: User interface > User interface rules > Harness forms > Harness forms - Adding a Menu Bar

Harness and Section forms
Completing the Design tab — Adding a Menu Bar

Note: This control is deprecrated in Pega Platform.

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.

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.

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.

From the Advanced control group, 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

General tab

Field	Description
Property	Retain the placeholder property pyTemplateMenuBar. (This property is not used.)
Label	Select this check box to use the default label for the property. If this check box is cleared, in the field that appears, select or create a label.
Label format	Select a format from the available options.
Default value	Optional. Enter a constant value for the property value, a property reference, or an expression, to be used only when the user form or flow action form appears in read-write mode rather than read-only mode. Click the Gear icon to start the Expression Builder. Choose a default value that speeds data entry. When the system renders a harness or section in read-only mode (for example because the read-write mode requires a privilege that the current user does not hold), the default value does not appear, because data entry is not permitted.
Visibility	Select to determine when the property value is to appear. `Always` is the default. (If this setting is not applicable, the cell contents are blank.) Choose `Always, If Not Blank`, or `If Not Zero` to have the field appear or be hidden based on the property value at the time this area of the user form (section or flow action) is first presented or refreshed. This condition is checked only once. Choose `Other Condition` to make the visibility depend on a when condition rule or a Java expression. Select the Reserve space when hidden check box, if it appears, to have a blank area appear in the section when the paragraph is hidden. Caution: Do not make an input field invisible if your application expects user input on the field. When a user submits an HTML form, an input field that is not visible is not included in the HTTP details.

Select the Required check box to make this a required field.

Presentation tab

Field

Description

Edit Options

Select an edit mode for this control. The edit mode of the control, specified here, 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.
Read Only — the property value is presented 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.

Advanced Options

Note: As a best practice, define custom styles in the skin.

Cell read-write style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode.
Cell read-only style — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode.
Cell inline style — Type CSS code to define an inline style. As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

Parameters tab

Note: Configuring parameters for this deprecated control is only supported in Internet Explorer.

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

You can define styles for menu bars in the skin. You can also create custom menu formats in the skin. See Skin form — Components tab — Controls — Menus.

Applying a custom menu format

Add a menu bar control to your layout.
Click the Gear icon to open the cell Properties panel and then click the Open icon beside the Control field to open the Menu Bar Parameters dialog.
In the Format field, press the down arrow to select the custom format that you want to apply.