AddAction - Платформа CUBA. Руководство по разработке приложений

3.5.5.2.1. AddAction

AddAction - действие с коллекцией, предназначенное для добавления существующих экземпляров сущности из экрана выбора в контейнер данных. Например, оно используется для заполнения many-to-many коллекций.

Действие реализовано классом com.haulmont.cuba.gui.actions.list.AddAction и объявляется в XML с помощью атрибута type="add". Общие свойства действий можно конфигурировать с помощью атрибутов элемента action, подробнее см. раздел Декларативное создание действий. Ниже рассматриваются параметры, специфичные для класса AddAction.

Следующие параметры можно установить и в XML и в Java:

openMode - режим открытия экрана выбора, задаваемый значением перечисления OpenMode: NEW_TAB, DIALOG, и т.д. По умолчанию AddAction открывает экран выбора в режиме THIS_TAB.
screenId - строковый идентификатор экрана выбора. По умолчанию AddAction использует экран, аннотированный @PrimaryLookupScreen, или имеющий идентификатор вида <entity_name>.lookup или <entity_name>.browse, например demo_Customer.browse.
screenClass - класс Java экрана выбора. Данный параметр имеет более высокий приоритет, чем screenId.

Например, если необходимо открыть определенный экран выбора в режиме диалога, действие можно сконфигурировать в XML следующим образом:

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

В качестве альтернативы, действие можно инжектировать в контроллер экрана и сконфигурировать, используя сеттеры:

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

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

Далее рассматриваются параметры, которые можно сконфигурировать только программно в Java. Для генерации корректно аннотированных методов для этих параметров используйте закладку Handlers окна инструментов Component Inspector в Studio.

screenOptionsSupplier - обработчик, возвращающий объект ScreenOptions для передачи в открываемый экран выбора. Например:
```
@Install(to = "customersTable.add", subject = "screenOptionsSupplier")
private ScreenOptions customersTableAddScreenOptionsSupplier() {
    return new MapScreenOptions(ParamsMap.of("someParameter", 10));
}
```
Возвращаемый объект ScreenOptions будет доступен в InitEvent открываемого экрана.
screenConfigurer - обработчик, принимающий экран выбора для его конфигурирования перед открытием. Например:
```
@Install(to = "customersTable.add", subject = "screenConfigurer")
private void customersTableAddScreenConfigurer(Screen screen) {
    ((CustomerBrowse) screen).setSomeParameter(10);
}
```
Конфигуратор экрана вступает в действие, когда экран уже инициализирован, но еще не показан, то есть после InitEvent и AfterInitEvent, и до BeforeShowEvent.
selectValidator - обработчик, вызываемый когда пользователь нажимает Select в экране выбора. Он принимает объект, содержащий выбранные сущности. Данный обработчик можно использовать для проверки выбора по каким-либо критериям. Обработчик должен вернуть true для того, чтобы процесс был продолжен и экран выбора закрылся. Например:
```
@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 - обработчик, вызываемый после того, как сущности выбраны и провалидированы в экране выбора. Он принимает коллекцию выбранных сущностей и может быть использован для того, чтобы преобразовать содержимое коллекции перед добавлением сущностей в контейнер данных. Например:
```
@Install(to = "customersTable.add", subject = "transformation")
private Collection<Customer> customersTableAddTransformation(Collection<Customer> collection) {
    return reloadCustomers(collection);
}
```

afterCloseHandler - обработчик, вызываемый после закрытия экрана выбора. Принимает AfterCloseEvent. Например:

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

Для того, чтобы произвести какие-либо проверки, или взаимодействовать с пользователем перед выполнением действия, необходимо подписаться на событие ActionPerformedEvent действия и в нужный момент вызвать метод execute(). Действие будет вызвано со всеми параметрами, которые были для него заданы. В примере ниже перед выполнением действия отображается диалог подтверждения:

@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();
}

Можно также подписаться на ActionPerformedEvent, и вместо вызова метода execute() действия, использовать для открытия экрана выбора ScreenBuilders API напрямую. По сути, в этом случае все специфичные параметры действия игнорируются, и действуют только общие параметры: caption, icon, и т.д. Например:

@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();
}