Telerik UI for Windows 8 HTML
Contents

The RadAutoCompleteBox control for Windows 8 is an HTML/JavaScript component that allows the user to select items from predefined or live (service/ajax 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 an HTML Page

Creating a RadAutoCompleteBox

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

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

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

HTML Copy imageCopy
<span id="myAutoCompleteBox">
</span>
JavaScript Copy imageCopy
var autocomplete = new Telerik.UI.RadAutoCompleteBox(document.getElementById("myAutoCompleteBox"));

Creating a RadAutoCompleteBox like that without setting any properties will not result in a very useful control. You need to define at least a set of items the RadAutoCompleteBox can search from. In the next section you can see a basic usage of the control.

Setting RadAutoCompleteBox Options

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

Markup Definition Copy imageCopy
<span data-win-control="Telerik.UI.RadAutoCompleteBox" data-win-options="{
        placeholder: 'enter country...',
        dataSource: [ 'Germany', 'England', 'France', 'Greece'],
        filter: 'startswith'
    }"></span>

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

JavaScript Definition Copy imageCopy
<span id="autoComplete"></span>
JavaScript Definition Copy imageCopy
var autoComplete = new Telerik.UI.RadAutoCompleteBox(document.getElementById("autoComplete"), {
    placeholder: 'enter country...',
    dataSource: ['Germany', 'England', 'France', 'Greece'],
    filter: 'startswith'
});

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

autocomplete-gettingstarted

Accessing and Modifying RadAutoCompleteBox

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

JavaScript Copy imageCopy
var autocomplete = document.getElementById("myAutoCompleteBox").winControl;

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

JavaScript Copy imageCopy
autocomplete.separator = ",";

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 Event Handler Function During Initialization Copy imageCopy
var autocomplete = new Telerik.UI.RadAutoCompleteBox(document.getElementById("myAutoCompleteBox"), { 
    onchange: changeHandlerFnName });
// OR
var autocomplete = new Telerik.UI.RadAutoCompleteBox(document.getElementById("myAutoCompleteBox"), {
    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 addEventListener Method Copy imageCopy
autocomplete.addEventListener("change", changeHandlerFnName);

Getting and Setting a Value

RadAutoCompleteBox allows the user to input any text. Because of the nature of the control, the value and the text properties are identical in their functionality. You can use both to get or set the input text:

Getting and Setting a Value Example Copy imageCopy
var autoComplete = document.getElementById("autoComplete").winControl;

var autoCompleteVal = autoComplete.value;
autoComplete.value = autoCompleteVal;

var autoCompleteText = autoComplete.text;
autoComplete.text = autoCompleteText;

To populate the RadAutoCompleteBox with one of the predefined data items you can 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 = autoComplete.list;
var toSelect = $("li:contains('Andrew Fuller')",items);
autoComplete.select(toSelect);

See Also