3.5.2.1.49. TokenList

Компонент TokenList представляет собой упрощенный вариант работы со списком сущностей: названия экземпляров располагаются в вертикальном или горизонтальном списке, добавление производится из выпадающего списка, удаление - с помощью кнопок, расположенных рядом с каждым экземпляром.

gui tokenList

XML-имя компонента: tokenList

Пример описания компонента TokenList в XML-дескрипторе экрана:

<data>
    <instance id="orderDc" class="com.company.sales.entity.Order" view="order-edit">
        <loader/>
        <collection id="productsDc" property="products"/>
    </instance>
    <collection id="allProductsDc" class="com.company.sales.entity.Product" view="_minimal">
        <loader id="allProductsDl">
            <query><![CDATA[select e from sales_Product e order by e.name]]></query>
        </loader>
    </collection>
</data>
<layout>
    <tokenList id="productsList" dataContainer="orderDc" property="products" inline="true" width="500px">
        <lookup optionsContainer="allProductsDc"/>
    </tokenList>
</layout>

Здесь в элементе data определен вложенный контейнер данных productsDc, содержащий коллекцию входящих в состав заказа продуктов. Кроме того, определен контейнер allProductsDc, содержащий коллекцию всех продуктов, имеющихся в базе данных. Компонент TokenList с идентификатором productsList отображает содержимое контейнера productsDc, а также позволяет изменять эту коллекцию, добавляя в него экземпляры из контейнера allProductsDc.

Атрибуты tokenList:

  • position - задает позиционирование раскрывающегося списка. Атрибут может принимать два значения: TOP, BOTTOM. По умолчанию TOP.

    gui tokenListBottom
  • Атрибут inline задает отображение списка выбранных значений: вертикально или горизонтально. Значение true соответствует горизонтальному расположению, значение false − вертикальному. Так выглядит компонент с горизонтальным расположением значений:

    gui tokenListInline
  • simple - значение true позволяет убрать компонент выбора, оставляя только кнопку добавления и очистки списка. При нажатии на кнопку добавления Add сразу показывается экран списка экземпляров сущности, тип которой задан контейнером данных. Идентификатор экрана выбора определяется по правилам, описанным для стандартного действия LookupAction для PickerField. Кнопка очистки списка Clear удаляет все элементы из контейнера данных компонента TokenList.

    gui tokenListSimple withClear
  • clearEnabled - значение false позволяет скрыть кнопку очистки Clear.

Элементы tokenList:

  • lookup − описатель компонента выбора значений.

    Атрибуты элемента lookup:

    • Атрибут lookup задает возможность выбора значений через экран выбора сущностей:

      gui tokenListLookup
    • inputPrompt - текстовая подсказка, которая отображается в поле выбора. Если подсказка не задана, поле будет пустым.

      <tokenList id="linesList" dataContainer="orderItemsDс" property="items" width="320px">
          <lookup optionsContainer="allItemsDс" inputPrompt="Choose an item"/>
      </tokenList>
      gui TokenList inputPrompt
    • Атрибут lookupScreen задает идентификатор экрана для выбора значений в режиме lookup="true". Если данный атрибут не задан, то идентификатор экрана выбора определяется по правилам, описанным для стандартного действия com.haulmont.cuba.gui.actions.picker.LookupAction.

    • Атрибут openType можно задать способ открытия экрана выбора, аналогично описанному для стандартного действия com.haulmont.cuba.gui.actions.picker.LookupAction. По умолчанию - THIS_TAB.

    • Если значение атрибута multiselect установлено в true, то в экране выбора сущностей будет установлен режим множественного выбора. Каждый экран, в котором предполагается изменять режим выбора, должен реализовать интерфейс com.haulmont.cuba.gui.screen.MultiSelectLookupScreen. Класс StandardLookup реализует этот интерфейс по умолчанию. Если вам нужно предоставить пользовательскую реализацию, переопределите метод setLookupComponentMultiSelect, например:

      public class ProductsList extends StandardLookup {
          @Inject
          private GroupTable<Product> productsTable;
      
          @Override
          public void setLookupComponentMultiSelect(boolean multiSelect) {
              productsTable.setMultiSelect(multiSelect);
          }
      }
  • addButton − описатель кнопки добавления значений. Может содержать атрибуты caption и icon.

Компонент может принимать список опций из data container: для этого используется атрибут optionsContainer. Кроме этого, список опций для компонента можно указать с помощью методов setOptions(), setOptionsList() и setOptionsMap(). В этом случае атрибут <lookup> в дескрипторе экрана можно оставить пустым.

  • setOptionsList() позволяет программно задать список опций компонента. Для этого объявляем компонент в XML-дескрипторе:

    <tokenList id="tokenList"
               dataContainer="orderDc"
               property="items"
               width="320px">
        <lookup/>
    </tokenList>

    Затем инжектируем компонент в контроллер и задаем ему список опций:

    @Inject
    private TokenList<OrderItem> tokenList;
    @Inject
    private CollectionContainer<OrderItem> allItemsDc;
    
    @Subscribe
    public void onAfterShow(AfterShowEvent event) {
        tokenList.setOptionsList(allItemsDc.getItems());
    }

    Того же результата можно достигнуть, используя метод setOptions(), который позволяет работать со всеми типами опций:

    @Inject
    private TokenList<OrderItem> tokenList;
    @Inject
    private CollectionContainer<OrderItem> allItemsDc;
    
    @Subscribe
    public void onAfterShow(AfterShowEvent event) {
        tokenList.setOptions(new ContainerOptions<>(allItemsDc));
    }

Компонент TokenList способен обрабатывать ввод пользователя при отсутствии подходящей опции в списке. Обработчик новых опций вызывается, если пользователь ввел некоторое значение, не совпадающее ни с одной из опций, и нажал Enter.

Существует два способа использовать newOptionHandler:

  • Декларативно, используя аннотацию @Install в контроллере экрана:

    @Inject
    private CollectionContainer<Tag> tagsDc;
    @Inject
    private Metadata metadata;
    
    @Install(to = "tokenList", subject = "newOptionHandler")
    private void tokenListNewOptionHandler(String string) {
        Tag newTag = metadata.create(Tag.class);
        newTag.setName(string);
        tagsDc.getMutableItems().add(newTag);
    }
  • Программно с помощью метода setNewOptionHandler():

    @Inject
    private CollectionContainer<Tag> tagsDc;
    @Inject
    private Metadata metadata;
    @Inject
    private TokenList<Tag> tokenList;
    
    @Subscribe
    public void onInit(InitEvent event) {
        tokenList.setNewOptionHandler(string -> {
            Tag newTag = metadata.create(Tag.class);
            newTag.setName(string);
            tagsDc.getMutableItems().add(newTag);
        });
    }

Слушатели tokenList:

  • ItemClickListener позволяет отслеживать клики по элементам tokenList.

  • ValueChangeListener отслеживает изменения значения`tokenList`, так же как и любого другого компонента, реализующего интерфейс Field. Источник события ValueChangeEvent можно отследить с помощью метода isUserOriginated().