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
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 |
---|
<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 |
---|
<span id="myDropDownList">
</span> |
JavaScript | Copy |
---|
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 |
---|
<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 |
---|
<span id="codeDropDown"></span> |
Initializing RadDropDownList in the Code-Behind | Copy |
---|
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.
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 |
---|
var dropdown = document.getElementById("myDropDown").winControl; |
Once you have a reference to the control, you can modify its properties as required:
JavaScript | Copy |
---|
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 |
---|
var dropdown = new Telerik.UI.RadDropDownList(document.getElementById("myDropDown"), {
onopen: changeHandlerFnName });
var dropdown = new Telerik.UI.RadDropDownList(document.getElementById("myDropDown"), {
onopen: function(e) {
}); |
Using the addEventListener Method | Copy |
---|
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 |
---|
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 |
---|
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 |
---|
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 |
---|
var items = dropdown.list;
var toSelect = $("li:contains('Andrew Fuller')",items);
dropdown.select(toSelect); |
See Also