How to extend the Developer portal menu with add-ons

Using XML Stream rules, you can add items to the menu structure of the Developer portal. Your menu choices appear in the Tools > Add-ons menu group.

Don't confuse this facility, which extends the Tools menu on the Developer portal, with the general-purpose menu bar control used in composite portals. The XML Stream rules for both facilities follow the same syntax, but the menu bar is for user portals, not the Developer portal. For the menu bar, see Harness, section, and flow action rules — Adding a menu bar.

Menu structure

Process Commander builds the menus that a developer experiences from four sets of XML Stream rules. All have @baseclass as the first key part. At runtime, stream processing evaluates JSP tags to produce the menu structure displayed in a portal.

• The standard rule @baseclass.DeveloperMenus.Menus defines the names and order of the top-level menus in a portal. The menu rules are final.
• Top-level menus (such as File, Tools, and so on) are defined by standard XML Stream rules with Menus as the third key part. For example, the XML Stream rule named @baseclass.DeveloperFileMenu.Menu defines the File menu in the Developer portal. (The Developer menu rules are final.)
• Standard menu items referenced in a top-level or second-level menu are defined by standard XML Stream rules with MenuItem as the third key part. For example, the XML Stream rule @baseclass.MyProfile.MenuItem defines the operation of the Edit > My Profile menu option.
• Your custom add-ons are defined by XML Stream rules with MenuAddon as the third key part. For example, you can define a menu add-on through an XML Stream rule named @baseclass.SearchGoogle.MenuItem.

Syntax

An add-on menu 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 Tools > Add-ons menu choices.
• myvalue is a unique text string identifying this add-on.
• function defines a JavaScript call that defines the result of selecting the menu option. The onClick() target references a JavaScript function in the standard text file rules webwb.DesktopWrapperAPI.js or — for advanced cases — webwb.MenuActionHandlers.js, or an HTML fragment rule identified in the Menu HTML Fragment field on the Options tab of the Portal form.

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.

Four features make this simple structure flexible and powerful:

• The XML code can include JSP tags such as <pega:include > and <pega:when > to make the menu option 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 users RuleSet list.

Example

An XML Stream rule named @baseclass.MarthasFavorites.MenuItem contains the following XML code:

<Item Value="MarthasFavorites"
   Caption="Martha report "
    onClick="showListInWindow('Data-Rule-Summary',
   'MJFavorite','true',Refresh')" />

When the developer selects Tools > Addons > Martha Report, the JavaScript function showListInWindow() executes the list view report named Data-Rule-Summary.MJFavorite.ALL and displays the resulting report output.

Building a menu Add-on

1. Identify or build, and test, the processing that is to occur when a developer chooses the menu add-on.
2. Create the XML Stream rule with @baseclass as the first key part and MenuItem as the final key part.
3. Log out and log back in. Confirm that the new menu add-on appears under the Tools > Add-ons menu item.
4. Test.

Call the JavaScript function showListInWindow() to present a list view report. Call the JavaScript function openUrlInWindow() to execute an activity.

• For descriptions of these and other built-in functions, select the Help > API > Desktop menu item and examine the DesktopWrapper and MenuActionHandler packages.
• To examine the source code, open the standard text file rules webwb.MenuActionHandlers.js and webwb.DesktopWrapperapi.js.

Example

See Pega Developer Network article PRKB-25061 How to extend the Developer portal menus.

Menu customizations in V5.1 to V5.3

Version 5.4 introduces the add-on approach presented above. If you built customized Developer portal menus in older versions, your customizations are unlikely to work in V5.4. Revise them by following the instructions in this topic.

	stream processing
	About JavaServer Pages tags About Portal rules About XML Stream rules

User Interface category