3.5.4.2.1. List Component Actions

The framework provides a set of standard actions for visual components implementing the ListComponent interface (DataGrid, Table, GroupTable, TreeTable and Tree). They are located in the com.haulmont.cuba.gui.actions.list package.

An example of using standard actions in a table:

<groupTable id="customersTable" width="100%" dataContainer="customersDc">
    <actions>
        <action id="create" type="create"/>
        <action id="edit" type="edit"/>
        <action id="remove" type="remove"/>
    </actions>
    <columns>
        <column id="name"/>
        <column id="email"/>
    </columns>
    <buttonsPanel>
        <button id="createBtn" action="customersTable.create"/>
        <button id="editBtn" action="customersTable.edit"/>
        <button id="removeBtn" action="customersTable.remove"/>
    </buttonsPanel>
</groupTable>

The standard list component actions include the following types:

  • create type is implemented by the com.haulmont.cuba.gui.actions.list.CreateAction class. It is designed to create a new entity using its default edit screen.

  • edit type is implemented by the com.haulmont.cuba.gui.actions.list.EditAction class. It is designed to edit the selected entity using its default edit screen.

  • remove type is implemented by the com.haulmont.cuba.gui.actions.list.RemoveAction class. It is designed to remove the selected entity.

  • add type is implemented by the com.haulmont.cuba.gui.actions.list.AddAction class. It is designed to select an entity from a default lookup screen and add it to the associated data container. A typical use case for this action is to add entities to a many-to-many collection.

  • exclude type is implemented by the com.haulmont.cuba.gui.actions.list.ExcludeAction class. It is designed to remove an entity from a collection data container without removing it from the database. A typical use case for this action is to remove entities from a many-to-many collection.

  • refresh type is implemented by the com.haulmont.cuba.gui.actions.list.RefreshAction class. It is designed to reload the data container which is used by the list component.

  • excel type is implemented by the com.haulmont.cuba.gui.actions.list.ExcelAction class. It is designed to output the list component content to an XLS file.

  • bulkEdit type is implemented by the com.haulmont.cuba.gui.actions.list.BulkEditAction class. It is designed to change attribute values for several entity instances at once. The usage is the same as for any other actions, for instance:

    <table id="table" width="100%" dataContainer="customersCt">
        <actions>
            ...
            <action id="bulkEdit" type="bulkEdit"/>
        </actions>
        ...
        <rowsCount/>
        <buttonsPanel alwaysVisible="true">
            ...
            <button action="table.bulkEdit"/>
        </buttonsPanel>
        <rows/>
    </table>

    In addition to that, the BulkEditorWindow can be created programmatically using the new com.haulmont.cuba.gui.BulkEditors bean:

    bulkEditors.builder(metaClass, table.getSelected(), getWindow().getFrameOwner())
               .withListComponent(table)
               .create()
               .show();

Standard actions provide default values for basic parameters: caption, icon and shortcut; and default behavior when executed. You can provide your own values to basic parameters in XML, just like for any other action. For example, you can specify a custom icon:

<action id="create" type="create" icon="USER"/>

In order to customize the execution behavior, you should subscribe to the action’s ActionPerformedEvent. All standard actions do not execute their code if an alternative action listener is provided. It means that your ActionPerformedEvent handler effectively overrides the default action behavior.

For example, the following code overrides the default create action behavior to create Customer entity using a specific screen opened as a modal dialog:

public class CustomerBrowse extends StandardLookup<Customer> {
    @Inject
    private GroupTable<Customer> customersTable;
    @Inject
    private ScreenBuilders screenBuilders;

    @Subscribe("customersTable.create")
    protected void onCustomersTableCreateActionPerformed(Action.ActionPerformedEvent event) {
        screenBuilders.editor(customersTable)
                .newEntity()
                .withScreenClass(CustomerEdit.class)     // specific editor screen
                .withLaunchMode(OpenMode.DIALOG)        // open as modal dialog
                .build()
                .show();
    }
}

You can customize behavior of the edit action in the same way as for create. See ScreenBuilders bean description for more details.

The add action also uses the ScreenBuilders bean, so you can customize it as follows:

public class CustomerEdit extends StandardEditor<Customer> {
    @Inject
    private ScreenBuilders screenBuilders;
    @Inject
    private Table<Employee> accountableTable;

    @Subscribe("accountableTable.add")
    protected void onAccountableTableAddActionPerformed(Action.ActionPerformedEvent event) {
        screenBuilders.lookup(Employee.class, this)
                .withListComponent(accountableTable)
                .withScreenClass(EmployeeBrowse.class)   // specific editor screen
                .withLaunchMode(OpenMode.DIALOG)        // open as modal dialog
                .build()
                .show();
    }
}