Multi-select Token Control

Description

The Multi-select Token control is a dropdown control with an auto-complete list that inserts tokens that can be removed by clicking an 'x' button on the token or using the delete or backspace key on the keyboard.

Discussion

The Multi-select Token control is similar to the Edit-combo control and the Auto-suggest control. However, the selected values are displayed as 'tokens' (as shown in the image below where 'Belgium', 'Brazil' and 'Canada' are selected). A selected value can be removed by clicking on the 'x' icon in the token.

The user can select values from a pick list as shown in the image below. The pick-list is automatically displayed when the user types in the input control or clicks on the optional down arrow. The user can insert a token by selecting a choice from the dropdown or by typing the value into the control and then pressing the Enter key.

Tokens are removed by clicking the 'x' icon or by placing the cursor after a token and using the Backspace key.

The choices for the pick-list can be statically defined as a fixed list of options or dynamically populated using a SQL query or Xbasic function.

 How to Add a Multi-select Token Control to a UX Component

To add a Multi-select Token control to a UX component, select the [More...] item in the Data Controls section of the UX toolbox.

The Multi-select Token control is a Data Control. This means it can be used with the UX Component's .getValue() and a .setValue() methods. When the UX component is submitted, the Multi-select Token control's value is submitted as a comma delimited list of values.

For example, if there are three tokens selected with values of 'USA', 'UK' and 'Canada', the value submitted is 'USA,UK,Canada'.

To set the value in a Multi-select Token control, the values must be specified as an array. For example:

{dialog.object}.setValue('MY_MULTISELECT_TOKEN_CONTROL',['USA','UK','Canada']);

 Setting the Multi-Select Token Control Properties

To set the properties of a Multi-select Token control, click the smart field button for the Control properties property in the Property sheet.

The configuration genie window is displayed, as shown below:

  •  Method for defining choices

    The Method for defining choices specifies how the data for the choices displayed by the control are obtained. Choices can be specified as a static list of choices, a SQL query, or an Xbasic function. The SQL query can be the name of a table in a database or a custom SQL statement (such as a call to a stored procedure.)

    If the FieldsFromTable option is used, two columns from the table must be selected to define the display value and stored value. The first column (Value column) defines the value for the selected token. The second column (Display column) is the value shown in the input control for the Token. An optional 3rd column can also be selected - List Display column. This property defines the display value shown in the choice list. The Display property of each choice will be used if no List Display column is specified.

    The query for a SQL statement must return a result set with either 2 or 3 columns. The first column must have a name of 'value', the second column must have a name of 'display' and the optional 3rd column must have a name of 'listDisplay'. For example:

    SELECT contactname as value, customerId as display from Customers
  •  Display icon to open choice list

    When the user begins to type in the control, the choice list is opened and is filtered on the text the user has typed. This is similar to how an auto-suggest control works. The Display icon to open choice list option controls whether or not an icon to open the choice list is shown. The icon can be displayed on the left or right side of the input control.

  •  User must select from choices

    If un-checked, the user can type in any value into the control. When the user presses Enter, the text the user has typed is added to the token list. If this property is checked, if the user types in a value and then presses Enter and the text the user has typed is not in the choice list (i.e. is not the value property for one of the choices in the list), a new token is not added.

  •  Icons

    The icons used to display the choice list and to delete a previously selected token can be customized using the Icons property. The Multi-select Token control only supports using SVG icons.

  •  Token CSS type

    The Token CSS type property can be used to customize the appearance of the selected tokens. The Token CSS type can either be set to Default or Custom. If Default is selected, tokens can be configured to have a square or round border using the Token border style property. In the images above, the border style has been set to rounded.

  •  onChange

    The onChange event can be used to execute JavaScript code when the value in the control changes. This event will fire each time the user makes a selection from the choice list to select a new token, or when the user types in the value of a new token and presses Enter. The JavaScript code can reference this.value, an array of the selected token values.

  •  valueNotInList

    The valueNotInList event can be used to execute JavaScript code when the user enters a value that is not in the list of choices. This property is only shown if the User must select from choices property is unchecked. If the user types in a value that in is not in the list of choices, the code defined for this event will execute. This event can be used to add the value to a database.

 Dynamically Populating Choices at Runtime

Choices in the Multi-select Token control can be dynamically populated at runtime by calling the control's .populate() method. For example, the following JavaScript will populate the choices for the Multi-Select Token control with an ID of 'MST1':

var _d = {
    "data":[
        {"value" : "Argentina", "display" : "Argentina"},
        {"value" : "Austria", "display" : "Austria"},
        {"value" : "Belgium", "display" : "Belgium"},
        {"value" : "Brazil", "display" : "Brazil"},
        {"value" : "Canada", "display" : "Canada"},
        {"value" : "Denmark", "display" : "Denmark"},
        {"value" : "Finland", "display" : "Finland"},
        {"value" : "France", "display" : "France"},
        {"value" : "Germany", "display" : "Germany"},
        {"value" : "Ireland", "display" : "Ireland"},
        {"value" : "Italy", "display" : "Italy"},
        {"value" : "Mexico", "display" : "Mexico"},
        {"value" : "Norway", "display" : "Norway"},
        {"value" : "Poland", "display" : "Poland"},
        {"value" : "Portugal", "display" : "Portugal"},
        {"value" : "Spain", "display" : "Spain"},
        {"value" : "Sweden", "display" : "Sweden"},
        {"value" : "Switzerland", "display" : "Switzerland"},
        {"value" : "UK", "display" : "UK"},
        {"value" : "USA", "display" : "USA"},
        {"value" : "Venezuela", "display" : "Venezuela"}
    ]
};

var obj = {dialog.object}.getControl('MST1');
obj.populate(_d);

 Text Highlighting

When you start typing into a multi-select tokens control, the list of choices that is displayed, which is filtered, by the text you have typed, now shows the matches in the choice list with the text you have typed in bold.

For example, in the image below, the user has typed 'ou'. The choice list shows all of the items that contain the string 'ou'. Notice that in the choice list, all instances of the string 'ou' are highlighted:

For multi-select token controls created in Alpha Anywhere 4.4.5 or earlier, the control must be edited and re-saved to add Text Highlighting.

 Videos

Adding a Multi-select Tokens Control to a UX Component

The Multi-select Tokens control operates much like the Gmail app when you address an e-mail to multiple recipients. You can type values into a control, or make selections from a drop-down choice list. Each selection is shown in the control as a 'token'. Tokens can be removed from the list of selections by either hitting the backspace key while focus is in the control, or by clicking on the 'delete' icon in the token.

A common use case for the Multi-select Tokens control is to define selection criteria for a List control. In this video we show how a Multi-select Tokens control is used to select a list of countries. The List control is then filtered to show the countries that match the selected tokens. For example, if tokens for 'USA' and 'UK' are selected, the List is filtered to show customers in either 'USA' or 'UK'

Download Component

2017-07-23