A multi-button on a ribbon tab enables users to view and interact with two views simultaneously with the click of a button. An example of a suitable use case for a multi-button might be while working with a security graph and threat scenarios. You can view a security graph for a particular TARA (Threat Assessment and Remediation Analysis) while entering information about the threat scenarios via the Overview view as shown in the below example. This article describes how to configure a multi-button.
Multi-buttons are configured by an Architect. Navigate to File > Configure the explorer > Features > Item ribbon tab.
Click Edit configuration to access the ribbon configuration XML.
Explanation of the Configuration Elements
A multi-button consists of the following elements:
The <MultiButton> tag contains the configuration for one multi-button. The following attributes apply:
- caption is the button label text. This is required.
- hideIfDisabled defines if the button should be hidden if it is not active. By default, inactive buttons display with gray text. Adding hideIfDisabled="true" will hide the button itself. This is optional.
In each MultiButton, include the two actions you want to occur. The following optional sub-elements are supported in a MultiButton:
- <TreeSettings> defines the tree settings to be used.
- <OpenItem> specifies an item to be opened, in the same way as when used separately, i.e., not within a MultiButton. However, the caption attribute in <OpenItem> will not be applied since the caption is defined by the MultiButton caption attribute.
- <ItemView> specifies the view selection, in the same way as when used separately. When using a configured graph in the <ItemView> in the main view, the optional locked attribute can be used.
- <SecondaryItemView> specifies a secondary item view to be opened by the button. It has four attributes: name, configItem, locked and orientation.
- The name attribute specifies the secondary item view by its name.
- The configItem attribute works similar to configItem in <ItemView>.
- The optional locked attribute specifies if the secondary item view will be locked or not. The default value is "false".
- The optional orientation attribute specifies the position of the secondary item view. Possible values are "right", "top", or "bottom". The default value is "right".
Refer to Configure ribbon tabs in the application Help for more information on Items ribbon configuration.
In the below multi-button example, the multi-button labeled "Use Case Diagram" consists of a locked graph config item view in the default primary view position (left side) and a SecondaryItemView displaying a grid config item view in the default secondary view position (right side). Ref id is used to identify both of the config items in use.
<MultiButton caption="Use Case Diagram">
<ItemView name="XXXGraph" configItem="BIDM:DirectLink" locked="true"/>
<SecondaryItemView name="Grid" configItem="BIDM:UseCasesAndActorsList" locked="true" orientation="right"/>
Given the above layout, users can easily interact with both views. In addition, if editing is enabled in the graph view, users can copy items in the grid and paste them in the graph per the graph's configured editing options.
Updates to Config Items
Keep in mind that if you use the config item's xID in the multi-button configuration, it will always point to that specific version of the config item.
In the below example, a configuration of <ItemView name="Graph" configItem="x3400000000095C0A"/> will always point to Version 1.
If a newer version of a config item is introduced, e.g., from verison 1 to version 2, the xID will manually need to be updated in the multi-button configuration so that it will point to Version 2 of the config item.
As mentioned above under Configuration, it is possible to use a Ref Id for a configItem instead of an xID in which case the <ItemView> in the multi-button will point to the latest version of the config item. It would not need to be manually updated (unless the Ref Id were to change, of course). This option is available in version R32 or later.