Ajax Control Toolkit ComboBox

Modified on 2010/04/16 00:04 by Stephen Walther — Categorized as: Uncategorized

ComboBox is an ASP.NET AJAX control that, like the AutoCompleteExtender, combines the flexibility of a TextBox with a list of options that users are able to choose from. It borrows many of its properties, behaviors, and naming conventions from the Windows Forms ComboBox control, and is derived from the same base class as the ListBox, BulletedList, and DropDownList web controls. In fact, a ComboBox is best described as a DropDownList that can be typed directly into like a TextBox.

Working with a ComboBox in code is also a lot like working with a DropDownList. It has all of the same properties and events as a DropDownList, with a few additional ComboBox-specific properties and events. Firstly, it can be configured to either prevent or allow user-typed text that does not match an item in the list. When user-typed text does match an item in the list, the ComboBox can also be configured to auto-complete the text based on the first matched item in the list, to show the list and highlight the first matched item, or to do both simultaneously. When user-typed text does not match an item in the list, the ComboBox raises ItemInserting and ItemInserted events which can be handled during postback. Other than these special behaviors, the ComboBox behaves essentially like a DropDownList.

The ComboBox is intended as a supplement to, rather than a replacement for, the AutoCompleteExtender. Though there are many scenarios where either could be used to satisfy the same user interface requirements, there are scenarios where one control could offer particular advantages or disadvantages compared to the other:

Data Binding - The ComboBox can bind to data source controls like SqlDataSource and ObjectDataSource, and to runtime objects that implement IListSource, IEnumerable, or IDataSource. Like the DropDownList, the ComboBox also has an Items collection that can be manipulated declaratively and/or programmatically. The AutoCompleteExtender can only get its item list from a web service or page method. When it is possible and more convenient to bind to a data source control, runtime object, or declared item list, the ComboBox may be a better choice than the AutoCompleteExtender.
Restricting User-Typed Text - Another feature of the ComboBox is that it can restrict input so that an item in the list is always selected after a postback (as long as the Items collection is not empty). The AutoCompleteExtender allows users to type anything into the TextBox being extended, even if the typed text doesn't match any options returned by the extender's ServiceMethod. A ComboBox may be a better fit for user interfaces which require a predetermined item be selected from the list (like a foreign key input).
Composite Items - Items in a ComboBox, like items in a DropDownList, have both Text and Value properties. The only user input value offered by the AutoCompleteExtender is the Text property of the TextBox being extended. If the items in your list can be modeled with different Text and Value properties, the ComboBox may provide a better match for the data items being listed (again, foreign keys can be a good example of this).
Long Item Lists / Multiple Input Controls - All of the items in a ComboBox's list will be rendered to the web page it exists in. The AutoCompleteExtender, on the other hand, retrieves items from its ServiceMethod after the page is rendered. When your ComboBox contains a rather long list of items, or when you have a relatively large number of ComboBoxes on the same page (or within the same UpdatePanel), load times could be slowed down significantly. When ComboBoxes perform slowly because of the amount of markup they must render to the browser, an AutoCompleteExtender can be used instead to increase performance.
Partial Auto-Completion - The auto-complete feature of the ComboBox will only match items that start with the first user-typed character. An AutoCompleteExtender's ServiceMethod, on the other hand, can be configured to match items where the user-typed text lies somewhere after the first character in the item. A ComboBox cannot be used in application scenarios that require items to be "partially matched" like this.
Multiple Item Selection - The ComboBox, like the DropDownList, will only allow one item to be selected at a time. The AutoCompleteExtender can be configured to allow users to select multiple items simultaneously (using the AutoCompleteExtender's DelimiterCharacters property), like a ListBox or CheckBoxList. When users must have the ability to submit multiple items in a single postback, the AutoCompleteExtender should be used instead of the ComboBox.

ComboBox Server Properties

The properties in italics are optional.

<ajaxToolkit:ComboBox ID="ComboBox1" runat="server" 
    DropDownStyle="DropDown" 
    AutoCompleteMode="None"
    CaseSensitive="false"
    RenderMode="Inline"
    ItemInsertLocation="Append"
    ListItemHoverCssClass="ComboBoxListItemHover"
      <asp:ListItem>...</asp:ListIem>
      ...
</ajaxToolkit:ComboBox>

DropDownStyle - Determines whether the user is allowed to enter text that does not match an item in the list, and whether the list is always displayed. If "DropDownList" is specified, users are not allowed to enter text that does not match an item in the list. When "DropDown" (the default value) is specified, any text is allowed. If "Simple" is specified, any text is allowed and the list is always displayed regardless of the AutoCompleteMode property value.
AutoCompleteMode - Determines how the ComboBox automatically completes the text that is typed into it. When "Suggest" is specified, the ComboBox will show the list, highlight the first matched item, and if necessary, scroll the list to show the highlighted item. If "Append" is specified, the ComboBox will append the remainder of the first matched item to the user-typed text and highlight the appended text. When "SuggestAppend" is specified, both of the above behaviors are applied. If "None" (the default value) is specified, the ComboBox's auto-complete behaviors are disabled.
CaseSensitive - Specifies whether user-typed text is matched to items in the list in a case-sensitive manner. The default is "false".
RenderMode - Specifies whether the ComboBox is rendered as an "Inline" or "Block" level HTML element. The default is "Inline".
ItemInsertLocation - Determines whether to "Append" or "Prepend" new items when they are inserted into the list, or whether to insert them in an "Ordinal" manner (alphabetically) based on the item Text or Value. The default is "Append".
ListItemHoverCssClass - When specified, replaces the default styles applied to highlighted items in the list with a custom css class.
ListItem - One or more child controls used to declare items that will be added to the ComboBox list. When bound to a data source, all declared ListItems will be removed unless the AppendDataBoundItems property is set to "true".

ComboBox Known Issues

When ListItemHoverCssClass is specified and the ComboBox list is scrollable, highlighting a list item will cause the scrollbar to flicker when using the Internet Explorer web browser. To avoid this issue, do not specify the ListItemHoverCssClass property.

ComboBox Theming

You can change the look and feel of the ComboBox using the ComboBox CssClass property. The ComboBox has a predefined set of CSS classes that can be overridden. It has a default style which is embedded as a WebResource and is a part of the Toolkit assembly that has styles set for all the sub-classes. You can find the default styles in the Toolkit solution in the "AjaxControlToolkit\ComboBox\ComboBox.css" file. If your CssClass does not provide values for any of those then it falls back to the default value. In the example above the default style is displayed when

"[Empty String]"

is selected as the CssClass. To customize the same the user would have to set the CssClass property to the name of the CSS style and define the styles for the individual classes so that the various elements in a ComboBox control can be styled accordingly. For example, if the CssClass property was set to "CustomComboBoxStyle", this is how the css to style the border and background color would look:

.CustomComboBoxStyle .ajax__combobox_textboxcontainer input {
    background-color: #ADD8E6;
    border: solid 1px Blue;
    border-right: 0px none;
}
.CustomComboBoxStyle .ajax__combobox_buttoncontainer button {
    background-color: #ADD8E6;
    border: solid 1px Blue;
}

ComboBox CSS classes

.ajax__combobox_inputcontainer: A table element that contains and positions the ComboBox's button and text box input elements. 
Child Css classes: ajax__combobox_textboxcontainer, ajax__combobox_buttoncontainer.

.ajax__combobox_textboxcontainer: The table cell that contains the ComboBox's text box input element.
.ajax__combobox_buttoncontainer: The table cell that contains the ComboBox's button element.
.ajax__combobox_itemlist: The ul element that contains the ComboBox's list item (li) elements.