Contextual Menu builder

Contextual Menu builder

In this topic ...

How Do I...?
Specifying Inputs
Objects This Builder Creates

Related Topics ...

Overview: Creating Pages
How to Use the Page Builder
Overview: Profiling

The Contextual Menu builder adds a pop-up menu to one or more pages in your model. The builder is included in the Page Controls builder category. When you add a contextual menu builder to a page, a menu and its menu items pop up when users click a specific link, button, or icon. We can also add a menu to a chart or other page element by using the Hidden (manually invoked) option. Specify the menu content when you create the builder or use indirect references to retrieve the content programmatically.
When users click a menu item, we can define an action that:

Submits the form

Executes a link to another page in the model or to an external Web page

Runs client-side JavaScript

The menu's appearance is governed by a cascading style sheet, which allows you to change the border, text color, font size, and so on.

How Do I...?

The following examples show how to create a few different types of menus.

Add a static menu list with a button control

Add a Contextual Menu builder to a page location in the model.

Select Portal-style Button as the Control Type.

Provide the Button/Link Text.

Verify the default image selection or choose another image file whose size is appropriate for a button.

Select Specify explicitly as builder input as the Menu Content.

Provide Menu Item Info by selecting Menu Item as the Type in the Menu Item Info section.
For each item, specify Text for Item, Action Type, Action, Input Mappings, and so on.
To add a horizontal rule between menu items, select Separator as the Type in the Menu Item Info section between the two menu items you want to separate.

Click OK.

Hide a menu item using profiling

Add a Contextual Menu builder to a page location in the model.

Select Portal-style Button as the Control Type.

Provide the Button/Link Text.

Verify the default image selection or choose another image file whose size is appropriate for a button.

Select Specify explicitly as builder input as the Menu Content.

Provide Menu Item Info by selecting Menu Item as the Type in the Menu Item Info section.
For each item, specify Text for Item, Action Type, Action, Input Mappings, and so on.

Click the profile icon to the left of the Menu Item you want to hide.

In the pop-up Profile window, click the profile icon next to Hide and set the profile, using the profile value "true." Click OK.
For more information about profiling, see Profiling Builder Call Inputs.

Click OK.

Create a menu that generates content through an indirect reference

Menu items can be generated through an indirect reference, such as a method, variable, or data service, as long as the reference contains schema-typed menu data. The return value of the indirect reference is an XML file. The schema of the XML is factory/xml/schemas/contextualmenu.xsd.
The indirect reference must contain these elements:

Text for the NAME element

ACTION element
Every ATTRIBUTE child of ACTION must be an HTML attribute in the result HTML. For example, if <ATTRIBUTE name="href" value="#"/>, the result HTML will be href=#.

The indirect reference may contain these elements:

ENABLE
The default value is True.

HIDE
The default value is False.

If the indirect reference contains TYPE elements, they are handled in one of two ways:

If the text of the TYPE element is not Separator, the builder sets the text of the TYPE element to the default value of "MenuItem."

If the text of the TYPE element is Separator, the builder ignores the other children of the Item element.

Follow the steps in this example to use an indirect reference to generate menu items.

Add a Contextual Menu builder to a page location in the model.

Select Portal-style Button as the Control Type.

Provide the Button/Link Text.

Select Indirect Reference as the Menu Content.

Specify an Indirect Reference value to generate menu items.

Click OK.

Add a Contextual Menu to a Web Chart

This example shows how to create a Web Chart whose data changes when users click on different areas of the chart. Through the use of HTML input controls on the page, data is passed to the back-end system, which returns the appropriate data.

Add two Hidden Input builders to a page location in the model and name them InputA and InputB.

Add a Contextual Menu builder.
Place both Hidden Input builders and the Contextual Menu builder inside a specific form (for example, myForm) if you plan to use the Submit form action for the menu.

