A merge button on a ribbon tab enables users to navigate through a structure without having to select different views themselves for different item types in a tree. With a merge button, you create a separate item view for each level (item type) of interest and with the click of one button, users can then move through a structure and are presented with a view specific to the item they currently have selected. 


An example of a suitable use case for a merge button is a large structure where a graph covering the entire structure is just too large to handle or does not easily zero in on a particular focus area. Separate graph configurations could be set for each item type in a sub-structure so users can easily zoom in on the different levels of interest in the graph. This article describes how to configure a merge button. 


Prerequisites

Configuration

Merge 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 merge button consists of the following elements: 


The <MergeButton> tag contains the configuration for one merge button that includes alternative <ItemView> views activated by that one button. The view that will be used when the button is clicked will be the first view that matches the selected item type. The following attributes apply: 

  • caption is the button label text. This is required.
  • image is used to add an icon. This is required.
  • hint is optional and defines a hint or tool-tip to be displayed when the cursor is positioned on the button. 
  • visibility defines the dynamic behavior in the same way as it does for ItemView.
  • 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.

In each <MergeButton>, include one <ItemView> tag for each config item to be included. 

The following attributes are required in each <ItemView> tag: 

  • name is the name of the view (or Extension view) according to the 'Name' column on the Item views tab in Configure the explorer.
  • configItem is the xID of the config item. Note that if running version R32 or later, you have the option to use a Ref id for the config item instead of the xID. The benefit of this is that is does not need to be updated should a new version of the config item be made. 


Refer to Configure ribbon tabs in the application Help for more information on Items ribbon configuration.


Example ItemView configItems

Using Ref Id

<ItemView name="Chart" configItem="JTSP:ConfigItemName"/>

Using xID

<ItemView name="Chart" configItem="x0400000000005A19"/>


Support for Multiple Config Item Types

A merge button does not have to consist of only one type of config item, e.g., grids, graphs, charts, etc. You can include any of the config types: 


<MergeButton caption="Safety " image="104">

    <ItemView name="Grid" configItem="x3400000000001CD2"/>

    <ItemView name="Report" configItem="x3400000000001D1B"/>

    <ItemView name="Chart" configItem="JTSP:ConfigItemName"/>

</MergeButton>   


Example MergeButton

<MergeButton caption="DAGraphs" image="8">      
  <ItemView name="XXXGraph" configItem="x3400000000095C0A"/> 
  <ItemView name="XXXGraph" configItem="x340000000009F40F"/>
  <ItemView name="XXXGraph" configItem="x34000000000956B9"/> 
</MergeButton>

When users click the DAGraphs button that is configured above and navigate between the three item types in the tree, the view will update automatically for them. 

In the above example, each of the three configItems in the configuration are for different item types in the database. The first ItemView is for the item type of 'Design architecture', the second is for the item type of 'Unallocated design' and the third is for the item type of 'Allocated design' although, in the configuration itself, they do not need to be listed in this order. A merge button should contain only one configItem per item type. If, by chance, there are more than one configItems included for one given item type, the one listed first in the configuration will apply.

Updates to Config Items

Keep in mind that if you use the config item's xID in the merge 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 merge 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 merge 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.