Telerik UI for Windows 8 HTML
Contents

The RadTokenInput control for Windows 8 is an HTML/JavaScript component that allows the user to select multiple items from predefined or live data. It then displays the selection as tokens. To use the control, you must specify a data source—you can use a Telerik.Data.DataSource control or even a simple JavaScript array.

This topic contains the following sections.

Prerequisites

Before you declare a Telerik control in your application, make sure that you have added the references to the needed JavaScript and CSS resources, as described here:

Adding Telerik UI for Windows 8 HTML to an HTML Page

Creating a RadTokenInput

To create a RadTokenInput in the HTML markup, add an empty span element with a data-win-control attribute with a value of Telerik.UI.RadTokenInput.

HTML Copy imageCopy
<span data-win-control="Telerik.UI.RadTokenInput">
</span>

Alternatively, you can create a RadTokenInput programmatically through JavaScript by first defining a span element with an id and then passing this id as a first argument to the RadTokenInput constructor.

HTML Copy imageCopy
<span id="myTokenInput">
</span>
JavaScript Copy imageCopy
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("myTokenInput"));

Creating a RadTokenInput without any properties set will not result in a usable control. RadTokenInput needs at least a basic set of data for the user to select from. You can find a basic example of how you can set property values below.

Setting RadTokenInput Options

Just like any other Windows Runtime JavaScript control, the RadTokenInput options can be defined through the data-win-options attribute.

RadTokenInput Markup Definition Copy imageCopy
<span id="markupTokenInput" data-win-control="Telerik.UI.RadTokenInput" data-win-options="{
            dataSource: {
                data: ['McLaren', 'Mercedes', 'Red Bull Racing']
            },
            placeholder: 'Choose a team...'
        }"></span>

Alternatively, you can programmatically pass an options object as a second argument to the control constructor.

Markup Copy imageCopy
<span id="codeTokenInput"></span>
Initializing RadTokenInput in the Code-Behind Copy imageCopy
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("codeTokenInput"), {
    dataSource: {
        data: ['McLaren', 'Mercedes', 'Red Bull Racing']
    },
    placeholder: 'Choose a team...'
});

Both the markup and the JavaScript versions produce the same result. Here is an image of the control and its usage:

tokeninput-gettingstarted

Accessing and Modifying RadTokenInput

You can get ahold of the RadTokenInput object the same way as the native WinJS components—find its DOM element and access its winControl property.

JavaScript Copy imageCopy
var tokenInput = document.getElementById("myTokenInput").winControl;

Once you have a reference to the control, you can modify its properties as required:

JavaScript Copy imageCopy
tokenInput.placeholder = "Start typing...";

Attaching Events

You can either declare an event handler in the options object that you pass to the control during initialization, or you can use the addEventListener method to attach a function for execution upon a certain event. Below you can see samples of both approaches:

Assigning an Event Handler Function During Initialization Copy imageCopy
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("myTokenInput"), {
    onchange: changeHandlerFnName });
// OR
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("myTokenInput"), {
    onchange: function(e) {//...}
});
Note

If you attach the event handler as shown above, in HTML mark-up, you would need to mark the handler function as safe in your code, using the WinJS.Utilities.markSupportedForProcessing function.

Using the addEventListener Method Copy imageCopy
tokenInput.addEventListener("change", changeHandlerFnName);

Getting and Setting Selected Items

To access the selected values in RadTokenInput, use its value property.

Accessing the Selected Items Values Copy imageCopy
var tokenInput = document.getElementById("myTokenInput").winControl;
var selectedValues = tokenInput.value; //Array of selected values or null if there is no selection
var firstSelectedValue = selectedValues[0];

The value property can also be used to set selected items. You can assign a single value or an array of values. If there is no match, no value will be selected.

Setting Selected Items by their Values Copy imageCopy
tokenInput.value = 1;
tokenInput.value = [1, 3, 5]; //Array of item values

If you want to get the raw data items from the data source corresponding to the selected items, use the dataItems() method:

Accessing the Data Entries Corresponding to the Selected Items Copy imageCopy
var tokenInput = document.getElementById("myTokenInput").winControl;
var selectedData = tokenInput.dataItems(); //Array of selected items' corresponding data entries

In order to select an item programmatically, you have to use the select() method. It takes a "li" HTML element as an argument and selects it from the list. The list property returns a jQuery-wrapped list of the "li" elements in the control. You can then use jQuery selectors to search for a given string value in the list. The following example shows how this can be done:

Selecting a Value from the Predefined Items Copy imageCopy
var items = tokenInput.list;
var toSelect = $("li:contains('Andrew Fuller')",items);
tokenInput.select(toSelect);

See Also