class sap.ui.commons.SearchField

Visiblity: public
UX Guidelines:
Implements: sap.ui.commons.ToolbarItem
Available since: N/A
Module: sap/ui/commons/SearchField
Application Component: CA-UI5-CTR

Allows the user to type search queries and to trigger the search. Optionally, suggestions can be added.


Constructor

Constructor for a new SearchField.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.ui.commons.SearchField(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
editable boolean true

Non-editable controls have different colors, depending on custom settings

Visibility: public
enableCache boolean true

When list suggestion is enabled all suggestions are cached and no suggest event is fired.

Since: 1.10.3.

Visibility: public
enableClear boolean false

Defines whether the clear functionality shall be active

Visibility: public
enableFilterMode boolean false

Defines whether the search event should also be fired when the SearchField is empty (like a Filter field) and when the clear button (if activated) is pressed.

Visibility: public
enableListSuggest boolean true

Defines whether a pop up list shall be provided for suggestions

Visibility: public
enabled boolean true

Disabled fields have different colors, and they can not be focused.

Visibility: public
maxHistoryItems int 0

Maximum number of history items in the suggestion list. 0 displays and stores no history. The history is locally stored on the client. Therefore do not activate this feature when this control handles confidential data.

Visibility: public
maxLength int 0

Maximum number of characters. Value '0' means the feature is switched off.

Visibility: public
maxSuggestionItems int 10

Maximum number of suggestion items in the suggestion list.

Visibility: public
placeholder string empty string

Placeholder for the input field.

Since: 1.32.

Visibility: public
showExternalButton boolean false

Defines whether an additional search button shall be displayed

Visibility: public
showListExpander boolean true

Defines whether the list expander shall be displayed in the case of an enabled list for suggestions. This feature is deactivated on mobile devices.

Visibility: public
startSuggestion int 3

Minimum length of the entered string triggering the suggestion list.

Visibility: public
textAlign sap.ui.core.TextAlign Begin

Sets the horizontal alignment of the text

Visibility: public
value string empty string

Text that shall be displayed within the search field

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes warnings or errors related to the input field. Possible values: Warning, Error, Success, None.

Since: 1.32.

Visibility: public
visibleItemCount int 20

Defines the number of items in the suggestion list that shall be displayed at once. If the overall number of list items is higher than the setting, a scroll bar is provided.

Visibility: public
width sap.ui.core.CSSSize

Control width in CSS-size

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
searchProvider 0..1 sap.ui.core.search.SearchProvider

Search provider instance which handles the suggestions for this SearchField (e.g. Open Search Protocol).


Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / IDs which describe this control (see WAI-ARIA attribute aria-describedby).

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs which label this control (see WAI-ARIA attribute aria-labelledby).


Events Overview

Event Description
search

Event which is fired when the user triggers a search

suggest

Event which is fired when new suggest values are required.

search

Event which is fired when the user triggers a search

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
query string

The search query

suggest

Event which is fired when new suggest values are required.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The value for which suggestions are required.


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachSearch

Attaches event handler fnFunction to the search event of this sap.ui.commons.SearchField.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.commons.SearchField itself.

Event which is fired when the user triggers a search

attachSuggest

Attaches event handler fnFunction to the suggest event of this sap.ui.commons.SearchField.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.commons.SearchField itself.

Event which is fired when new suggest values are required.

clearHistory

Clears the history of the control

destroySearchProvider

Destroys the searchProvider in the aggregation searchProvider.

detachSearch

Detaches event handler fnFunction from the search event of this sap.ui.commons.SearchField.

The passed function and listener object must match the ones used for event registration.

detachSuggest

Detaches event handler fnFunction from the suggest event of this sap.ui.commons.SearchField.

The passed function and listener object must match the ones used for event registration.

sap.ui.commons.SearchField.extend

Creates a new subclass of class sap.ui.commons.SearchField with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireSearch

Fires event search to attached listeners.

fireSuggest

Fires event suggest to attached listeners.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEditable

Gets current value of property editable.

Non-editable controls have different colors, depending on custom settings

Default value is true.

getEnableCache

Gets current value of property enableCache.

When list suggestion is enabled all suggestions are cached and no suggest event is fired.

Default value is true.

getEnableClear

Gets current value of property enableClear.

Defines whether the clear functionality shall be active

Default value is false.

getEnabled

Gets current value of property enabled.

Disabled fields have different colors, and they can not be focused.

Default value is true.

getEnableFilterMode

Gets current value of property enableFilterMode.

Defines whether the search event should also be fired when the SearchField is empty (like a Filter field) and when the clear button (if activated) is pressed.

Default value is false.

getEnableListSuggest

Gets current value of property enableListSuggest.

Defines whether a pop up list shall be provided for suggestions

Default value is true.

getMaxHistoryItems

Gets current value of property maxHistoryItems.

Maximum number of history items in the suggestion list. 0 displays and stores no history. The history is locally stored on the client. Therefore do not activate this feature when this control handles confidential data.

Default value is 0.

getMaxLength

Gets current value of property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

Default value is 0.

getMaxSuggestionItems

Gets current value of property maxSuggestionItems.

Maximum number of suggestion items in the suggestion list.

Default value is 10.

sap.ui.commons.SearchField.getMetadata

Returns a metadata object for class sap.ui.commons.SearchField.

getPlaceholder

Gets current value of property placeholder.

Placeholder for the input field.

Default value is empty string.

getSearchProvider

Gets content of aggregation searchProvider.

Search provider instance which handles the suggestions for this SearchField (e.g. Open Search Protocol).

getShowExternalButton

Gets current value of property showExternalButton.

Defines whether an additional search button shall be displayed

Default value is false.

getShowListExpander

Gets current value of property showListExpander.

Defines whether the list expander shall be displayed in the case of an enabled list for suggestions. This feature is deactivated on mobile devices.

Default value is true.

getStartSuggestion

Gets current value of property startSuggestion.

Minimum length of the entered string triggering the suggestion list.

Default value is 3.

getTextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text

Default value is Begin.

getValue

Gets current value of property value.

Text that shall be displayed within the search field

Default value is empty string.

getValueState

Gets current value of property valueState.

Visualizes warnings or errors related to the input field. Possible values: Warning, Error, Success, None.

Default value is None.

getVisibleItemCount

Gets current value of property visibleItemCount.

Defines the number of items in the suggestion list that shall be displayed at once. If the overall number of list items is higher than the setting, a scroll bar is provided.

Default value is 20.

getWidth

Gets current value of property width.

Control width in CSS-size

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setEditable

Sets a new value for property editable.

Non-editable controls have different colors, depending on custom settings

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setEnableCache

Sets a new value for property enableCache.

When list suggestion is enabled all suggestions are cached and no suggest event is fired.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setEnableClear

Sets a new value for property enableClear.

Defines whether the clear functionality shall be active

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setEnabled

Sets a new value for property enabled.

Disabled fields have different colors, and they can not be focused.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setEnableFilterMode

Sets a new value for property enableFilterMode.

Defines whether the search event should also be fired when the SearchField is empty (like a Filter field) and when the clear button (if activated) is pressed.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setEnableListSuggest

Sets a new value for property enableListSuggest.

Defines whether a pop up list shall be provided for suggestions

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setMaxHistoryItems

Sets a new value for property maxHistoryItems.

Maximum number of history items in the suggestion list. 0 displays and stores no history. The history is locally stored on the client. Therefore do not activate this feature when this control handles confidential data.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

setMaxLength

Sets a new value for property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

setMaxSuggestionItems

Sets a new value for property maxSuggestionItems.

Maximum number of suggestion items in the suggestion list.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 10.

setPlaceholder

Sets a new value for property placeholder.

Placeholder for the input field.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setSearchProvider

Sets the aggregated searchProvider.

setShowExternalButton

Sets a new value for property showExternalButton.

Defines whether an additional search button shall be displayed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setShowListExpander

Sets a new value for property showListExpander.

Defines whether the list expander shall be displayed in the case of an enabled list for suggestions. This feature is deactivated on mobile devices.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setStartSuggestion

Sets a new value for property startSuggestion.

Minimum length of the entered string triggering the suggestion list.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 3.

setTextAlign

Sets a new value for property textAlign.

Sets the horizontal alignment of the text

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Begin.

setValue

Sets a new value for property value.

Text that shall be displayed within the search field

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setValueState

Sets a new value for property valueState.

Visualizes warnings or errors related to the input field. Possible values: Warning, Error, Success, None.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

setVisibleItemCount

Sets a new value for property visibleItemCount.

Defines the number of items in the suggestion list that shall be displayed at once. If the overall number of list items is higher than the setting, a scroll bar is provided.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 20.

setWidth

Sets a new value for property width.

Control width in CSS-size

When called with a value of null or undefined, the default value of the property will be restored.

suggest

Callback function used to provide the suggest values in the handler of the suggest event (only in list suggestion mode)

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

attachSearch

Attaches event handler fnFunction to the search event of this sap.ui.commons.SearchField.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.commons.SearchField itself.

Event which is fired when the user triggers a search

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.commons.SearchField itself

attachSuggest

Attaches event handler fnFunction to the suggest event of this sap.ui.commons.SearchField.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.commons.SearchField itself.

Event which is fired when new suggest values are required.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.commons.SearchField itself

clearHistory

Clears the history of the control

destroySearchProvider

Destroys the searchProvider in the aggregation searchProvider.

detachSearch

Detaches event handler fnFunction from the search event of this sap.ui.commons.SearchField.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachSuggest

Detaches event handler fnFunction from the suggest event of this sap.ui.commons.SearchField.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.commons.SearchField.extend

Creates a new subclass of class sap.ui.commons.SearchField with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireSearch

Fires event search to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

query string

The search query

fireSuggest

Fires event suggest to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The value for which suggestions are required.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEditable

Gets current value of property editable.

Non-editable controls have different colors, depending on custom settings

Default value is true.

getEnableCache

Gets current value of property enableCache.

When list suggestion is enabled all suggestions are cached and no suggest event is fired.

Default value is true.

getEnableClear

Gets current value of property enableClear.

Defines whether the clear functionality shall be active

Default value is false.

getEnabled

Gets current value of property enabled.

Disabled fields have different colors, and they can not be focused.

Default value is true.

getEnableFilterMode

Gets current value of property enableFilterMode.

Defines whether the search event should also be fired when the SearchField is empty (like a Filter field) and when the clear button (if activated) is pressed.

Default value is false.

getEnableListSuggest

Gets current value of property enableListSuggest.

Defines whether a pop up list shall be provided for suggestions

Default value is true.

getMaxHistoryItems

Gets current value of property maxHistoryItems.

Maximum number of history items in the suggestion list. 0 displays and stores no history. The history is locally stored on the client. Therefore do not activate this feature when this control handles confidential data.

Default value is 0.

getMaxLength

Gets current value of property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

Default value is 0.

getMaxSuggestionItems

Gets current value of property maxSuggestionItems.

Maximum number of suggestion items in the suggestion list.

Default value is 10.

sap.ui.commons.SearchField.getMetadata

Returns a metadata object for class sap.ui.commons.SearchField.

getPlaceholder

Gets current value of property placeholder.

Placeholder for the input field.

Default value is empty string.

getSearchProvider

Gets content of aggregation searchProvider.

Search provider instance which handles the suggestions for this SearchField (e.g. Open Search Protocol).

getShowExternalButton

Gets current value of property showExternalButton.

Defines whether an additional search button shall be displayed

Default value is false.

getShowListExpander

Gets current value of property showListExpander.

Defines whether the list expander shall be displayed in the case of an enabled list for suggestions. This feature is deactivated on mobile devices.

Default value is true.

getStartSuggestion

Gets current value of property startSuggestion.

Minimum length of the entered string triggering the suggestion list.

Default value is 3.

getTextAlign

Gets current value of property textAlign.

Sets the horizontal alignment of the text

Default value is Begin.

getValue

Gets current value of property value.

Text that shall be displayed within the search field

Default value is empty string.

getValueState

Gets current value of property valueState.

Visualizes warnings or errors related to the input field. Possible values: Warning, Error, Success, None.

Default value is None.

getVisibleItemCount

Gets current value of property visibleItemCount.

Defines the number of items in the suggestion list that shall be displayed at once. If the overall number of list items is higher than the setting, a scroll bar is provided.

Default value is 20.

getWidth

Gets current value of property width.

Control width in CSS-size

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

setEditable

Sets a new value for property editable.

Non-editable controls have different colors, depending on custom settings

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEditable boolean true

New value for property editable

setEnableCache

Sets a new value for property enableCache.

When list suggestion is enabled all suggestions are cached and no suggest event is fired.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnableCache boolean true

New value for property enableCache

setEnableClear

Sets a new value for property enableClear.

Defines whether the clear functionality shall be active

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bEnableClear boolean false

New value for property enableClear

setEnabled

Sets a new value for property enabled.

Disabled fields have different colors, and they can not be focused.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setEnableFilterMode

Sets a new value for property enableFilterMode.

Defines whether the search event should also be fired when the SearchField is empty (like a Filter field) and when the clear button (if activated) is pressed.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bEnableFilterMode boolean false

New value for property enableFilterMode

setEnableListSuggest

Sets a new value for property enableListSuggest.

Defines whether a pop up list shall be provided for suggestions

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnableListSuggest boolean true

New value for property enableListSuggest

setMaxHistoryItems

Sets a new value for property maxHistoryItems.

Maximum number of history items in the suggestion list. 0 displays and stores no history. The history is locally stored on the client. Therefore do not activate this feature when this control handles confidential data.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

Param Type DefaultValue Description
iMaxHistoryItems int 0

New value for property maxHistoryItems

setMaxLength

Sets a new value for property maxLength.

Maximum number of characters. Value '0' means the feature is switched off.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 0.

Param Type DefaultValue Description
iMaxLength int 0

New value for property maxLength

setMaxSuggestionItems

Sets a new value for property maxSuggestionItems.

Maximum number of suggestion items in the suggestion list.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 10.

Param Type DefaultValue Description
iMaxSuggestionItems int 10

New value for property maxSuggestionItems

setPlaceholder

Sets a new value for property placeholder.

Placeholder for the input field.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sPlaceholder string ""

New value for property placeholder

setSearchProvider

Sets the aggregated searchProvider.

Param Type DefaultValue Description
oSearchProvider sap.ui.core.search.SearchProvider

The searchProvider to set

setShowExternalButton

Sets a new value for property showExternalButton.

Defines whether an additional search button shall be displayed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowExternalButton boolean false

New value for property showExternalButton

setShowListExpander

Sets a new value for property showListExpander.

Defines whether the list expander shall be displayed in the case of an enabled list for suggestions. This feature is deactivated on mobile devices.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowListExpander boolean true

New value for property showListExpander

setStartSuggestion

Sets a new value for property startSuggestion.

Minimum length of the entered string triggering the suggestion list.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 3.

Param Type DefaultValue Description
iStartSuggestion int 3

New value for property startSuggestion

setTextAlign

Sets a new value for property textAlign.

Sets the horizontal alignment of the text

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Begin.

Param Type DefaultValue Description
sTextAlign sap.ui.core.TextAlign Begin

New value for property textAlign

setValue

Sets a new value for property value.

Text that shall be displayed within the search field

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sValue string ''

New value for property value

setValueState

Sets a new value for property valueState.

Visualizes warnings or errors related to the input field. Possible values: Warning, Error, Success, None.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Param Type DefaultValue Description
sValueState sap.ui.core.ValueState None

New value for property valueState

setVisibleItemCount

Sets a new value for property visibleItemCount.

Defines the number of items in the suggestion list that shall be displayed at once. If the overall number of list items is higher than the setting, a scroll bar is provided.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 20.

Param Type DefaultValue Description
iVisibleItemCount int 20

New value for property visibleItemCount

setWidth

Sets a new value for property width.

Control width in CSS-size

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

suggest

Callback function used to provide the suggest values in the handler of the suggest event (only in list suggestion mode)

Param Type DefaultValue Description
sSSuggestValue string

The value which was provided in the corresponding suggest event (parameter 'value')

aASuggestions string[]

The list of suggestions belonging to the suggest value