5.5.4.2.1. Стандартные действия с коллекцией
Для наследников ListComponent
(это Table, GroupTable, TreeTable и Tree) набор стандартных действий определен в перечислении ListActionType
, классы их реализации находятся в пакете com.haulmont.cuba.gui.components.actions
.
Пример использования стандартных действий в таблице:
<table id="usersTable" width="100%">
<actions>
<action id="create"/>
<action id="edit"/>
<action id="remove"/>
<action id="refresh"/>
</actions>
<buttonsPanel>
<button action="usersTable.create"/>
<button action="usersTable.edit"/>
<button action="usersTable.remove"/>
<button action="usersTable.refresh"/>
</buttonsPanel>
<rowsCount/>
<columns>
<column id="login"/>
...
</columns>
<rows datasource="usersDs"/>
</table>
Рассмотрим их подробнее.
CreateAction
CreateAction
- действие с идентификатором create. Предназначено для создания нового экземпляра сущности и открытия экрана редактирования для этого экземпляра. Если экран редактирования успешно закоммитил новый экземпляр в базу данных, то CreateAction
добавляет этот новый экземпляр в источник данных таблицы и делает его выбранным.
В классе CreateAction
определены следующие специфические методы:
-
setOpenType()
- позволяет задать режим открытия экрана редактирования новой сущности. По умолчанию экран открывается в режимеTHIS_TAB
.Так как довольно часто требуется открывать экраны редактирования в другом режиме (как правило,
DIALOG
), при декларативном создании действияcreate
в элементеaction
можно указать атрибутopenType
с нужным значением. Это избавляет от необходимости получать ссылку на действие в контроллере и программно устанавливать данное свойство. Например:<table id="usersTable"> <actions> <action id="create" openType="DIALOG"/>
-
setWindowId()
- позволяет задать идентификатор экрана редактирования сущности. По умолчанию используется экран{имя_сущности}.edit
, напримерsales$Customer.edit
. -
setWindowParams()
- позволяет задать параметры экрана редактирования, передаваемые в его методinit()
. Далее эти параметры можно использовать напрямую в запросе источника данных через префиксparam$
или инжектировать в контроллер экрана с помощью аннотации@WindowParam
. -
setWindowParamsSupplier()
отличается отsetWindowParams()
тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными черезsetWindowParams()
и могут переопределять их. Например:createAction.setWindowParamsSupplier(() -> { Customer customer = metadata.create(Customer.class); customer.setCategory(/* some value dependent on the current state of the screen */); return ParamsMap.of("customer", customer); });
-
setInitialValues()
- позволяет задать начальные значения атрибутов создаваемой сущности. Принимает объектMap
, в котором ключами являются имена атрибутов, а значениями - значения атрибутов. Например:Map<String, Object> values = new HashMap<>(); values.put("type", CarType.PASSENGER); carCreateAction.setInitialValues(values);
Пример использования
setInitialValues()
приведен также в разделе рецептов разработки. -
setInitialValuesSupplier()
отличается отsetInitialValues()
тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными черезsetInitialValues()
и могут переопределять их. Например:carCreateAction.setInitialValuesSupplier(() -> ParamsMap.of("type", /* value depends on the current state of the screen */));
-
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableCreate.setBeforeActionPerformedHandler(() -> { showNotification("The new customer instance will be created"); return isValid(); });
-
afterCommit()
- вызывается действием после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие. -
setAfterCommitHandler()
- позволяет задать обработчик, который будет вызван после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный обработчик можно использовать вместо переопределения методаafterCommit()
, тем самым избавившись от необходимости создания наследника действия. Например:@Named("customersTable.create") private CreateAction customersTableCreate; @Override public void init(Map<String, Object> params) { customersTableCreate.setAfterCommitHandler(new CreateAction.AfterCommitHandler() { @Override public void handle(Entity entity) { showNotification("Committed", NotificationType.HUMANIZED); } }); }
-
afterWindowClosed()
- вызывается действием в последнюю очередь после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие. -
setAfterWindowClosedHandler()
- позволяет задать обработчик, который будет вызван после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный обработчик можно использовать вместо переопределения методаafterWindowClosed()
, тем самым избавившись от необходимости создания наследника действия.
EditAction
EditAction
- действие с идентификатором edit. Открывает экран редактирования для выбранного экземпляра сущности. Если экран редактирования успешно закоммитил экземпляр в базу данных, то EditAction
обновляет этот экземпляр в источнике данных таблицы.
В классе EditAction
определены следующие специфические методы:
-
setOpenType()
- позволяет задать режим открытия экрана редактирования сущности. По умолчанию экран открывается в режимеTHIS_TAB
.Так как довольно часто требуется открывать экраны редактирования в другом режиме (как правило,
DIALOG
), при декларативном создании действияedit
в элементеaction
можно указать атрибутopenType
с нужным значением. Это избавляет от необходимости получать ссылку на действие в контроллере и программно устанавливать данное свойство. Например:<table id="usersTable"> <actions> <action id="edit" openType="DIALOG"/>
-
setWindowId()
- позволяет задать идентификатор экрана редактирования сущности. По умолчанию используется экран{имя_сущности}.edit
, напримерsales$Customer.edit
. -
setWindowParams()
- позволяет задать параметры экрана редактирования, передаваемые в его методinit()
. Далее эти параметры можно использовать напрямую в запросе источника данных через префиксparam$
или инжектировать в контроллер экрана с помощью аннотации@WindowParam
. -
setWindowParamsSupplier()
отличается отsetWindowParams()
тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными черезsetWindowParams()
и могут переопределять их. Например:customersTableEdit.setWindowParamsSupplier(() -> ParamsMap.of("category", /* some value dependent on the current state of the screen */));
-
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableEdit.setBeforeActionPerformedHandler(() -> { showNotification("The customer instance will be edited"); return isValid(); });
-
afterCommit()
- вызывается действием после того, как экран редактирования успешно закоммитил сущность и был закрыт. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие. -
setAfterCommitHandler()
- позволяет задать обработчик, который будет вызван после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный обработчик можно использовать вместо переопределения методаafterCommit()
, тем самым избавившись от необходимости создания наследника действия. Например:@Named("customersTable.edit") private EditAction customersTableEdit; @Override public void init(Map<String, Object> params) { customersTableEdit.setAfterCommitHandler(new EditAction.AfterCommitHandler() { @Override public void handle(Entity entity) { showNotification("Committed", NotificationType.HUMANIZED); } }); }
-
afterWindowClosed()
- вызывается действием в последнюю очередь после закрытия экрана редактирования, независимо от того, была ли закоммичена редактируемая сущность. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие. -
setAfterWindowClosedHandler()
- позволяет задать обработчик, который будет вызван после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный обработчик можно использовать вместо переопределения методаafterWindowClosed()
, тем самым избавившись от необходимости создания наследника действия. -
getBulkEditorIntegration()
позволяет настроить массовое редактирование строк таблицы, для этого атрибутmultiselect
таблицы должен иметь значениеtrue
. Компонент BulkEditor будет открыт, если при вызовеEditAction
в таблице выделено более одной строки.Возвращаемый экземпляр
BulkEditorIntegration
можно изменить с помощью следующих методов:-
setOpenType()
, -
setExcludePropertiesRegex()
, -
setFieldValidators()
, -
setModelValidators()
, -
setAfterEditCloseHandler()
.
@Named("clientsTable.edit") private EditAction clientsTableEdit; @Override public void init(Map<String, Object> params) { super.init(params); clientsTableEdit.getBulkEditorIntegration() .setEnabled(true) .setOpenType(WindowManager.OpenType.DIALOG); }
-
RemoveAction
RemoveAction
- действие с идентификатором remove. Предназначено для удаления выбранного экземпляра сущности.
В классе RemoveAction
определены следующие специфические методы:
-
setAutocommit()
- позволяет управлять моментом удаления сущности из базы данных. По умолчанию после срабатывания действия и удаления сущности из источника данных у источника вызывается методcommit()
, в результате чего сущность удаляется из базы данных. Cвойствоautocommit
можно установить вfalse
либо методомsetAutocommit()
, либо соответствующим параметром конструктора. В результате после удаления сущности из источника данных для подтверждения удаления потребуется явно вызвать методcommit()
источника данных.Значение
autocommit
не влияет на работу источников данных в режимеDatasource.CommitMode.PARENT
, то есть тех, которые обеспечивают редактирование композиционных сущностей. -
setConfirmationMessage()
- позволяет задать текст сообщения в диалоге подтверждения удаления. -
setConfirmationTitle()
- позволяет задать заголовок диалога подтверждения удаления. -
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableRemove.setBeforeActionPerformedHandler(() -> { showNotification("The customer instance will be removed"); return isValid(); });
-
afterRemove()
- вызывается действием после успешного удаления сущности. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие. -
setAfterRemoveHandler()
позволяет задать обработчик, который будет вызван после успешного удаления сущности. Данный обработчик можно использовать вместо переопределения методаafterWindowClosed()
, тем самым избавившись от необходимости создания наследника действия. Например:@Named("customersTable.remove") private RemoveAction customersTableRemove; @Override public void init(Map<String, Object> params) { customersTableRemove.setAfterRemoveHandler(new RemoveAction.AfterRemoveHandler() { @Override public void handle(Set removedItems) { showNotification("Removed", NotificationType.HUMANIZED); } }); }
RefreshAction
RefreshAction
- действие с идентификатором refresh. Предназначено для обновления (перезагрузки) коллекции сущностей. При срабатывании вызывает метод refresh()
источника данных, с которым связан компонент.
В классе RefreshAction
определены следующие специфические методы:
-
setRefreshParams()
- позволяет задать параметры, передаваемые в методCollectionDatasource.refresh()
, для использования внутри запроса. По умолчанию никакие параметры не передаются. -
setRefreshParamsSupplier()
отличается отsetRefreshParams()
тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными черезsetRefreshParams()
и могут переопределять их. Например:customersTableRefresh.setRefreshParamsSupplier(() -> ParamsMap.of("number", /* some value dependent on the current state of the screen */));
AddAction
AddAction
- действие с идентификатором add. Предназначено для выбора существующего экземпляра сущности и добавления его в коллекцию. При срабатывании открывает экран выбора сущностей.
В классе AddAction
определены следующие специфические методы:
-
setOpenType()
- позволяет задать режим открытия экрана выбора сущности. По умолчанию экран открывается в режимеTHIS_TAB
.Так как довольно часто требуется открывать экраны выбора в другом режиме (как правило,
DIALOG
), при декларативном создании действияadd
в элементеaction
можно указать атрибутopenType
с нужным значением. Это избавляет от необходимости получать ссылку на действие в контроллере и программно устанавливать данное свойство. Например:<table id="usersTable"> <actions> <action id="add" openType="DIALOG"/>
-
setWindowId()
- позволяет задать идентификатор экрана выбора сущности. По умолчанию используется экран{имя_сущности}.lookup
, напримерsales$Customer.lookup
. Если такого экрана не существует, то делается попытка открыть экран{имя_сущности}.browse
, напримерsales$Customer.browse
. -
setWindowParams()
- позволяет задать параметры экрана выбора, передаваемые в его методinit()
. Далее эти параметры можно использовать напрямую в запросе источника данных через префиксparam$
или инжектировать в контроллер экрана с помощью аннотации@WindowParam
. -
setWindowParamsSupplier()
отличается отsetWindowParams()
тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными черезsetWindowParams()
и могут переопределять их. Например:tableAdd.setWindowParamsSupplier(() -> ParamsMap.of("customer", getItem()));
-
setHandler()
- позволяет задать объект, реализующий интерфейсWindow.Lookup.Handler
, передаваемый в экран выбора. По умолчанию используется объект классаAddAction.DefaultHandler
. -
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableAdd.setBeforeActionPerformedHandler(() -> { showNotification("The new customer will be added"); return isValid(); });
ExcludeAction
ExcludeAction
- действие с идентификатором exclude. Позволяет исключать экземпляры сущности из коллекции, не удаляя их из базы данных. Класс данного действия является наследником RemoveAction
, однако при срабатывании вызывает у CollectionDatasource
не removeItem()
, а excludeItem()
. Кроме того, для вложенных источников данных ExcludeAction
разрывает связь с родительской сущностью, поэтому с помощью данного действия можно организовать редактирование ассоциации one-to-many.
В классе ExcludeAction
в дополнение к RemoveAction
определены следующие специфические методы:
-
setConfirm()
- показывать ли диалог подтверждения удаления. Это свойство можно также установить через конструктор действия. По умолчанию установлено вfalse
. -
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableExclude.setBeforeActionPerformedHandler(() -> { showNotification("The selected customer will be excluded"); return isValid(); });
ExcelAction
ExcelAction
- действие с идентификатором excel. Предназначено для экспорта данных таблицы в формат XLS и выгрузки соответствующего файла. Данное действие можно связать только с компонентами Table, GroupTable и TreeTable.
При программном создании действия можно задать параметр конструктора display
, передав реализацию интерфейса ExportDisplay
для выгрузки файла. По умолчанию используется стандартная реализация.
В классе ExcelAction
определены следующие специфические методы:
-
setFileName()
- позволяет задать имя выгружаемого файла Excel без расширения. -
getFileName()
- возвращает имя выгружаемого файла Excel без расширения. -
setBeforeActionPerformedHandler()
позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращаетtrue
, действие будет выполнено, еслиfalse
- отменено. Например:customersTableExcel.setBeforeActionPerformedHandler(() -> { showNotification("The selected data will ve downloaded as an XLS file"); return isValid(); });