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
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 |
---|
<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 |
---|
<span id="myTokenInput">
</span> |
JavaScript | Copy |
---|
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 |
---|
<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 |
---|
<span id="codeTokenInput"></span> |
Initializing RadTokenInput in the Code-Behind | Copy |
---|
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:
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 |
---|
var tokenInput = document.getElementById("myTokenInput").winControl; |
Once you have a reference to the control, you can modify its properties as required:
JavaScript | Copy |
---|
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 |
---|
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("myTokenInput"), {
onchange: changeHandlerFnName });
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("myTokenInput"), {
onchange: function(e) {
}); |
Using the addEventListener Method | Copy |
---|
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 |
---|
var tokenInput = document.getElementById("myTokenInput").winControl;
var selectedValues = tokenInput.value;
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 |
---|
tokenInput.value = 1;
tokenInput.value = [1, 3, 5]; |
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 |
---|
var tokenInput = document.getElementById("myTokenInput").winControl;
var selectedData = tokenInput.dataItems(); |
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 |
---|
var items = tokenInput.list;
var toSelect = $("li:contains('Andrew Fuller')",items);
tokenInput.select(toSelect); |
See Also