Telerik UI for Windows 8 HTML

By default RadTokenInput allows the user to search and select only from a list of predefined items. The following example shows how this behavior can be changed, so that the user can type and select free text while still be able to choose from the available items.

  1. Define a simple RadTokenInput in the markup. You need only the data properties to be set - dataSource, dataValueField and dataTextField.

    Mark-up Copy imageCopy
    <span id="tokenInput" data-win-control="Telerik.UI.RadTokenInput" data-win-options="{
        dataSource: {
            data: Tokens.SampleData
        },
        dataValueField: 'id',
        dataTextField: 'text'
    }"></span>

    Below is a code sample of the sample data array and how it has been called from a namespace, so it can be used in the markup definition of RadTokenInput. Also, the variable that will hold the control's object is declared here.

    Sample Data Array Copy imageCopy
    var tokenInput,
        sampleData = [
        { id: 1, text: "New York" },
        { id: 2, text: "Philadelphia" },
        { id: 3, text: "Boston" }
        ];
    
    WinJS.Namespace.define("Tokens", {
        SampleData: sampleData
    });
    
  2. Access the RadTokenInput object and its input element. Get RadTokenInput instance and assign it to the already declared variable. Get the control's text input element by its class and add a "mousedown" event handler to it. This has to be done in the ready() function when you are using single page navigation or in the promise returned by the processAll() function when building a blank application. This is necessary, because in order to get elements or controls from the DOM, they have to be loaded or initialized there first.

    Accessing the DOM Objects Copy imageCopy
    tokenInput = Telerik.UI.find.TokenInput("#tokenInput");
    
    var tokenInputField = document.querySelector("#tokenInput .k-input");
    tokenInputField.addEventListener("keydown", tokenKeyDownHandler);
    
  3. Create the text input's "keydown" event handler. The code sample below represents the following logic.

    1. Check if the key that has been pressed is the Enter key.

    2. If the above is true, check if there is text written in the text input box.

    3. If there is a text in the input field, create a new object with the text and unique value and add it to the control's dataSource.

    4. Finally, select the newly added item via the select() method.

    The control still handles the case when the input text matches a predefined item, so you don't need to handle it yourself.

    Text Input's Onkeydown Event Handler Copy imageCopy
    function tokenKeyDownHandler(e) {
        var enterKey = 13;
        if (e.keyCode == enterKey) {
            var text = e.target.value;
    
            if (text) {
                var data = tokenInput.dataSource.data;
    
                var value = data[data.length - 1].id + 1;
                var item = {
                    id: value,
                    text: text
                };
                tokenInput.dataSource.add(item);
    
                var items = tokenInput.list;
                var toSelect = $("li:contains('" + text + "')", items);
                tokenInput.select(toSelect);
            }
        }
    }
    

    Alternatively, you can use RadTokenInput's value property to select the values programmatically. To visually refresh the control's selection, you need to assign the value property an array of values. You need to copy all previously selected items, add the new item and assign the resulting array to the value property.

    Furthermore, when the user types something in the text input of the control, the dataSource is automatically filtered. When they input a completely new text that is not to be found in the predefined items, the dataSource is empty. Therefore, you must clear the dataSource.filter property before the new item is added, so that the previously selected items can be selected again. Below is a code snippet for the second alternative.

    Text Input's Onkeydown Event Handler Copy imageCopy
    function tokenKeyDownHandlerValue(e) {
        var enterKey = 13;
        if (e.keyCode == enterKey) {
            var text = e.target.value;
    
            if (text) {
                var data = tokenInput.dataSource.data;
    
                var value = data[data.length - 1].id + 1;
                var item = {
                    id: value,
                    text: text
                };
                tokenInput.dataSource.filter = null;
                tokenInput.dataSource.add(item);
    
                var tokenValue = [];
                for (var i = 0; i < tokenInput.value.length; i++) {
                    tokenValue[i] = tokenInput.value[i];
                }
    
                tokenValue.push(item.id);
                tokenInput.value = tokenValue;
            }
        }
    }
    

With this functionality RadTokenInput behaves just like RadComboBox with multiple selected items. The difference between the two is that the tokens can be unselected by the user with the RadTokenInput control.

This implementation is part of our SDK Examples and is available for download at the following link: Telerik Windows 8 HTML SDK under TokenInput/SelectFreeTextWithTokenInput.

See Also