Select Hidden (manually invoked).
The Contextual Menu can be created only once per builder call because the <Builder Name>ShowContextualMenu method, which gets the JavaScript method name used to show the contextual menu, is generated once per builder call. If more than one Contextual Menu is created (for example, by using the Advanced Page Location to place a menu in multiple locations or to place a menu inside a Repeated Region), only the first Contextual Menu on the page will be available.

Select Specify explicitly as builder input as the Menu Content.

Select Submit form and invoke action as the Action Type.

Select the action and the form.

Click OK.

In the WebCharts builder, add a Chart Click Action that uses JavaScript code to initialize values for InputA and InputB. Call <Builder Name>ShowContextualMenu to get the JavaScript method name used to show the contextual menu.
For example:
document.myForm.InputA.value='$(colLabel)';document.myForm.InputB.value='$(rowLabel)';${MethodCall/<Builder Name>ShowContextualMenu}

Click OK.

Specifying Inputs

The Contextual Menu builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see Using the builder call editor.

Input Name Description
Name Required. Enter a name for this builder call, for example, "ContextualMenu." The Designer tool displays this name in the builder call list.
Page location Required. Use the Page Location input to specify the page or pages on which this builder call will act. See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Control Type Required. Specify which page control activates the contextual menu: Portal-style Button, Link, Image only, or Hidden (manually invoked). The default value is Portal-style Button.
Button/Link Text Required. Displayed when you select Portal-style Button or Link as the Control Type. Specify the text for the button/link, for example, "Actions."
Image Required when you select Image only as the Control Type; optional for other control types. Displayed when you select Portal-style Button, Link, or Image only as the Control Type. Specify the path and file name of the image to be used with the control. The default image is /factory/images/contextualmenu/MenuDropdown.gif.
Menu Content Required. Specify how menu items are generated. If you select "Specify explicitly as builder input," you define the entries and actions as builder inputs. If you select Indirect Reference, you specify a method to generate the menu items.
Menu Items Required. Displayed when you choose Indirect Reference as the Menu Content. Click the ellipses (. . .) to use the Reference Chooser to specify a method, variable, or data service that will contain the schema-typed menu data.
Menu Item Info
Type (for menu content that is categorized as "Specify explicitly as builder input") Required for each row in the Menu Item Info list. The value is either Menu Item or Separator. Menu Item adds an entry to the menu. Separator adds a horizontal line that separates menu items. The default is Menu Item.
Text for Item
(for menu content that is categorized as "Specify explicitly as builder input")
Required if you select "Specify explicitly as builder input" as the Menu Content. Specify the label for the menu item.
Action Type
(for menu content that is categorized as "Specify explicitly as builder input")
Defines the behavior of the action. Choose an action type based on the action that will process the onClick event and whether you want to process any form inputs as part of that action.
Submit form and invoke action - Choose this option if the specified action is a method in the model or LJO and that method processes the inputs to the form on which the menu item resides.
Submit form and invoke URL - Choose this option if the specified action that will process the inputs to a form is a URL outside of Designer. The specified URL receives the form input values as name/value pairs appended to the URL.
Link to an action - Choose this option if the specified action is a method in the model or LJO (including Service Calls) that acts as a simple link, transferring control directly to the specified URL. The specified action cannot process any form inputs.
Link to a URL - Choose this option if you want to navigate to a non-Designer URL. The URL cannot process any form inputs.
Run a script - Choose this option if you want this action to run some client-side JavaScript when a user clicks a menu item. The script cannot process any form inputs.
Action
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when you select Submit form and invoke action or Link to an action. Use the Action chooser to select which action to perform.
URL
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when you select Submit form and invoke URL or Link to a URL. Specify the URL to execute when the user clicks the menu item.
Form Name
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when you select Submit form and invoke action or Submit form and invoke URL. If the builder is in one form or frame and the form to be submitted is in another, enter the name of the form whose inputs you want to submit.
Input Mappings
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when you select Submit form and invoke action, Submit form and invoke URL, Link to an action, or Link to a URL. We can pass arguments to the specified action by adding argument names and the value to be passed to them. Click the ellipses (. . .) to use the Reference Chooser to specify input values or values returned by methods or service calls as the value to be passed to an argument for the specified action.
Evaluate arguments
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when the action you specify takes an argument. Select either When the action is run or As the page is rendered. See Passing arguments to actions for more information.
Script to Execute
(for menu content that is categorized as "Specify explicitly as builder input")
Optional. Displayed when you select Run a script. Specify the JavaScript to link to when the specified event occurs.
Note that Do not use comments in the script you specify. The script you specify is added as one line, so any code following comments is ignored.
Enable Rule
(for menu content that is categorized as "Specify explicitly as builder input")
Required. Select one of the listed rules with which to enable the menu item:
Always Enable - The menu item is enabled under all conditions. This is the default value.
Enable when Value is "true" - Enables the menu item when the selected value returns a condition of true.
Enable when Value equals Comparison Value - Enables the menu item when Value and Comparison Value are equal.
Enable when Value does not equal Comparison Value - Enables the menu item when Value and Comparison Value are not equal.
Never Enable (used for profiling) - Disables the menu item.
Value Required. Displayed when you select Enable when Value is "true." Specify the value to be used or click the ellipses (. . .) to use the Reference Chooser to choose a value.
Comparison Value Required. Displayed when either Enable when Value equals Comparison Value or Enable when Value does not equal Comparison Value is selected as the Enable Rule. Specify the Comparison Value to be used or click the ellipses (. . .) to use the Reference Chooser to choose a value.
Appearance
Position of Contextual Menu items Required. Displayed when you select Portal-style Button, Link, or Image only as the Control Type. Specify where the menu items will pop up relative to the menu control: Left, Right, Left Bottom, Right Bottom. The default value is Right.
Advanced
Base HTML File Required. Select a base HTML page that contains the HTML and JavaScript code that is used to generate the contextual menus. The default file is /factory/pages/contextual_menu.jsp.
Stylesheet Optional. Select a style sheet containing custom .css classes that define the look and feel of the contextual menu. The default style sheet is /factory/pages/contextual_menu.css.

