RadSearchBox
Telerik RadSearchBox for ASP.NET AJAX provides the user the ability to write text in an input field with an optional autocomplete functionality.
Definition
Namespace:Telerik.Web.UI
Assembly:Telerik.Web.UI.dll
Syntax:
[EmbeddedSkin("SearchBox", typeof(RadSearchBox))]
[EmbeddedSkin("SearchBox", "Default", typeof(RadSearchBox))]
[RequiredCss("Telerik.Web.UI.Skins.Common.fonticons.css", RenderMode.Lightweight, typeof(RadSearchBox))]
[RequiredCss("Telerik.Web.UI.Skins.Common.MaterialRipple.css", RenderMode.Lightweight, typeof(RadButton))]
[RequiredScript(typeof(jQueryPlugins), 1)]
[RequiredScript(typeof(DropDown), 2)]
[RequiredScript(typeof(ChangeLog), 3)]
[RequiredScript(typeof(MaterialRipple))]
[ClientScriptResource("Telerik.Web.UI.RadSearchBox", "Telerik.Web.UI.SearchBox.RadSearchBoxScripts.js")]
[TelerikToolboxCategory("Data Editing")]
[ToolboxBitmap(typeof(RadSearchBox), "Toolbox.Icons.SearchBox.png")]
public class RadSearchBox : RadDataBoundControl, IComponent, IDisposable, IParserAccessor, IUrlResolutionService, IDataBindingsAccessor, IControlBuilderAccessor, IControlDesignerAccessor, IExpressionsAccessor, IAttributeAccessor, IScriptControl, IControlResolver, IPostBackDataHandler, ISkinnableControl, IControl, IFeatureGroup, IPostBackEventHandler, ICallbackEventHandler, IFlatBoundContainer, INamingContainerInheritance: objectControlWebControlBaseDataBoundControlDataBoundControlRadDataBoundControlRadSearchBox...
Implements:
Inherited Members
Constructors
public RadSearchBox()Properties
Gets the RadSearchBox SearchBoxButtons collection.
[PersistenceMode(PersistenceMode.InnerProperty)]
public SearchBoxButtonCollection Buttons { get; }protected SearchBoxButtonCollection Children { get; }Gets the settings for the animation played when the dropdown closes.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings CollapseAnimation { get; }An AnimationSettings that represents the collapse animation.
Use the CollapseAnimation property to customize the expand animation of RadSearchBox. You can specify the Type and Duration. To disable collapse animation effects you should set the Type to AnimationType.None.
To customize the expand animation you can use the ExpandAnimation property.
The client-side id of the inner input element used for intergation with RadLabel
public string ControlId { get; }The CssClass property will now be used instead of the former Skin and will be modified in AddAttributesToRender()
protected override string CssClassFormatString { get; }Overrides:
Gets or sets the selected culture. Localization strings will be loaded based on this value.
public CultureInfo Culture { get; set; }The culture.
Gets or sets the DataContextKeyField. This property will define the data column used as a context field.
public virtual string DataContextKeyField { get; set; }The DataContextKeyField.
Gets or sets an array of data-field names that will be used to populate the DropDownItem's DataItem property.
[SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]
[TypeConverter(typeof(ListConverter))]
[PersistenceMode(PersistenceMode.Attribute)]
public virtual string[] DataKeyNames { get; set; }An array that contains the names of the fields contained in the DropDownItem's DataItem property.
Note: Values set to this property are case-sensitive! The field names should be coma-separated.
Gets or sets the DataTextField.
public virtual string DataTextField { get; set; }The DataTextField.
Implements:
Gets or sets a value indicating how the DropDownItems text should be formatted.
public virtual string DataTextFormatString { get; set; }Gets or sets the DataValueField.
public virtual string DataValueField { get; set; }The DataValueField.
Implements:
Used to customize the appearance and position of the buttons displayed by RadListBox.
[PersistenceMode(PersistenceMode.InnerProperty)]
public DropDownSettings DropDownSettings { get; }Gets or sets a message when the input of the RadSearchBox is empty.
[ClientControlProperty]
[ClientPropertyName("_emptyMessage")]
[Bindable(false)]
public virtual string EmptyMessage { get; set; }The message which will be shown when the input of the RadSearchBox is empty.
Gets or sets a value indicating whether WAI-ARIA support is enabled.
[ClientControlProperty]
[ClientPropertyName("_enableAriaSupport")]
public bool EnableAriaSupport { get; set; }true if WAI-ARIA support is enabled; otherwise, false. The default is false.
When enabled, the SearchBox control will render appropriate ARIA attributes to improve accessibility for screen readers such as JAWS. This includes:
- ARIA roles for the input and dropdown list
- ARIA states for expanded/collapsed dropdown
- ARIA live regions for announcing search results
- ARIA attributes for keyboard navigation support
Gets or sets a value indicating whether the AutoComplete functionality of the RadSearchBox is enabled.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_enableAutoComplete")]
public virtual bool EnableAutoComplete { get; set; }Determines whether the Direction Detection is enabled or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_enableDirectionDetection")]
public bool EnableDirectionDetection { get; set; }Determines whether the Screen Boundaries Detection is enabled or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_enableScreenBoundaryDetection")]
public bool EnableScreenBoundaryDetection { get; set; }Gets the settings for the animation played when the dropdown opens.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings ExpandAnimation { get; }An AnimationSettings that represents the expand animation.
Use the ExpandAnimation property to customize the expand animation of RadSearchBox. You can specify the Type and Duration. To disable expand animation effects you should set the Type to AnimationType.None.
To customize the collapse animation you can use the CollapseAnimation property.
Gets or sets a value indicating whether the RadSearchBox should apply “Contains” or “StartsWith” filter logic.
[Bindable(false)]
[ClientControlProperty]
public SearchBoxFilter Filter { get; set; }Gets or sets the height of the Web server control.
public override Unit Height { get; }A Unit that represents the height of the control. The default is Empty.
Exceptions: ArgumentExceptionThe height was set to a negative value.
Overrides:
Gets or sets a value indicating whether the first matching result will be highlighted upon drop down opening.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_highlightFirstMatch")]
public virtual bool HighlightFirstMatch { get; set; }protected SearchContext InnerContext { get; }Gets or sets a value that indicates whether the filter logic is case-sensitive or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("isCaseSensitive")]
public bool IsCaseSensitive { get; set; }Gets or sets the label of the control.
public string Label { get; set; }The label of the control.
Gets or sets the css class of the label.
public string LabelCssClass { get; set; }The label CSS class.
Gets or sets the width of the control's label
public Unit LabelWidth { get; set; }Gets the localization.
[PersistenceMode(PersistenceMode.InnerProperty)]
[TypeConverter(typeof(ExpandableObjectConverter))]
public SearchBoxLocalization Localization { get; }The localization.
Gets or sets a value indicating where RadSearchBox will look for its .resx localization files.
public string LocalizationPath { get; set; }The localization path.
Gets or sets how many results are shown in the dropdown.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("maxResultCount")]
public virtual int MaxResultCount { get; set; }Defines the minimum number of characters that must be typed before a search is made.
[ClientControlProperty]
public virtual int MinFilterLength { get; set; }The minimum number of characters that must be typed before a search is made.
Gets or sets a value indicating the client-side event handler that is called when a button from the Buttons Collection is clicked.
[ClientControlEvent]
[ClientPropertyName("buttonCommand")]
public string OnClientButtonCommand { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientButtonCommand client-side event handler is called when a button from the Buttons Collection is clicked.
The event handler receives two parameters: the instance of the searchBox client-side object and event args.
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called before a search is triggered in RadSearchBox.
[ClientControlEvent]
[ClientPropertyName("dataRequesting")]
public string OnClientDataRequesting { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientDataRequesting client-side event handler is called before a search is triggered in RadSearchBox .
The event handler receives two parameters: the instance of the searchBox client-side object and event args.
This event can be cancelled.
Gets or sets a value indicating the client-side event handler that is called after the RadSearchBox client-side object is initialized.
[ClientControlEvent]
[ClientPropertyName("load")]
public string OnClientLoad { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClienLoad client-side event handler is called after the searchBox is fully initialized on the client.
A single parameter - the searchBox client object - is passed to the handler.
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when a search is triggered in the SearchBox. This happens when the default seach button or an item from the dropdown is clicked, or Enter key is pressed.
[ClientControlEvent]
[ClientPropertyName("search")]
public string OnClientSearch { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientSearch client-side event handler is called when a search is triggered in the SearchBox. This happens when the default seach button or an item from the dropdown is clicked, or Enter key is pressed.
The event handler receives two parameters: the instance of the searchBox client-side object and event args.
This event cannot be cancelled.
Gets the RadSearchBox SearchContext.
[PersistenceMode(PersistenceMode.InnerProperty)]
public SearchContext SearchContext { get; }protected DataSourceSelectArguments SelectArguments { get; }Gets or sets a value indicating whether a loading icon should be shown while a request it pending.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("showLoadingIcon")]
public bool ShowLoadingIcon { get; set; }Gets or sets a value indicating whether the default search button is rendered.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_showSearchButton")]
public virtual bool ShowSearchButton { get; set; }protected override bool SupportsRenderingMode { get; }Overrides:
protected override HtmlTextWriterTag TagKey { get; }Overrides:
Gets or sets the RadSearchBox's input value.
[Browsable(false)]
[Bindable(false)]
public virtual string Text { get; set; }The value shown in the input of the RadSearchBox.
Gets the unique, hierarchically qualified identifier for the server control.
[ClientControlProperty]
[ClientPropertyName("_uniqueId")]
public override string UniqueID { get; }The fully qualified identifier for the server control.
Overrides:
Gets the settings for the web service used to provide search results.
[PersistenceMode(PersistenceMode.InnerProperty)]
public WebServiceSettings WebServiceSettings { get; }An WebServiceSettings that represents the web service used to provide search results.
Use the WebServiceSettings property to configure the web service used to provide search results. You must specify both Path and Method to fully describe the service.
In order to use the integrated support, the web service should have the following signature:
<pre><code class="lang-csharp">[ScriptService]public class WebServiceName : WebService { [WebMethod] public SearchBoxItemData[] GetResult(SearchBoxContext context) {
} }
<System.Web.Script.Services.ScriptService()> _ Public Class WebService Inherits System.Web.Services.WebService<WebMethod> _ Public Function GetResult(context As SearchBoxContext) As SearchBoxItemData() End Function
End Class
Methods
protected override void AddAttributesToRender(HtmlTextWriter writer)Overrides:
protected override void CreateChildControls()Overrides:
This method should return object that implements ISearchBoxRenderer or Inherits the SearchBoxRenderer class.
protected override DataSourceSelectArguments CreateDataSourceSelectArguments()Overrides:
protected override void DescribeComponent(IScriptDescriptor descriptor)Overrides:
[SuppressMessage("Microsoft.Design", "CA1063:ImplementIDisposableCorrectly")]
public override void Dispose()Overrides:
public override void Focus()Overrides:
Executed when post data is loaded from the request
protected override bool LoadPostData(string postDataKey, NameValueCollection postCollection)Overrides:
Raises the ButtonCommand event.
protected void OnButtonCommand(SearchBoxButtonEventArgs e)The SearchBoxButtonEventArgs instance containing the event data.
Raises the DataSourceSelect event.
protected bool OnDataSourceSelect(SearchBoxDataSourceSelectEventArgs e)The SearchBoxDataSourceSelectEventArgs instance containing the event data.
Returns:Raises the Search event.
protected void OnSearch(SearchBoxEventArgs e)The SearchBoxEventArgs instance containing the event data.
protected override void RenderContents(HtmlTextWriter writer)Overrides:
protected override void TrackViewState()Overrides:
Events
Occurs when a button has been clicked.
public event SearchBoxButtonEventHandler ButtonCommandOccurs before a select command is sent to the datasource.
public event SearchBoxDataSourceSelectEventHandler DataSourceSelectOccurs when a search has been triggered.
public event SearchBoxEventHandler Search