list_actions.adoc

Действия с коллекцией (устаревшее)

Warning

Это устаревший API. Новый API, доступный начиная с v.7.0, описан в разделе [std_list_actions].

Для наследников ListComponent (это Table, GroupTable, TreeTable и Tree) набор стандартных действий определен в перечислении ListActionType, классы их реализации находятся в пакете com.haulmont.cuba.gui.components.actions.

Пример использования стандартных действий в таблице:

link:../../../../source/gui/listActions_1.xml[role=include]

Рассмотрим их подробнее.

CreateAction

CreateAction - действие с идентификатором create. Предназначено для создания нового экземпляра сущности и открытия экрана редактирования для этого экземпляра. Если экран редактирования успешно закоммитил новый экземпляр в базу данных, то CreateAction добавляет этот новый экземпляр в источник данных таблицы и делает его выбранным.

В классе CreateAction определены следующие специфические методы:

• setOpenType() - позволяет задать режим открытия экрана редактирования новой сущности. По умолчанию экран открывается в режиме THIS_TAB.

  Так как довольно часто требуется открывать экраны редактирования в другом режиме (как правило, DIALOG), при декларативном создании действия create в элементе action можно указать атрибут openType с нужным значением. Это избавляет от необходимости получать ссылку на действие в контроллере и программно устанавливать данное свойство. Например:

  link:../../../../source/gui/createAction_1.xml[role=include]

• setWindowId() - позволяет задать идентификатор экрана редактирования сущности. По умолчанию используется экран {имя_сущности}.edit, например sales$Customer.edit.

• setWindowParams() - позволяет задать параметры экрана редактирования, передаваемые в его метод init(). Далее эти параметры можно использовать напрямую в запросе источника данных через префикс param$ или инжектировать в контроллер экрана с помощью аннотации @WindowParam.

• setWindowParamsSupplier() отличается от setWindowParams() тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными через setWindowParams() и могут переопределять их. Например:

  link:../../../../source/gui/createAction_5.java[role=include]

• setInitialValues() - позволяет задать начальные значения атрибутов создаваемой сущности. Принимает объект Map, в котором ключами являются имена атрибутов, а значениями - значения атрибутов. Например:

  link:../../../../source/gui/createAction_2.java[role=include]

  Пример использования setInitialValues() приведен также в разделе рецептов разработки.

• setInitialValuesSupplier() отличается от setInitialValues() тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными через setInitialValues() и могут переопределять их. Например:

  link:../../../../source/gui/createAction_4.java[role=include]

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/createAction_6.java[role=include]

• afterCommit() - вызывается действием после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие.

• setAfterCommitHandler() - позволяет задать обработчик, который будет вызван после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный обработчик можно использовать вместо переопределения метода afterCommit(), тем самым избавившись от необходимости создания наследника действия. Например:

  link:../../../../source/gui/createAction_3.java[role=include]

• afterWindowClosed() - вызывается действием в последнюю очередь после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие.

• setAfterWindowClosedHandler() - позволяет задать обработчик, который будет вызван после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный обработчик можно использовать вместо переопределения метода afterWindowClosed(), тем самым избавившись от необходимости создания наследника действия.

EditAction

EditAction - действие с идентификатором edit. Открывает экран редактирования для выбранного экземпляра сущности. Если экран редактирования успешно закоммитил экземпляр в базу данных, то EditAction обновляет этот экземпляр в источнике данных таблицы.

В классе EditAction определены следующие специфические методы:

• setOpenType() - позволяет задать режим открытия экрана редактирования сущности. По умолчанию экран открывается в режиме THIS_TAB.

  Так как довольно часто требуется открывать экраны редактирования в другом режиме (как правило, DIALOG), при декларативном создании действия edit в элементе action можно указать атрибут openType с нужным значением. Это избавляет от необходимости получать ссылку на действие в контроллере и программно устанавливать данное свойство. Например:

  link:../../../../source/gui/editAction_1.xml[role=include]

• setWindowId() - позволяет задать идентификатор экрана редактирования сущности. По умолчанию используется экран {имя_сущности}.edit, например sales$Customer.edit.

• setWindowParams() - позволяет задать параметры экрана редактирования, передаваемые в его метод init(). Далее эти параметры можно использовать напрямую в запросе источника данных через префикс param$ или инжектировать в контроллер экрана с помощью аннотации @WindowParam.

• setWindowParamsSupplier() отличается от setWindowParams() тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными через setWindowParams() и могут переопределять их. Например:

  link:../../../../source/gui/editAction_4.java[role=include]

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/editAction_5.java[role=include]

• afterCommit() - вызывается действием после того, как экран редактирования успешно закоммитил сущность и был закрыт. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие.

• setAfterCommitHandler() - позволяет задать обработчик, который будет вызван после того, как экран редактирования успешно закоммитил новую сущность и был закрыт. Данный обработчик можно использовать вместо переопределения метода afterCommit(), тем самым избавившись от необходимости создания наследника действия. Например:

  link:../../../../source/gui/editAction_2.java[role=include]

