Telerik UI for Windows 8 HTML

The RadComboBox control for Windows 8 is an HTML/JavaScript component that allows the user to select one item from predefined or live (xhr requested) data. To use the control, you must specify a datasource. You can use a Telerik.Data.DataSource component 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 RadComboBox

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

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

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

HTML Copy imageCopy
<span id="myComboBox">
</span>
JavaScript Copy imageCopy
var combobox = new Telerik.UI.RadComboBox(document.getElementById("myComboBox"));

Defining RadComboBox without any properties set will not render a usable control. Without data to search from RadComboBox cannot serve its purpose. Therefore, you need to at least specify a dataSource. The rest of RadComboBox's properties will be set to their default values. You can see a basic example of defining a usable RadComboBox in the next step.

Setting RadComboBox Options

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

RadComboBox Markup Definition Copy imageCopy
<span id="markupComboBox" data-win-control="Telerik.UI.RadComboBox" data-win-options="{
        dataSource: [
            { Name: 'Mercedes', ID: 1 },
            { Name: 'McLaren', ID: 2 },
            { Name: 'Red Bull Racing', ID: 3 }
        ],
        placeholder: 'Choose a team...',
        filter: 'startswith',
        dataTextField: 'Name',
        dataValueField: 'ID'
        }"></span>

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

Markup Copy imageCopy
<span id="codeComboBox"></span>
RadComboBox Initializing Programmatically Copy imageCopy
var comboBox = new Telerik.UI.RadComboBox(document.getElementById("codeComboBox"), {
    dataSource: [
        { Name: 'Mercedes', ID: 1 },
        { Name: 'McLaren', ID: 2 },
        { Name: 'Red Bull Racing', ID: 3 }
    ],
    placeholder: 'Choose a team...',
    filter: 'startswith',
    dataTextField: 'Name',
    dataValueField: 'ID'
});

To see all available configuration options, go to the API reference for RadComboBox

Both of the above examples produce the same result. Below you can see an image of the control and its usage.

combobox-gettingstarted

Accessing and Modifying RadComboBox

You can get a reference to the RadComboBox object the same way as the native WinJS components - find its DOM element and access its winControl property.

JavaScript Copy imageCopy
var combobox = document.getElementById("myComboBox").winControl;

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

JavaScript Copy imageCopy
combobox.autoSuggest = true;

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 examples of both approaches:

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

Note that if you attach the event handler using the on[eventname] property, but in HTML mark-up, you would need to mark the handler function as safe in your code, using the WinJS.Utilities.markSupportedForProcessing function.

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

Getting and Setting a Value

RadComboBox allows the user to select an item from a dropdown list or to input any text. The value property allows you to select an item from the predefined item list. You can also use the value property to get the value of the selected item.

Getting and Setting a Selected Item through its Value Copy imageCopy
var comboBox = document.getElementById("comboBox").winControl;

var comboBoxVal = comboBox.value;
comboBox.value = comboBoxVal;

Note that when you set a value to the RadComboBox, if it matches a value of a predefined item, the text in the input field will be updated with the item's text. If there is no match, the input box will still be populated with the value you set.

Use the text property to get the input string from the control. The text property can also be used to select an item from the predefined list by its text. If there is no match, the input box will still be populated with the text you set.

Getting and Setting a Selected Item through its Text Copy imageCopy
var comboBoxText = comboBox.text;
comboBox.text = comboBoxText;

The index property gets or sets the selected item through its index in the item list. Note that if the user does not select an item and types any text instead, the index property will return -1. Once you have the selected item index, you can get the corresponding data entry through the dataItem() method.

Getting and Setting the Selected Item through its Index Copy imageCopy
comboBox.index = 0;
var selectedItemIndex = comboBox.index;

if (selectedItemIndex != -1) {
  item = comboBox.dataItem(selectedItemIndex);
}

You can also use the select() method to set a selected item. 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 an Item through its HTML Element Copy imageCopy
var items = comboBox.list;
var toSelect = $("li:contains('Andrew Fuller')",items);
comboBox.select(toSelect);

See Also