Settings in the 'Ribbon macros' tab

Each ribbon macro requires the indication of a Name (1), which only appears during configuration and is not subject to localization. The name is not required to be unique, but for matters of transparency, it is advisable to ensure names are at least unique within a group of ribbon macros linked to the same Context (2) and make use of the option to provide a plain text Description (3).

The Context (2) is populated automatically if the ribbon macro overview was navigated to from the 'Preferences' menu of a specific view. In this case the field appears as read-only, as shown in the screenshot. If the overview was opened via the menu item Ribbonmakroübersicht instead, the context field may be edited, e.g. to assign a copy of a ribbon macro to another context.

Priority (3) is initialized with a default value of 0. This setting prioritizes between competing definitions of ribbon macros in the following cases:

• Multiple ribbon macros specify Overrides (4)/(5) for properties of the same main or sub category.

• Multiple ribbon macros define Macros (see the following section) referring to the same button (identified by macro name).

In both cases only the definition form the ribbon macro with the highest priority value is effective. However, priorities are only considered in case of conflicts on the level of element (definitions for same category or macro). Any non-conflicting definitions from ribbon macros with matching Association criteria are 'cumulatively' applied to the ribbon menu.

Each ribbon macro must be linked to a specific section of the ribbon menu by a two-stage selection of the Main category (4) and Sub category (5). The respective comboboxes are qualified as 'required', their dropdowns feature all predefined categories. They also allow entering random text to define extensions of the structural level by adding a custom ribbon tab (main category) or section (sub category).

For the selected category (per level) a ribbon macro may define specifics for labelling (Main category label or Sub category label) and the position in the sequence of categories in that level (Main category priority or Sub category priority). The options Main category override or Sub category override, control whether these definitions should be applied as overrides to existing definitions based on defaults for predefined categories or other applicable ribbon macros. If multiple ribbon macros are applicable for a context and addressing the same element(s) with the override option checked, the one with the highest Priority (3) overrides all the others (as stated above).

The label definitions (Main category label or Sub category label) may be entered as direct text input or defined via Localization or Company specific localization by clicking the menu symbol next to the input field. If the text field does not contain characters (except blanks etc.), the 'override' option is only applied to the priority setting for category (defining the sequence position per level), leaving the label unchanged.

The following main categories are available in views for all data objects, unless restricted by permissions:

Choices for Sub category largely vary per context. Moreover, the choices available in the sub category dropdown are limited to the relevant subset, when a main category is selected. Therefore no list of predefined sub categories is featured here.

The option Forbid ribbon bar auto hide (6) controls the dynamic behaviour of the ribbon bar, in response to shortage of vertical space for a view. In general, the ribbon bar of a view is hidden automatically to gain extra vertical space for contents of a view as required (see Arbeiten in der Benutzeroberfläche). While at least one ribbon macro relevant for a context forbids 'auto hide', the ribbon bar will not hide automatically. This option is effective without assigning macros in the same ribbon macro. Main category and sub category must be assigned for formal reasons only. 'Auto hide' is effectively prohibited, even if the referenced categories do not appear in the ribbon bar, because no buttons are specified.

►CAUTION◄ An existing choice of a predefined sub category is only valid in combination with the proper predefined main category. Still, the main category could be changed after picking the sub category. In this case, the internal name stored to identify the sub category will be re-interpreted as text input, which may qualify an additional sub category for the tab for the selected main category, bearing the Sub category label defined in the ribbon macro, if any. Inversely, switching from a custom main category to a predefined main category may induce the accidental effect that the random name of a sub category now matches the internal name of a predefined sub category of the main category selected. Effectively, this may apply definitions from the ribbon macro to the predefined sub category.

Settings in the 'Macros' tab

The Macros tab features settings that affect the level of individual buttons in the ribbon menu. The term 'macro' refers to a relation between a set of commands and a specific button.

Often a ribbon macro contains exactly one macro, e.g. in order to add a specific button in a certain sub category of a menu, depending on matching Association criteria for a context. However, ribbon macros may also combine multiple macros, provided these belong to the same sub category of the ribbon menu. Even ribbon macros without any macros may be useful, e.g to define overrides on the level of categories (see the previous section).

The tab lines up configured macros in the selection row (1). Similar to a ribbon menu, each macro is represented by a button, which here features a small 'trash-can' symbol in the top right corner, which can be clicked to remove the macro.

Configured macros are aligned from right to left starting from the placeholder with the symbol. Their sequence does not necessarily match the buttons in a ribbon menu, which typically also contains other buttons.

Clicking one of the buttons shows the details for its macro in the Details (2) area below, where they can also be edited.

The Priority (3) of a macro determines its position within the ribbon menu. Buttons belonging to the same sub category are lined up from left to right in sequence of ascending priority.

The Name (4) of the macro serves as a unique identifier within the sub category defined in the Ribbon macro tab. When a standard macro is added in the context of a predefined sub category (see the section 'Overriding, disabling and hiding buttons', below), the internal name of the standard button is initialized here. For new custom macros, the name is initialized with an automatically generated value (e.g. new_1559822118620). For the sake of transparency, it is recommended to replace these strings with meaningful text (such as 'Save and print' in the screenshot). If other applicable ribbon macros contain a macro referring to the same name within the same sub category, only the definitions of the ribbon macro with the highest priority setting are considered.

The Icon uri (5) optionally defines an icon to display on the button representing the macro in a ribbon. Although the browser available per the Select button only lists content of specific standard resources for icons, other objects can be addressed by entering a path relative to the 'web' folder, e.g. to refer to images uploaded via File manager. Buttons displayed in a ribbon menu show images in shades of grey by default, and only produce colors when 'hovering' (i.e. touching the mouse cursor). Advanced design options (as described in Working with image resources (Icons)) are available for button icons as well.

The label text for the button may be defined as direct text input for the Label (6) or assigned from Localization or Company specific localization via the menu symbol to the right of the input.

The list of Commands (7) defines a sequence of command to execute when the button is clicked (see Verfügbare Befehle), which is the functional core of a 'macro'.

• The symbol opens a structured context menu from which commands can be picked.

• The configured commands can be removed from the macro by clicking the 'X' symbol at the top-right.

• The sequence of commands – executed top-down – can be adjusted by drag & drop.

• Clicking a command in the list, produces its parameters (8) in the area right of the list (if any).

►NOTE◄ If a macro does not specify any command, it will not be represented by a button in the ribbon menu.

In the screenshot above the command 'Details > Save' has been selected according to its frame color, which makes the option Required (8) appear on the right. This flag is available for any command and defines the following:

• If the flag is set for any command in a sequence, the button in the ribbon menu will only appear as enabled in a situation where requirements for executing the 'required' command – e.g. a certain type of selection in an overview (single/multi, see Verfügbare Befehle) – are met. Otherwise, the button is disabled, which prevents the entire macro from being executed. In the above example, the command 'Details > Save' requires a single selection. In a combined view, only a single line may be selected in the datagrid, to enable the button.

• If multiple commands of the same sequence are flagged as Required, all applicable criteria must be met before macro execution in order to enable the button. If in the given example the Required flag was also set for the command 'Print > Pdf', which is only available once an object has been created, the Save and print button would appear disabled for a new object until it was saved for the first time.

►IMPORTANT◄ The Required (8) flag is only evaluated if the configured command is basically applicable in the context of the macro. This may not always be the case for all commands listed as choices in the context menu. If a sequence includes a command categorically inapplicable in the context of the ribbon macro, the button will never appear in the menu, regardless of settings for the Required flag for this command.