• afterWindowClosed() - вызывается действием в последнюю очередь после закрытия экрана редактирования, независимо от того, была ли закоммичена редактируемая сущность. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие.

• setAfterWindowClosedHandler() - позволяет задать обработчик, который будет вызван после закрытия экрана редактирования, независимо от того, была ли закоммичена новая сущность или нет. Данный обработчик можно использовать вместо переопределения метода afterWindowClosed(), тем самым избавившись от необходимости создания наследника действия.

• getBulkEditorIntegration() позволяет настроить массовое редактирование строк таблицы, для этого атрибут multiselect таблицы должен иметь значение true. Компонент BulkEditor будет открыт, если при вызове EditAction в таблице выделено более одной строки.

  Возвращаемый экземпляр BulkEditorIntegration можно изменить с помощью следующих методов:

  • setOpenType(),

  • setExcludePropertiesRegex(),

  • setFieldValidators(),

  • setModelValidators(),

  • setAfterEditCloseHandler().

  link:../../../../source/gui/editAction_3.java[role=include]

RemoveAction

RemoveAction - действие с идентификатором remove. Предназначено для удаления выбранного экземпляра сущности.

В классе RemoveAction определены следующие специфические методы:

• setAutocommit() - позволяет управлять моментом удаления сущности из базы данных. По умолчанию после срабатывания действия и удаления сущности из источника данных у источника вызывается метод commit(), в результате чего сущность удаляется из базы данных. Cвойство autocommit можно установить в false либо методом setAutocommit(), либо соответствующим параметром конструктора. В результате после удаления сущности из источника данных для подтверждения удаления потребуется явно вызвать метод commit() источника данных.

  Значение autocommit не влияет на работу источников данных в режиме Datasource.CommitMode.PARENT, то есть тех, которые обеспечивают редактирование композиционных сущностей.

• setConfirmationMessage() - позволяет задать текст сообщения в диалоге подтверждения удаления.

• setConfirmationTitle() - позволяет задать заголовок диалога подтверждения удаления.

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/removeAction_2.java[role=include]

• afterRemove() - вызывается действием после успешного удаления сущности. Данный метод не имеет реализации и может быть переопределен в наследниках для реакции на это событие.

• setAfterRemoveHandler() позволяет задать обработчик, который будет вызван после успешного удаления сущности. Данный обработчик можно использовать вместо переопределения метода afterWindowClosed(), тем самым избавившись от необходимости создания наследника действия. Например:

  link:../../../../source/gui/removeAction_1.java[role=include]

RefreshAction

RefreshAction - действие с идентификатором refresh. Предназначено для обновления (перезагрузки) коллекции сущностей. При срабатывании вызывает метод refresh() источника данных, с которым связан компонент.

В классе RefreshAction определены следующие специфические методы:

• setRefreshParams() - позволяет задать параметры, передаваемые в метод CollectionDatasource.refresh(), для использования внутри запроса. По умолчанию никакие параметры не передаются.

• setRefreshParamsSupplier() отличается от setRefreshParams() тем, что позволяет получить значения параметров непосредственно перед вызовом действия. Полученные параметры объединяются с предоставленными через setRefreshParams() и могут переопределять их. Например:

  link:../../../../source/gui/refreshAction_1.java[role=include]

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() и могут переопределять их. Например:

  link:../../../../source/gui/addaction_2.java[role=include]

• setHandler() - позволяет задать объект, реализующий интерфейс Window.Lookup.Handler, передаваемый в экран выбора. По умолчанию используется объект класса AddAction.DefaultHandler.

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/addaction_3.java[role=include]

ExcludeAction

ExcludeAction - действие с идентификатором exclude. Позволяет исключать экземпляры сущности из коллекции, не удаляя их из базы данных. Класс данного действия является наследником RemoveAction, однако при срабатывании вызывает у CollectionDatasource не removeItem(), а excludeItem(). Кроме того, для вложенных источников данных ExcludeAction разрывает связь с родительской сущностью, поэтому с помощью данного действия можно организовать редактирование ассоциации one-to-many.

В классе ExcludeAction в дополнение к RemoveAction определены следующие специфические методы:

• setConfirm() - показывать ли диалог подтверждения удаления. Это свойство можно также установить через конструктор действия. По умолчанию установлено в false.

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/excludeAction.java[role=include]

ExcelAction

ExcelAction - действие с идентификатором excel. Предназначено для экспорта данных таблицы в формат XLS и выгрузки соответствующего файла. Данное действие можно связать только с компонентами Table, GroupTable и TreeTable.

При программном создании действия можно задать параметр конструктора display, передав реализацию интерфейса ExportDisplay для выгрузки файла. По умолчанию используется стандартная реализация.

В классе ExcelAction определены следующие специфические методы:

• setFileName() - позволяет задать имя выгружаемого файла Excel без расширения.

• getFileName() - возвращает имя выгружаемого файла Excel без расширения.

• setBeforeActionPerformedHandler() позволяет задать обработчик, который будет вызван до выполнения действия. Если метод возвращает true, действие будет выполнено, если false - отменено. Например:

  link:../../../../source/gui/excelAction.java[role=include]