AX1179

Ribbon tab design considerations

Keep in mind the following design considerations when creating ribbon tabs.

Creating ribbon tabs with multiple groups

All top-level items in a ribbon tab define groups within the ribbon. Each group can have one or more child items that display as buttons in the group.

Most ribbon tabs will have multiple groups. Groups are used to organize the ribbon into logical sections and help users find the buttons they are looking for. If all buttons in the ribbon tab are within a single group, this may make the ribbon tab difficult to use.

In most cases, the only valid property for a top-level item is the display text to define the group name. Top-level items in a ribbon tab cannot be assigned to a shortcut target and do not use any of the display options. However, there are two exceptions:

• The Excel Command Button command can be placed at the top level, to display an entire Excel group in the ribbon tab.
• An Axiom Managed Group command can be placed at the top level, to include the entire contents of an Axiom group in the ribbon tab.

Both of these exceptions are discussed later in this design considerations topic.

Using Axiom Managed Groups in a ribbon tab

Axiom Managed Groups are special commands that allow you to include the entire contents of a particular ribbon group in a custom ribbon tab. The contents of each group are based on the default Axiom ribbon tab that is delivered with the application.

The advantage of using an Axiom Managed Group is that the group will remain in sync with the default Axiom ribbon tab as you upgrade the software. So if a new feature is added to the File Output group in a particular release, and you are using the Axiom Managed Group command for File Output in a custom ribbon tab, then the new feature will automatically be included in the custom ribbon tab. If instead you have customized the File Output group and are no longer using the Axiom Managed Group command, then you would need to manually add the new feature to the custom ribbon tab if you wanted it to display.

The built-in Axiom ribbon tab (AxiomMain.AXL) is made using Axiom Managed Groups. If you want to create a new custom ribbon tab that uses these groups, it is easiest to copy this file and then edit the copy as desired. However, if you want to manually add an Axiom Managed Group to a custom ribbon tab, you can do so as follows:

• In the Axiom Explorer pane of the Edit Ribbon Tab dialog, navigate to the Groups/Sections folder of the Command Library.
• Drag and drop the desired group from the Command Library to the Ribbon Structure pane, as a top-level group item.

It is not possible to add a new "blank" group item and then link it to the group command, because by default the Shortcut Target field is not available for group items. You must either drag and drop the command as a top-level item directly, or create a new child item and link it to the command, then move the child item up to the top level.

If a ribbon tab already contains an Axiom Managed Group, and you want to customize the contents of that group to remove or add features (or otherwise modify the configuration of individual items in the group), then you can "convert" the group to its individual commands. To do so, right-click the group and then select Convert group to individual items. The group will be replaced with all of the individual items in that group, so that you can modify the group as desired. However, keep in mind that converted groups are no longer system-managed and will not automatically update for future changes.

For more information, see Axiom Managed Group commands and Customizing the Axiom ribbon tab.

Creating drop-down menus and "split buttons" in a ribbon tab

Non-group items in a ribbon tab can also have child items. If the user clicks on the "parent" item in the ribbon tab, a drop-down menu allows the user to click one of the child items. This will either perform the configured action for the child item, or open a further sub-menu if the item has child items.

Some features that you can link to in a ribbon tab are automatically drop-down menus. For example, if you use the Axiom Function command and select a function group in the shortcut parameters, then clicking this button will automatically display a drop-down menu of the functions in that group. In this case you should not place any child items under this item, as this will cause the default menu to not display as expected.

It is also possible to configure "split buttons" in ribbon tabs. A split button is a button that performs a default command, but also has a secondary drop-down menu where users can select related commands. For example, the Refresh button on the default Axiom tab is a split button. To create a split button, you assign a shortcut target to the "parent" item, and then also assign child items to that item. This configuration will automatically render as a split button in the ribbon tab.

Example ribbon tab structure

When this ribbon definition is rendered as a ribbon tab, the Examples group will have two buttons:

• Save button: Because the Save parent item is linked to a command, users can click on the Save button to perform a save, or they can use the secondary drop-down menu to save the file only or data only. This would be similar to the Save button on the default Axiom tab.

• Manage Tables button: Because the Manage Tables parent item is not linked to a command, clicking that button does not perform an action. Instead it brings up a drop-down menu where users can open the Table Library or add a table.

If the split button or drop-down menu has several items in it, you may want to use separator text to organize the menu. You can do this by adding an item where you want the separator text to display, and then only defining display text for that item. This non-linked item will automatically display as separator text in the drop-down menu. For example:

Hiding items in the ribbon tab

By default, the option to Show restricted item is selected for all child items in a ribbon tab. This means that the item will always display in the ribbon tab, but it will be grayed out and unavailable if the user does not have permission to use the feature, or if the feature does not apply to the current context.

In most cases, it is recommended to leave this option selected. It may be disorienting to users to have options in the ribbon tab appear and disappear if it is not obvious why this behavior is occurring. Users may wonder why a particular command no longer displays on the ribbon tab, without realizing that the command does not apply to the current context. However, in certain cases it is best to disable this option—such as when placing file groups and file group categories on the ribbon, so that users do not see file groups that they do not have access to.

Leaving this option selected for most items in a ribbon tab also avoids the potential issue of displaying entirely blank ribbon tabs. Depending on the commands in your ribbon tab, it is possible to end up in situations where none of the commands apply to the current context, and therefore the entire ribbon tab is blank. For example, if your home page is an Axiom form instead of a spreadsheet file, then none of the commands that can be normally used in a spreadsheet file apply to this context, and they will not display on the ribbon tab unless Show restricted items is selected.

NOTE: This option is not available for Axiom Managed Groups; the visibility of commands in the group is system-managed.

Including Excel features on an Axiom ribbon tab

You can include Excel features on an Axiom ribbon tab, using the Excel Command Button in the Command Library. You can enter Excel command IDs to incorporate virtually any Excel feature on the ribbon. For more information, see Excel Command Button command. This feature is only supported for use in the Excel Client; the Windows Client will ignore any item set to the Excel Command Button.

It is also possible to include entire Excel command groups on the ribbon. To do this:

• From the Axiom Explorer pane in the Edit Ribbon Tab dialog, locate the Excel Command Button command in the Command Library, and then drag and drop it into the ribbon tab structure as a top-level item.

• Use the shortcut parameters to specify the appropriate Excel Control ID for the group that you want to display. The Excel Control Type must be set to Group.

  Group codes cannot be looked up in the Excel Options dialog like button codes. You will need to download the appropriate resources from Microsoft to look up the desired group codes, as discussed in the Excel Command Button topic referenced above.

• The group node cannot have any child items. Excel will automatically populate the group node with the features that normally display in the specified group.

Displaying child items inline

If an item has child items, you can choose to display those items inline (at the level of the parent item), omitting the display of the parent item. To do this, you must enable Display child items inline for the parent item.

For example, you may want to create a drop-down menu with a couple of feature commands at the top, followed by the contents of a particular folder (similar to the Reports menu). To do this, you can add the folder to the ribbon tab structure, and then enable Display child items inline for that item. When the ribbon is rendered to users, the folder item will be omitted and instead the individual files in the folder will dynamically display in the drop-down menu.

The inline behavior applies whether the child items are defined in the ribbon tab structure, or if the child items will be generated dynamically based on the parent item. In the previous example, the individual files aren't defined in the ribbon tab structure, they are generated dynamically based on the folder parent item. However, keep in mind that if the child items are displayed directly on the ribbon instead of in a drop-down list, then they will not update dynamically as changes are made to the folder in that session.