3.5.5.1. Declarative Actions

You can specify a set of actions in an XML screen descriptor for any component that implements the Component.ActionsHolder interface, including the entire window or fragment. This is done in the actions element, which contains nested action elements.

The action element can have the following attributes:

  • id − identifier, which should be unique within the ActionsHolder component.

  • type - defines a specific action type. If this attribute is set, the framework finds the class having @ActionType annotation with the specified value, and uses it to instantiate the action. If the type is not defined, the framework creates an instance of BaseAction class. See Standard Actions for how to use action types provided by the framework and Custom Action Types for how to create your own types.

  • caption – action name.

  • description – action description.

  • enable – accessibility flag (true / false).

  • icon – action icon.

  • primary - attribute that indicates if a button representing this action should be highlighted with a special visual style (true / false).

    The highlighting is available by default in the hover theme; to enable this feature in the halo theme, set true for the $cuba-highlight-primary-action style variable.

    The create standard list action and the lookupSelectAction in the lookup screen are primary by default.

    actions primary

  • shortcut - a keyboard shortcut.

    Shortcut values can be hard-coded in the XML descriptor. Possible modifiers, ALT, CTRL, SHIFT, are separated by the "-" character. For example:

    <action id="create" shortcut="ALT-N"/>

    To avoid the hard-coded values, you can use the predefined shortcut aliases from the list below, for example:

    <action id="edit" shortcut="${TABLE_EDIT_SHORTCUT}"/>

    • TABLE_EDIT_SHORTCUT

    • COMMIT_SHORTCUT

    • CLOSE_SHORTCUT

    • FILTER_APPLY_SHORTCUT

    • FILTER_SELECT_SHORTCUT

    • NEXT_TAB_SHORTCUT

    • PREVIOUS_TAB_SHORTCUT

    • PICKER_LOOKUP_SHORTCUT

    • PICKER_OPEN_SHORTCUT

    • PICKER_CLEAR_SHORTCUT

    Another option is to use the fully qualified name of the Config interface and method which returns shortcut:

    <action id="remove" shortcut="${com.haulmont.cuba.client.ClientConfig#getTableRemoveShortcut}"/>

  • visible – visibility flag (true / false).

The examples of action declaration and handling are provided below.

  • Declaring actions for the whole screen:

    <window>
    <actions>
        <action id="sayHello" caption="msg://sayHello" shortcut="ALT-T"/>
    </actions>

    <layout>
        <button action="sayHello"/>
    </layout>
</window>
    // controller
@Inject
private Notifications notifications;

@Subscribe("sayHello")
protected void onSayHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
                .withCaption("Hello")
                .withType(Notifications.NotificationType.HUMANIZED)
                .show();
}

    In the example above, an action with sayHello identifier and a caption from the screen’s message pack is declared. This action is bound to a button, which caption will be set to the action’s name. The screen controller subscribes to the action’s ActionPerformedEvent, so the onSayHelloActionPerformed() method will be invoked when the user clicks the button or presses the ALT-T keyboard shortcut.

Note that actions declared for the whole screen do not refresh their state. It means that if an action has specific enabledRule, it will not be applied until refreshState() is invoked manually.

  • Declaring actions for PopupButton:

    <popupButton id="sayBtn" caption="Say">
    <actions>
        <action id="hello" caption="Say Hello"/>
        <action id="goodbye" caption="Say Goodbye"/>
    </actions>
</popupButton>
    // controller
@Inject
private Notifications notifications;

private void showNotification(String message) {
    notifications.create()
            .withCaption(message)
            .withType(NotificationType.HUMANIZED)
            .show();
}

@Subscribe("sayBtn.hello")
private void onSayBtnHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

@Subscribe("sayBtn.goodbye")
private void onSayBtnGoodbyeActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

  • Declaring actions for Table:

    <groupTable id="customersTable" width="100%" dataContainer="customersDc">
    <actions>
        <action id="create" type="create"/>
        <action id="edit" type="edit"/>
        <action id="remove" type="remove"/>
        <action id="copy" caption="Copy" icon="COPY" trackSelection="true"/>
    </actions>
    <columns>
        <!-- -->
    </columns>
    <rowsCount/>
    <buttonsPanel alwaysVisible="true">
        <!-- -->
        <button action="customersTable.copy"/>
    </buttonsPanel>
</groupTable>
    // controller

@Subscribe("customersTable.copy")
protected void onCustomersTableCopyActionPerformed(Action.ActionPerformedEvent event) {
    // ...
}

    In this example, the copy action is declared in addition to create, edit and remove standard actions of the table. The trackSelection="true" attribute means that the action and corresponding button become disabled if no row is selected in the table. It is useful if the action is intended to be executed for a currently selected table row.

  • Declaring PickerField actions:

    <pickerField id="userPickerField" dataContainer="customerDc" property="user">
    <actions>
        <action id="lookup" type="picker_lookup"/>
        <action id="show" description="Show user" icon="USER"/>
    </actions>
</pickerField>
    // controller

@Subscribe("userPickerField.show")
protected void onUserPickerFieldShowActionPerformed(Action.ActionPerformedEvent event) {
    //
}

    In the example above, the standard picker_lookup action and an additional show action are declared for the PickerField component. Since PickerField buttons that display actions use icons instead of captions, the caption attribute is not set. The description attribute allows you to display a tooltip when hovering over the action button.

You can obtain a reference to any declared action in the screen controller either directly by injection, or from a component that implements the Component.ActionsHolder interface. It can be useful to set action properties programmatically. For example:

@Named("customersTable.copy")
private Action customersTableCopy;

@Inject
private PickerField<User> userPickerField;

@Subscribe
protected void onBeforeShow(BeforeShowEvent event) {
    customersTableCopy.setEnabled(false);
    userPickerField.getActionNN("show").setEnabled(false);
}