Default Combo Box
This example demonstrates the Combo Box control with default settings. The Combo Box control is a drop-down list editor allowing your end-users to select from a list of values. The items can be loaded from the DataSource or populated using the Items collection. The control provides enchanced server-side and client-side API for different scenarios.
<dx:BootstrapComboBox runat="server" SelectedIndex="0">
<Items>
<dx:BootstrapListEditItem Text="Item1" Value="Item1" />
<dx:BootstrapListEditItem Text="Item2" Value="Item2" />
<dx:BootstrapListEditItem Text="Item3" Value="Item3" />
<dx:BootstrapListEditItem Text="Item4" Value="Item4" />
<dx:BootstrapListEditItem Text="Item5" Value="Item5" />
</Items>
</dx:BootstrapComboBox>
DropDown Style
The DropDownStyle property specifies the manner in which and end-user can change an editor value. When this property is set to DropDownList, it is only possible to change the editor's value by selecting an item from the drop-down list.
In this demo, the DropDownStyle property is set to DropDown, so you can change the editor's value by either selecting an item from the drop-down list or entering new values into the edit box without invoking the drop-down list.
<dx:BootstrapComboBox runat="server" SelectedIndex="0" DropDownStyle="DropDown">
<Items>
<dx:BootstrapListEditItem Text="Item1" Value="Item1" />
<dx:BootstrapListEditItem Text="Item2" Value="Item2" />
<dx:BootstrapListEditItem Text="Item3" Value="Item3" />
<dx:BootstrapListEditItem Text="Item4" Value="Item4" />
<dx:BootstrapListEditItem Text="Item5" Value="Item5" />
</Items>
</dx:BootstrapComboBox>
Data Binding
The Combo Box control's content can be dynamically generated by binding the editor to a data source. On retrieving items from the data source, item characteristics such as text and value are obtained from specific data fields. These data fields either can be defined manually using the TextField and ValueField properties or the Combo Box control can obtain them automatically provided that data fields in the data source are named the same as corresponding characteristics ("Text", "Value").
<dx:BootstrapComboBox runat="server" DataSourceID="CountriesDataSource"
TextField="CountryName" ValueField="CountryName" SelectedIndex="0">
</dx:BootstrapComboBox>
<ef:EntityDataSource ID="CountriesDataSource" runat="server" ContextTypeName="DevExpress.Web.Demos.WorldCitiesContextSL"
EntitySetName="Countries" OrderBy="it.CountryName">
</ef:EntityDataSource>
Incremental Filtering
The Combo Box control allows you to dynamically filter list items based on the text typed into the editor's input box on the client side ("find-as-you-type" filtering). The following modes are available.
- Contains - The editor is filtered for list items that contain the search string. Search string matches are highlighted.
- StartsWith - The editor is filtered for list items that begin with the search string. The editor value is autocompleted with the first corresponding value.
- None - Filtering is not applied to list items.
To try this feature in action, set the focus to the Combo Box control and start typing.
<dx:BootstrapComboBox runat="server" DataSourceID="CountriesDataSource"
TextField="CountryName" ValueField="CountryName" IncrementalFilteringMode="StartsWith">
</dx:BootstrapComboBox>
Custom Filtering
The Combo Box control allows you to provide custom filtering logic using the server-side and client-side API. The CustomFiltering server-side event provides the capability to set the filtering expression and customize highlighting applied to search results. The event argument object exposes the following properties:
- e.Filter - Provides access to the search text entered by an end-user.
- e.FilterExpression - Specifies the filter expression.
- e.CustomHighlighting - Specifies rules, according to which the editor highlights the filtered items (by default, the first occurrence of the searched text is highlighter in the item's display text).
On the client-side, custom filtering logic can be implemented using the following client events:
- ItemFiltering - Fires for each item as an end-user types the search text if callback mode is disabled and provides a capability to change the visibility of an item in the search result.
- CustomHighlighting - Fires once for every item and provides a capability to specify the custom highlighting logic.
This demo demonstrates how to use the server-side CustomFiltering event to search for several words through multiple data fields. When you type a search phrase, a custom algorithm dynamically splits it into individual words, searches for each of these words in both data fields and, if found, highlights them.
<dx:BootstrapComboBox ID="ComboBoxCustomFiltering" runat="server" OnCustomFiltering="ComboBoxCustomFiltering_CustomFiltering"
DataSourceID="CustomersDataSource" ValueField="CustomerID" ValueType="System.String" EnableCallbackMode="true">
<Fields>
<dx:BootstrapListBoxField FieldName="CompanyName" />
<dx:BootstrapListBoxField FieldName="Country" />
</Fields>
</dx:BootstrapComboBox>
<ef:EntityDataSource runat="server" ID="CustomersDataSource" ContextTypeName="DevExpress.Web.Demos.NorthwindContextSL" EntitySetName="Customers">
</ef:EntityDataSource>
protected void ComboBoxCustomFiltering_CustomFiltering(object sender, ListEditCustomFilteringEventArgs e) {
string[] words = e.Filter.Split(new char[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);
string[] dataFields = new string[] { "CompanyName", "Country" };
e.FilterExpression = DevExpress.Data.Filtering.GroupOperator.And(words.Select(w =>
DevExpress.Data.Filtering.GroupOperator.Or(
dataFields.Select(f =>
new DevExpress.Data.Filtering.FunctionOperator(DevExpress.Data.Filtering.FunctionOperatorType.Contains, new DevExpress.Data.Filtering.OperandProperty(f), w)
)
)
)).ToString();
e.CustomHighlighting = dataFields.ToDictionary(f => f, f => words);
}
Load Items on Callbacks
In this example, the Combo Box operates in callback mode. In this mode, list items that are not currently displayed within the editor's drop-down window are dynamically loaded when you scroll the list. The callback mode makes the first page load much faster, since only a few items need to be loaded initially.
- EnableCallbackMode - specifies whether or not the Combo Box operates in callback mode
- CallBackPageSize - defines the number of items to be obtained from the server each time it's required
<dx:BootstrapComboBox runat="server" DataSourceID="CountriesDataSource"
TextField="CountryName" ValueField="CountryName" SelectedIndex="0" CallbackPageSize="25" EnableCallbackMode="true">
</dx:BootstrapComboBox>
Null Text
This example illustrates how the NullText property can be used to display prompt text (watermark) in the editor's edit box. Specified text is displayed when the value of the editor is null and the editor is not focused. The prompt text disappears when the editor receives focus. To show the null text even in the focused editor set the NullTextDisplayMode property to UnfocusedAndFocused.
<dx:BootstrapComboBox runat="server" DataSourceID="CountriesDataSource" NullText="Select Your Country"
TextField="CountryName" ValueField="CountryName">
<ClearButton DisplayMode="Always" />
</dx:BootstrapComboBox>
The DisplayFormatString property specifies the pattern used to format the value of an editor for display purposes, when the editor is not focused. Display values can be formatted using the standard formatting mechanism described in MSDN. For more information about composing format patterns, see the following MSDN topics: Numeric Format Strings and Date and Time Format Strings.
<dx:BootstrapComboBox runat="server" SelectedIndex="0" DisplayFormatString="DXperience Enterprise v{0}">
<Items>
<dx:BootstrapListEditItem Text="2017.1" Value="2017.1" />
<dx:BootstrapListEditItem Text="2016.2" Value="2016.2" />
<dx:BootstrapListEditItem Text="2016.1" Value="2016.1" />
</Items>
</dx:BootstrapComboBox>
Caption and HelpText
In this example, the Combo Box control displays a caption on the top and auxiliary help text at the bottom of the editor.
<dx:BootstrapComboBox runat="server" Caption="Country" HelpText="Select your country"
DataSourceID="CountriesDataSource" TextField="CountryName" ValueField="CountryName">
<ValidationSettings RequiredField-IsRequired="true"></ValidationSettings>
</dx:BootstrapComboBox>
Templates
The Combo Box control allows you to customize layouts of its visual elements using the template technology. In this demo, the Button Template is used to customize the Combo Box control's drop-down button. For the custom button to expand the dropdown list on click, the corresponding action is declaratively assigned to the button using the data-toggle attribute.
Note that the TextFormatString property is specified to provide a custom format for the value displayed by the ComboBox's input. Placeholder indexes in the format string correspond to indexes of the Fields collection's items.
<dx:BootstrapComboBox runat="server" DataSourceID="EmployeesDataSource" ValueField="EmployeeID" TextFormatString="{0} {1}" DropDownRows="5">
<Fields>
<dx:BootstrapListBoxField FieldName="FirstName" />
<dx:BootstrapListBoxField FieldName="LastName" />
</Fields>
<ButtonTemplate>
<span class="dxbs-edit-btn btn btn-secondary dropdown-toggle" data-toggle="dropdown-show">Show More</span>
</ButtonTemplate>
<ItemTemplate>
<div class="media mb-3">
<dx:BootstrapBinaryImage runat="server" AlternateText="" Value='<%# Eval("Photo") %>' Width="64" Height="68">
<CssClasses Control="mr-3" />
</dx:BootstrapBinaryImage>
<div class="media-body media-middle">
<h5 class="mt-0"><%# Eval("FirstName") %> <%# Eval("LastName") %></h5>
<%# Eval("Title") %>
</div>
</div>
</ItemTemplate>
</dx:BootstrapComboBox>
Adaptivity
The Combo Box's drop-down list can be wider than the browser window, for example on a device with a smaller screen. In this case, set the SettingsAdaptivity.Mode property to "OnWindowInnerWidth" to display the drop-down list as a modal window.
The following API members specify the combo box's adaptive settings:
<div class="container mt-2">
<dx:BootstrapComboBox runat="server"
Caption="Ticket Type" HelpText="All special offers are available on the website">
<SettingsAdaptivity Mode="OnWindowInnerWidth" ModalDropDownCaption="Choose ticket type" />
<Items>
<dx:BootstrapListEditItem Text="Standard" Value="Standard" Selected="true" />
<dx:BootstrapListEditItem Text="Business" Value="Business" />
<dx:BootstrapListEditItem Text="Economy" Value="Economy" />
<dx:BootstrapListEditItem Text="Special Offer" Value="SO" />
</Items>
</dx:BootstrapComboBox>
</div>
Multi Column
The Combo Box can display data across multiple columns. To enable multi-column mode, add data source fields to the BootstrapComboBox.Fields collection and set the BootstrapComboBox.EnableMultiColumn property to true. Each added field is rendered as a Combo Box column. To customize a column's caption, width, and tooltip, use the field's SettingsMultiColumn property.
<dx:BootstrapComboBox runat="server" DataSourceID="WWICountriesDataSource" EnableMultiColumn="true" ValueField="CountryID">
<Fields>
<dx:BootstrapListBoxField FieldName="IsoAlpha3Code">
<SettingsMultiColumn Caption="Code" ToolTip="IsoAlpha3Code" Width="50px" />
</dx:BootstrapListBoxField>
<dx:BootstrapListBoxField FieldName="CountryName" />
<dx:BootstrapListBoxField FieldName="Region" />
<dx:BootstrapListBoxField FieldName="Subregion" />
</Fields>
</dx:BootstrapComboBox>