3.5.5.2.1. AddAction

AddAction is a list action designed to add existing entity instances to a data container by selecting them in a lookup screen. For example, it can be used to fill a many-to-many collection.

The action is implemented by com.haulmont.cuba.gui.actions.list.AddAction class and should be defined in XML using type="add" action’s attribute. You can configure common action parameters using XML attributes of the action element, see Declarative Actions for details. Below we describe parameters specific to the AddAction class.

The following parameters can be set both in XML and in Java:

  • openMode - the lookup screen opening mode as a value of the OpenMode enum: NEW_TAB, DIALOG, etc. By default, AddAction opens the lookup screen in THIS_TAB mode.

  • screenId - string id of the lookup screen to use. By default, AddAction uses either a screen, annotated with @PrimaryLookupScreen, or having identifier in the format of <entity_name>.lookup or <entity_name>.browse, e.g. demo_Customer.browse.

  • screenClass - Java class of the lookup screen controller to use. It has higher priority than screenId.

For example, if you want to open a specific lookup screen as a dialog, you can configure the action in XML:

<action id="add" type="add">
    <properties>
        <property name="openMode" value="DIALOG"/>
        <property name="screenClass" value="com.company.sales.web.customer.CustomerBrowse"/>
    </properties>
</action>

Alternatively, you can inject the action into the screen controller and configure it using setters:

@Named("customersTable.add")
private AddAction customersTableAdd;

@Subscribe
public void onInit(InitEvent event) {
    customersTableAdd.setOpenMode(OpenMode.DIALOG);
    customersTableAdd.setScreenClass(CustomerBrowse.class);
}

Now let’s consider parameters that can be configured only in Java code. In order to generate correctly annotated method stubs for these parameters, use Handlers tab of the Component Inspector tool window in Studio.

  • screenOptionsSupplier - a handler that returns ScreenOptions object to be passed to the opened lookup screen. For example:

    @Install(to = "customersTable.add", subject = "screenOptionsSupplier")
private ScreenOptions customersTableAddScreenOptionsSupplier() {
    return new MapScreenOptions(ParamsMap.of("someParameter", 10));
}

    The returned ScreenOptions object will be available in the InitEvent of the opened screen.

  • screenConfigurer - a handler that accepts the lookup screen and can initialize it before opening. For example:

    @Install(to = "customersTable.add", subject = "screenConfigurer")
private void customersTableAddScreenConfigurer(Screen screen) {
    ((CustomerBrowse) screen).setSomeParameter(10);
}

    Note that screen configurer comes into play when the screen is already initialized but not yet shown, i.e. after its InitEvent and AfterInitEvent and before BeforeShowEvent are sent.

  • selectValidator - a handler that is invoked when the user clicks Select in the lookup screen. It accepts the object that contains the selected entities. You can use this handler to check if the selection matches some criteria. The handler must return true to proceed and close the lookup screen. For example:

    @Install(to = "customersTable.add", subject = "selectValidator")
private boolean customersTableAddSelectValidator(LookupScreen.ValidationContext<Customer> validationContext) {
    boolean valid = checkCustomers(validationContext.getSelectedItems());
    if (!valid) {
        notifications.create().withCaption("Selection is not valid").show();
    }
    return valid;
}

  • transformation - a handler that is invoked after entities are selected and validated in the lookup screen. It accepts the collection of selected entities. You can use this handler to transform the selection before adding entities to the receiving data container. For example:

    @Install(to = "customersTable.add", subject = "transformation")
private Collection<Customer> customersTableAddTransformation(Collection<Customer> collection) {
    return reloadCustomers(collection);
}

  • afterCloseHandler - a handler that is invoked after the lookup screen is closed. AfterCloseEvent is passed to the handler. For example:

    @Install(to = "customersTable.add", subject = "afterCloseHandler")
private void customersTableAddAfterCloseHandler(AfterCloseEvent event) {
    if (event.closedWith(StandardOutcome.SELECT)) {
        System.out.println("Selected");
    }
}

If you want to perform some checks or interact with the user before the action is executed, subscribe to the action’s ActionPerformedEvent and invoke execute() method of the action when needed. The action will be invoked with all parameters that you defined for it. In the example below, we show a confirmation dialog before executing the action:

@Named("customersTable.add")
private AddAction customersTableAdd;

@Subscribe("customersTable.add")
public void onCustomersTableAdd(Action.ActionPerformedEvent event) {
    dialogs.createOptionDialog()
            .withCaption("Please confirm")
            .withMessage("Do you really want to add a customer?")
            .withActions(
                    new DialogAction(DialogAction.Type.YES)
                            .withHandler(e -> customersTableAdd.execute()), // execute action
                    new DialogAction(DialogAction.Type.NO)
            )
            .show();
}

You can also subscribe to ActionPerformedEvent and instead of invoking the action’s execute() method, use ScreenBuilders API directly to open the lookup screen. In this case, you are ignoring all specific action parameters and behavior and using only its common parameters like caption, icon, etc. For example:

@Inject
private ScreenBuilders screenBuilders;
@Inject
private Table<Customer> customersTable;

@Subscribe("customersTable.add")
public void onCustomersTableAdd(Action.ActionPerformedEvent event) {
    screenBuilders.lookup(customersTable)
            .withOpenMode(OpenMode.DIALOG)
            .withScreenClass(CustomerBrowse.class)
            .withSelectValidator(customerValidationContext -> {
                boolean valid = checkCustomers(customerValidationContext.getSelectedItems());
                if (!valid) {
                    notifications.create().withCaption("Selection is not valid").show();
                }
                return valid;

            })
            .build()
            .show();
}