3.5.2.1.48. TokenList
LIVE DEMO
API DOCS

TokenList component offers a simplified way of working with lists: instance names are listed vertically or horizontally, adding is done using drop-down list, removal – using the buttons located near each instance.

gui tokenList

XML-name of the component: tokenList

Below is an example description of TokenList in an XML-descriptor of a screen:

<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>

In the example above, the nested productsDc data container which includes a collection of products within an order is defined, as well as allProductsDs data container containing a collection of all products available in the database. The TokenList component with productsList identifier displays the content of the productsDc container and enables changing the collection by adding instances from allProductsDc.

tokenList attributes:

  • position – sets the position for the drop-down list. The attribute can take two values: TOP, BOTTOM. Default is TOP.

gui tokenListBottom

  • inline attribute defines how the list with selected items will be displayed: vertically or horizontally. true corresponds to horizontal alignment, false – to vertical. An example of a component with horizontal alignment:

gui tokenListInline

  • simple – when set to true, the items selection component will be hidden with only the Add button left. Clicking the Add button opens the screen with the list of entity instances which type is defined by the data container. Selection screen identifier is selected according to the rules for the PickerField standard lookup action. Clicking the Clear button will remove all elements from the TokenList component’s container.

    gui tokenListSimple withClear

  • clearEnabled - when set to false, the Clear button is hidden.

tokenList elements:

  • lookup − values selection component descriptor.

    Attributes of the lookup element:

    • lookup attribute makes it possible to select items using an entity lookup screen:

      gui tokenListLookup

    • inputPrompt - a textual prompt that is displayed in the lookup field to prompt the user for input. If not set, the lookup is empty.

      <tokenList id="linesList" dataContainer="orderItemsDс" property="items" width="320px">
    <lookup optionsDatasource="allItemsDs" inputPrompt="Choose an item"/>
</tokenList>
      gui TokenList inputPrompt

    • lookupScreen attribute sets the identifier of the screen used for items selection in lookup="true" mode. If this attribute is not set, screen identifier is selected according to the rules for the com.haulmont.cuba.gui.actions.picker.LookupAction standard action.

    • openType attribute defines how the lookup screen will be opened, similar to what is described for the com.haulmont.cuba.gui.actions.picker.LookupAction standard action. Default value – THIS_TAB.

    • multiselect - if this attribute’s value is set to true, then true will be passed to parameters map of the lookup screen for the MULTI_SELECT key. This flag can be used to set the screen into multiple selection mode. This flag is defined in the WindowParams enum, and in legacy screens it is convenient to work with it in the following way:

      @Override
public void init(Map<String, Object> params) {
    if (WindowParams.MULTI_SELECT.getBool(getContext())) {
        usersTable.setMultiSelect(true);
    }
}

  • addButton – descriptor of the button for adding items. Can contain caption and icon attributes.

tokenList listeners:

  • ItemClickListener allows you to track the click on tokenList items.

  • ValueChangeListener enables tracking the changes of the tokenList value, as well as of any other components implementing the Field interface. The origin of the ValueChangeEvent can be tracked using isUserOriginated() method.

Attributes of tokenList

align - caption - captionAsHtml - captionProperty - clearEnabled - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datasource - description - descriptionAsHtml - editable - enable - box.expandRatio - height - icon - id - inline - position - simple - stylename - tabIndex - visible - width

Elements of tokenList

addButton - lookup

Attributes of lookup

captionProperty - filterMode - inputPrompt - lookup - lookupScreen - multiselect - openType - optionsDatasource

Attributes of button

caption - icon

API

addValueChangeListener - setContextHelpIconClickHandler - setItemClickListener - setOptionCaptionProvider