Objects this builder creates

This builder creates a variety of objects within the WebApp. They include the following items:

Linked Java objects

IBM_Workplace_Dashboard_ContextualMenu_IDHelper - A linked Java object that includes createNewID() and getCurrentID() methods, used for assigning unique IDs to each contextual menu item.

Pages

<buildername>_ContextualMenu - This page contains the menu item body.

Methods

CMGetContextualMenuID - This method is created only when you select "Hidden (manually invoked)" as the Control Type. The method returns the ID of the contextual menu.

CMShowContextualMenu - This method is created only when you select "Hidden (manually invoked)" as the Control Type. The method returns the JavaScript function name. Calling this method in JavaScript pops up the contextual menu.

Input Name	Description
Name	Required. Enter a name for this builder call, for example, "ContextualMenu." The Designer tool displays this name in the builder call list.
Page location	Required. Use the Page Location input to specify the page or pages on which this builder call will act. See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Control Type	Required. Specify which page control activates the contextual menu: Portal-style Button, Link, Image only, or Hidden (manually invoked). The default value is Portal-style Button.
Button/Link Text	Required. Displayed when you select Portal-style Button or Link as the Control Type. Specify the text for the button/link, for example, "Actions."
Image	Required when you select Image only as the Control Type; optional for other control types. Displayed when you select Portal-style Button, Link, or Image only as the Control Type. Specify the path and file name of the image to be used with the control. The default image is /factory/images/contextualmenu/MenuDropdown.gif.
Menu Content	Required. Specify how menu items are generated. If you select "Specify explicitly as builder input," you define the entries and actions as builder inputs. If you select Indirect Reference, you specify a method to generate the menu items.
Menu Items	Required. Displayed when you choose Indirect Reference as the Menu Content. Click the ellipses (. . .) to use the Reference Chooser to specify a method, variable, or data service that will contain the schema-typed menu data.
Menu Item Info
Type (for menu content that is categorized as "Specify explicitly as builder input")	Required for each row in the Menu Item Info list. The value is either Menu Item or Separator. Menu Item adds an entry to the menu. Separator adds a horizontal line that separates menu items. The default is Menu Item.
Text for Item (for menu content that is categorized as "Specify explicitly as builder input")	Required if you select "Specify explicitly as builder input" as the Menu Content. Specify the label for the menu item.
Action Type (for menu content that is categorized as "Specify explicitly as builder input")	Defines the behavior of the action. Choose an action type based on the action that will process the onClick event and whether you want to process any form inputs as part of that action. Submit form and invoke action - Choose this option if the specified action is a method in the model or LJO and that method processes the inputs to the form on which the menu item resides. Submit form and invoke URL - Choose this option if the specified action that will process the inputs to a form is a URL outside of Designer. The specified URL receives the form input values as name/value pairs appended to the URL. Link to an action - Choose this option if the specified action is a method in the model or LJO (including Service Calls) that acts as a simple link, transferring control directly to the specified URL. The specified action cannot process any form inputs. Link to a URL - Choose this option if you want to navigate to a non-Designer URL. The URL cannot process any form inputs. Run a script - Choose this option if you want this action to run some client-side JavaScript when a user clicks a menu item. The script cannot process any form inputs.
Action (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when you select Submit form and invoke action or Link to an action. Use the Action chooser to select which action to perform.
URL (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when you select Submit form and invoke URL or Link to a URL. Specify the URL to execute when the user clicks the menu item.
Form Name (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when you select Submit form and invoke action or Submit form and invoke URL. If the builder is in one form or frame and the form to be submitted is in another, enter the name of the form whose inputs you want to submit.
Input Mappings (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when you select Submit form and invoke action, Submit form and invoke URL, Link to an action, or Link to a URL. We can pass arguments to the specified action by adding argument names and the value to be passed to them. Click the ellipses (. . .) to use the Reference Chooser to specify input values or values returned by methods or service calls as the value to be passed to an argument for the specified action.
Evaluate arguments (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when the action you specify takes an argument. Select either When the action is run or As the page is rendered. See Passing arguments to actions for more information.
Script to Execute (for menu content that is categorized as "Specify explicitly as builder input")	Optional. Displayed when you select Run a script. Specify the JavaScript to link to when the specified event occurs. Note that Do not use comments in the script you specify. The script you specify is added as one line, so any code following comments is ignored.
Enable Rule (for menu content that is categorized as "Specify explicitly as builder input")	Required. Select one of the listed rules with which to enable the menu item: Always Enable - The menu item is enabled under all conditions. This is the default value. Enable when Value is "true" - Enables the menu item when the selected value returns a condition of true. Enable when Value equals Comparison Value - Enables the menu item when Value and Comparison Value are equal. Enable when Value does not equal Comparison Value - Enables the menu item when Value and Comparison Value are not equal. Never Enable (used for profiling) - Disables the menu item.
Value	Required. Displayed when you select Enable when Value is "true." Specify the value to be used or click the ellipses (. . .) to use the Reference Chooser to choose a value.
Comparison Value	Required. Displayed when either Enable when Value equals Comparison Value or Enable when Value does not equal Comparison Value is selected as the Enable Rule. Specify the Comparison Value to be used or click the ellipses (. . .) to use the Reference Chooser to choose a value.
Appearance
Position of Contextual Menu items	Required. Displayed when you select Portal-style Button, Link, or Image only as the Control Type. Specify where the menu items will pop up relative to the menu control: Left, Right, Left Bottom, Right Bottom. The default value is Right.
Advanced
Base HTML File	Required. Select a base HTML page that contains the HTML and JavaScript code that is used to generate the contextual menus. The default file is /factory/pages/contextual_menu.jsp.
Stylesheet	Optional. Select a style sheet containing custom .css classes that define the look and feel of the contextual menu. The default style sheet is /factory/pages/contextual_menu.css.