Telerik UI for Windows 8 HTML
Contents

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

Creating a RadDropDownList

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

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

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

HTML Copy imageCopy
<span id="myDropDownList">
</span>
JavaScript Copy imageCopy
var dropdown = new Telerik.UI.RadDropDownList(document.getElementById("myDropDownList"));

Defining RadDropDownList without setting any properties will not result in a usable control. You need to at least specify a dataSource to have items in the drop down list to choose from. You can find how you can assign a dataSource and set other of RadDropDownList's properties in the next section.

Setting RadDropDownList Options

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

RadDropDownList Markup Definition Copy imageCopy
<span id="markupDropDown" data-win-control="Telerik.UI.RadDropDownList" data-win-options="{
        dataSource: [
            { Name: 'Mercedes', ID: 1 },
            { Name: 'McLaren', ID: 2 },
            { Name: 'Red Bull Racing', ID: 3 }
        ],
        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="codeDropDown"></span>
Initializing RadDropDownList in the Code-Behind Copy imageCopy
var dropDown = new Telerik.UI.RadDropDownList(document.getElementById("codeComboBox"), {
    dataSource: [
        { Name: 'Mercedes', ID: 1 },
        { Name: 'McLaren', ID: 2 },
        { Name: 'Red Bull Racing', ID: 3 }
    ],
    dataTextField: 'Name',
    dataValueField: 'ID'
});

To see all available configuration options, go to RadDropDownList

Both of the examples above produce the same result. Here is an image of the control and its usage.

dropdownlist-gettingstarted

Accessing and Modifying RadDropDownList

You can get hold of the RadDropDownList object the same way as the native WinJS components - find its DOM element and access its winControl property.

JavaScript Copy imageCopy
var dropdown = document.getElementById("myDropDown").winControl;

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

JavaScript Copy imageCopy
dropdown.optionLabel = "Pick a name...";

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 dropdown = new Telerik.UI.RadDropDownList(document.getElementById("myDropDown"), {
    onopen: changeHandlerFnName });
// OR
var dropdown = new Telerik.UI.RadDropDownList(document.getElementById("myDropDown"), {
    onopen: function(e) {//...}
});
Note

If you attach the event handler as shown above 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 the addEventListener Method Copy imageCopy
dropdown.addEventListener("open", changeHandlerFnName);

Getting and Setting a Selected Item

RadDropDownList allows the user to choose an item from a dropdown list of predefined items.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. If there is no matching item value, the first item from the list is selected.

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

var dropDownVal = dropdown.value;
dropdown.value = dropDownVal;

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, no item will be selected.

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

To get or set the selected item's index you can use the index property. 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
dropdown.index = 0;
var selectedItemIndex = dropdown.index;

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

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

See Also