Command Bar Items

So far, we’ve defined the layout of the client UI (Window Sections and Controls) and we’ve defined the content of the UI (Command Bar Sections and their relationships to Command Bar Items), but we haven’t defined the behavior of the UI. That’s where Command Bar Items differ from the rest of the data model we’ve reviewed so far – they provide the ability to execute logic based on user interaction, client state, and item context in addition to the add, remove, replace, and clear all actions on the relationship.

Figure 5. Default ItemView Command Bar Items

Command Bar Items are also implemented differently. While Window Sections, Controls, and Command Bar Sections all used classifications to differentiate items, the CommandBarItem ItemType is implemented as a polymorphic ItemType.

See the list in the following section for more details on the various ItemTypes that are implemented as sources of the CommandBarItem poly ItemType.

A CommandBarButton item represents an element that triggers an action. It can be single state, where a click executes the same action every time, or it can have two states – active and inactive.

Buttons support multilingual labels, multilingual tooltips, images, and the following properties:

• Additional Data: supports cssClass
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

See the default itemview.itemcommandbar.default.save item for an example.

A CommandBarCheckbox represents a single, atomic item in any non-menu container that can be toggled on/off. Can be styled as a checkbox or radio button.

Checkboxes support multilingual labels, multilingual tooltips, and the following properties:

• Additional Data: supports custom parameters
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

A CommandBarDropDown item represents a combobox element. The element’s options are populated from the Additional Data property merged with the result of the Init Method.

Dropdowns support multilingual labels, multilingual tooltips, images, and the following properties:

• Additional Data: supports cui_items, an array of objects each containing an id and name or label
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

A CommandBarSeparator represents a divider to visually separate items in any non-menu container.

Separators support the following properties:

• Additional Data: supports custom parameters
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Include Events: state change events that should trigger the item’s initialization method

See the default itemview.itemcommandbar.default.sep_af_promote item for an example.

A CommandBarMenu represents a hierarchical menu that can contain CommandBarMenuButton items or other CommandBarMenu items.

Menus support multilingual labels, multilingual tooltips, images, and the following properties:

• Parent Menu: the parent CommandBarMenu item if this item is a sub-menu
• Additional Data: supports menuPosition
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

See the default itemview.itemcommandbar.default.navigate item for an example.

A CommandBarMenuButton represents a single, atomic button in a menu with some associated logic.

Menu Buttons support multilingual labels, multilingual tooltips, images, and the following properties:

• Parent Menu: the parent CommandBarMenu item
• Additional Data: supports custom parameters
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

See the default itemview.itemcommandbar.default.navigate.structurebrowser item for an example.

A CommandBarMenuSeparator represents a divider to visually separate items in a menu.

Menu Separators support the following properties:

• Parent Menu: the parent CommandBarMenu item
• Additional Data: supports custom parameters
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Include Events: state change events that should trigger the item’s initialization method

See the default itemview.itemcommandbar.default.navigate.aftersearch item for an example.

A CommandBarMenuCheckbox represents a single, atomic item in a menu that can be toggled on/off. Can be styled as a checkbox or radio button.

Menu Checkboxes support multilingual labels, multilingual tooltips, and the following properties:

• Parent Menu: the parent CommandBarMenu item
• Additional Data: supports custom parameters
• Init Method: a Method, often used to show, hide, enable, or disable an element when initialized
• Click Method: a Method used to execute some logic when the element is clicked by a user
• Include Events: state change events that should trigger the item’s initialization method

A CommandBarShortcut item represents a keyboard shortcut that triggers an action. It can only be used with specific Locations intended for shortcuts.

Shortcuts support the following properties:

• Additional Data: supports stopPropagation, useCapture, preventDefault, preventBlur, and context
  
  • stopPropagation: Boolean property, prevents further propagation of the current event
  • useCapture: Boolean property, set to true if the “this” pointer must point to the context item
  • preventDefault: Boolean property, cancels the default event if it’s cancelable, without stopping further propagation
  • preventBlur: Boolean property, prevents the blur event if set to true and a domNode has the focus
  • context: Object property, the “this” pointer references this object if useCapture is true
• Click Method: a Method used to execute some logic when the shortcut is keyed in by a user
• Shortcut: the key combination for triggering the shortcut

Table 3 lists valid shortcut combinations:
Table 2: Valid shortcuts

See the default com.aras.innovator.cui_default.mws_delete item for an example.

The Edit ItemType enables you to create a text box control and use it in a Command Bar to capture data relevant to a particular command. The Edit option supports multilingual labels, multilingual tooltips, and the following properties:

• Additional Data: supports custom parameters
• On Keydown Method: a Method used to execute some logic when the shortcut is keyed in by a user
• Init Handler: a Method, often used to show, hide, enable, or disable an element when initialized

The following screenshot shows an example using the Class Structure dialog box:

Figure 6. In this example, entering “pr” in the search box displays only those documents that start with the letters “pr” enabling you to create a class structure for documents. The Edit ItemType enables you to create a text box control which can be placed in a command bar to capture data relevant to a command. The following figure shows an example using the CommandBarEdit ItemType.

Figure 7.