5.5.2.1.40. TokenList
LIVE DEMO

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

The component is implemented for both Web Client and Desktop Client.

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

<dsContext>
    <datasource id="orderDs"
                class="com.sample.sales.entity.Order"
                view="order-edit">
        <collectionDatasource id="productsDs" property="products"/>
    </datasource>
    <collectionDatasource id="allProductsDs"
                          class="com.sample.sales.entity.Product"
                          view="_minimal">
        <query>select p from sales$Product p order by p.name</query>
    </collectionDatasource>
</dsContext>
<layout>
    <tokenList id="productsList" datasource="productsDs" inline="true" width="500px">
        <lookup optionsDatasource="allProductsDs"/>
    </tokenList>

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

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 datasource. Selection screen identifier is selected according to the rules for the PickerField.LookupAction standard action. Clicking the Clear button will remove all elements from the TokenList component datasource.

    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"
           datasource="orderItemsDs"
           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 PickerField.LookupAction standard action.

    • openType attribute defines how the lookup screen will be opened, similar to what is described for the PickerField.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 so 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.

Attributes of tokenList

align - caption - captionProperty - clearEnabled - datasource - description - editable - enable - 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 - setItemClickListener