Default Tag Box
The Tag Box control provides an interface for selecting multiple unique values (tags) from a predefined list with the autocomplete functionality. End-users can select a value from a drop-down list or by typing in the tag box. The Tags property provides access to a collection of strings corresponding to selected values. Note that tags must be unique. A tag can be removed from the selection using either its remove button or the backspace key.
<dx:BootstrapTagBox ID="TagBoxDefault" runat="server" OnLoad="TagBoxDefault_Load">
<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:BootstrapTagBox>
protected void TagBoxDefault_Load(object sender, EventArgs e) {
if(!IsPostBack) {
BootstrapTagBox tagBox = (BootstrapTagBox)sender;
tagBox.Tags.Add(tagBox.Items[0].Text);
tagBox.Tags.Add(tagBox.Items[1].Text);
}
}
An end-user can specify a custom tag, which is not specified in the Items collection, by typing it into the Tag Box. This behavior can be changed via the AllowCustomTags property: when its value is set to false, it is only possible to change the editor's value by selecting a tag from the drop-down list.
The server-side CustomTagsAdded event provides a notification that an end-user specified a custom tag. You can access a collection of specified custom tags through the event's CustomTags argument, so you can programmatically add such tags to the Items collection in the event handler.
Use the client IsCustomTag method to find out whether the specified tag is a custom tag.
<dx:BootstrapTagBox runat="server" AllowCustomTags="true" Tags="Item6, Item7">
<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:BootstrapTagBox>
Data Binding
Binding the editor to a data source enables the Tag Box control to dynamically generate its content. Set the DataSourceID property to assign a data source to a Tag Box control.
A data-bound Tag Box control automatically creates a list item for each data item. On retrieving items from the data source, list item characteristics such as text, value, and icon are obtained from specific data fields with matching names. You can also explicitly specify mappings between toolbar item properties and data item attribute names using the following properties:
- ValueField - Specifies the name of a data field providing values to the editor's items.
- TextField - Specifies the name of a data field providing tag texts.
- IconCssClassField - Specifies the name of a data field providing CSS classes of icons displayed within tag elements.
<dx:BootstrapTagBox runat="server" DataSourceID="UsersDataSource"
TextField="Email" ValueField="ID" OnDataBound="TagBox_DataBound">
</dx:BootstrapTagBox>
<ef:EntityDataSource runat="server" ID="UsersDataSource" ContextTypeName="DevExpress.Web.Demos.Bootstrap.IssueListContextSL" EntitySetName="Users">
</ef:EntityDataSource>
protected void TagBox_DataBound(object sender, EventArgs e) {
BootstrapTagBox tagBox = (BootstrapTagBox)sender;
tagBox.Tags.Add(tagBox.Items[0].Text);
tagBox.Tags.Add(tagBox.Items[1].Text);
}
Incremental Filtering
The Tag 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 auto-completed with the first corresponding value.
- None - Filtering is not applied to list items.
The IncrementalFilteringDelay property allows you to specify the time interval between the moment an end-user starts typing within the editor box, and filtering is applied.
Use the FilterMinLength to specify the minimum length of the filter string input required to initiate a filtering operation.
To try incremental filtering in action, set the focus to the Tag Box control and start typing.
<dx:BootstrapTagBox runat="server" DataSourceID="UsersDataSource"
TextField="Email" ValueField="ID" IncrementalFilteringMode="StartsWith">
</dx:BootstrapTagBox>
Load Items on Callbacks
In this example, the Tag 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 Tag Box operates in callback mode.
- CallBackPageSize - defines the number of items to be obtained from the server each time it is required.
Note that in this demo the callback time is extended intentionally so that the loading indicator is visible during callbacks.
<dx:BootstrapTagBox ID="TagBoxCallbacks" runat="server" CallbackPageSize="10" EnableCallbackMode="true"
DataSourceID="UsersDataSource" TextField="Email" ValueField="ID" OnDataBound="TagBoxCallbacks_DataBound">
</dx:BootstrapTagBox>
protected void TagBoxCallbacks_DataBound(object sender, EventArgs e) {
BootstrapTagBox tagBox = (BootstrapTagBox)sender;
tagBox.Tags.Add(tagBox.Items[0].Text);
}
Null Text
This example illustrates how the NullText property can be used to display the 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.
The NullTextDisplayMode property allows you to specify whether the prompt text should always be displayed, or only when the editor is unfocused.
<dx:BootstrapTagBox runat="server" NullText="Send To..."
DataSourceID="UsersDataSource" TextField="Email" ValueField="ID">
</dx:BootstrapTagBox>
Caption and HelpText
In this example, the Tag Box control displays a caption at the top and auxiliary help text at the bottom of the editor.
- Caption - Specifies the caption text.
- HelpText - Specifies the help text.
- CaptionSettings - Provides access to settings related to the editor caption.
- HelpTextSettings - Provides access to settings related to the editor help text.
<dx:BootstrapTagBox runat="server" Caption="Send To" HelpText="Select the email addresses of recipients"
DataSourceID="UsersDataSource" TextField="Email" ValueField="ID">
</dx:BootstrapTagBox>
Validation
The Tag Box editor provides a universal mechanism for performing data validation on both the client and server. You can access the validation settings through the ValidationSettings property.
Use the following API to define the validation logic:
You can force editor validation using the following approaches:
<dx:BootstrapTagBox runat="server" ClientInstanceName="tgbValidation" Caption="Send To"
DataSourceID="UsersDataSource" TextField="Email" ValueField="ID">
<ValidationSettings ValidateOnLeave="false">
<RequiredField IsRequired="true" ErrorText="At least one recipient is required" />
</ValidationSettings>
</dx:BootstrapTagBox>
<dx:BootstrapButton runat="server" Text="Validate" AutoPostBack="false" UseSubmitBehavior="false">
<ClientSideEvents Click="onValidateClick" />
<SettingsBootstrap RenderOption="Primary" />
</dx:BootstrapButton>
function onValidateClick(s, e) {
tgbValidation.Validate();
}