Configuration of the dynamic ribbon tabs is done via the Features tab in Configure the explorer. This article explains where to configure the feature and provides an explanation of all of the available configuration elements. Links to configuration examples are also provided.
- Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
- Familiar with the SystemWeaver Explorer Interface and common operations
- An installation of the SystemWeaver Explorer client (swExplorer)
- Knowledge of XML
- Assignment of the SW Architect role in the server
- Introduction to Item Ribbon Tab Configuration
To begin, navigate to File > Configure the explorer > Features > Item ribbon tab.
If you are starting from scratch, you may find it helpful to copy the example found by clicking View example XML and use it as your starting point. The example is shown below.
<ItemRibbonTabConfig> <Contexts> <Context caption="context1" color="Black"/> </Contexts> <ItemTabs> <ItemTab caption="tab-caption" context="context1"> <RibbonGroups> <RibbonGroup caption="group1"> <ItemView name="TestSpecConnectRequirements"/> <ItemView name="Overview" visibility="Dynamic" hideIfDisabled="true"/> <ItemView name="Coverage" configId="1"/> <ItemView name="Coverage" configItem="x1234123412341234"/> <MultiButton> <ItemView name="Overview"/> <SecondaryItemView name="Overview"/> </MultiButton> <MultiButton> <ItemView name="Parts"/> <SecondaryItemView name="Overview" locked="true" orientation="right"/> </MultiButton> <OpenItem id="x1234123412341234" caption="" treeSettings=""/> <TreeSettings name="Requirements"/> </RibbonGroup> </RibbonGroups> </ItemTab> </ItemTabs> </ItemRibbonTabConfig>
Click Edit configuration to access the ribbon configuration XML editor.
Enter your configuration there and click Save or OK when done. All available configuration elements are described below.
Note: To refresh an existing configuration that has been modified, log out and back in to the swExplorer. If a new version of a config item button is created, click Save to refresh the ribbon button for users.
Explanation of the Configuration Elements
The <ItemRibbonTabConfig> tag builds the structure of the Item Ribbon Tab configuration. All configuration elements must be included here. This is required.
<Contexts> can include one or more tab contexts. Tab contexts appear above the standard tab row in the swExplorer as shown above. If configured, tab contexts are always visible to users and cannot be hidden. Contexts are optional.
<Context> includes the configuration of one tab context. Available attributes:
- caption: defines the name of the tab context that will display as the background for the configured tabs. This is optional.
- color: defines the background and text color of the tab context caption. See Defining Color in Configurations. This is required.
<ItemTabs> can include one or more <ItemTab> ribbon tabs.
<ItemTab> defines one ribbon tab. Note: It is also needed if you wish to add any of the options that require an item ribbon configuration, e.g., multi-button, merge button, item link, etc., to the standard Items ribbon tab.
- caption: defines the name of the ribbon tab.
- context: used to link the ItemTab to the specific <Context> in which the Item tab should appear. If this attribute is omitted, the item tab will be located in the context of the standard Items tab. See example configurations.
<RibbonGroups> defines the structure of the ribbon into one or more <RibbonGroup> menu groups.
<RibbonGroup> defines one menu group on a ribbon tab.
- caption: defines the name of the group seen on the ribbon tab. This is required.
- merge: If you plan to have more than one ribbon group with the same caption, you can use this optional attribute to indicate if the definition of a ribbon group should be merged with any existing ribbon group with the same name, including standard groups found on the Items ribbon tab. Possible values are "false" (default) or "true". "false" will clear all of the buttons from the RibbonGroup upon merge. "true" will keep the buttons from the RibbonGroup upon merge, even if there are duplicates.
<ItemView> defines a link to a view, i.e., config item views (grids, graphs, reports, etc.), configurable multi-instance built-in views (Coverage, Clone item, etc.), standard views (Attachments, Overview, etc.), extension views (FaultTreeGraph, HazardIdentification, etc.). All views can be found listed on the Item views tab in Configure the explorer:
- name: the name of the view (or Extension view). Enter the Name value as seen on the Item views tab of Configure the explorer. This is required.
Although config item views can be found in the above list, the below quick-reference table shows the name to be used for each config item type.
|Config Item Type||Name to be used in ItemView|
|Configurable XML generators||XML|
|Note: For extensions: the extension dll file must be located in the swExplorerExtensions directory in order for it to appear in the list.|
- configId: required for multi-instance configurable item views only. Enter the configuration id attribute for the view. This can be found in the view's configuration:
- configItem: required for config item views, e.g., chart, grid, graph, report, etc., only. Enter one of two possible values:
- The xID of the config item. Example: "x34000000000877C5". Note that if this is used, the ItemView button will always point to that version of the config item. If a new version is made of the config item, the button configuration would need be updated to include the new ID if the button needs to be updated. Or,
- The Ref id of the config item. It consists of the SID of the configured type along with the defined id for the config item. This option will automatically point the button to the latest version of the config item.
If "configitem" is misspelled, the configuration will not apply properly until the misspelling is corrected.
|Note: The Item ribbon tab metadata must be installed if you will be using Ref id for config item views.|
- visibility: defines the dynamic behavior of an ItemView button (and indirectly the ribbon group, item tab and context). This is optional. There are three possible values:
- Ignore: the item view will not be activated by item selection. Activation will instead depend on activation of other views or item links in the same ribbon group. If a group includes only one or more buttons with visibility="Ignore", then the group will not be visible.
- Always: the item view and ribbon group will always be available.
- Dynamic: activation of the item view will depend on the specific view and the item being selected in the item structure tree, according to standard view activation (default).
- hideIfDisabled: defines if the button should be hidden if it is not active. This is optional. If not used, inactive buttons display with gray text by default. Adding hideIfDisabled="true" will hide the button itself. If there are no other buttons in the ribbon group, the ribbon group will be hidden as well. See Creating Item View Buttons for item view button configuration examples. example configurations for visibility.
- locked: When using a configurable graph in an <ItemView> configuration, you can use this attribute to specify if the graph will be locked or not upon loading. This is optional. Valid values are "true" or "false". The default value is "false".
<OpenItem> defines a button that can open a specific item.
- id: the SystemWeaver item ID of the item that will be opened. Example: "x04000000000375CF"
- caption: label text that will be used for the OpenItem button. If not used, the text will be the name of the item according to the id attribute.
- treeSettings: defines which structure tree view setting should be used when the item is opened. This is optional. Enter the name of the tree setting. To use the Default setting, you must specify it, i.e., treeSettings="Default". If not specified, the behavior is the same as using Ctrl+O to open the item. If the item is already open, it will become the active page without any setting changes.
<TreeSettings> offers fast selection of a tree view setting. If multiple tree settings are used, they will work as "radio buttons", i.e., if one is selected the other will be de-selected.
- name: the name of a tree setting. The name appears as the label of the button.
<MultiButton> loads two views simultaneously. In the below example, a configurable graph is defined for the left-side pane and a configurable report is defined for the right-side pane.
See Configuring a Multi-Button for an explanation of tags and attributes and a configuration example.
<MergeButton> enables users to navigate through a structure without having to click on multiple view buttons to change the view. The view updates each time they select a new item type for which there is a definition included in the MergeButton configuration.
See Configuring a Merge Button for an explanation of tags and attributes and a configuration example.
Item ribbon tab configuration examples can be found here.