class sap.f.SearchManager

Control sample: sap.f.SearchManager
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/f/SearchManager
Application Component: CA-UI5-CTR

Defines specific properties of the search that are applied to sap.f.ShellBar.


Constructor

Constructor for a new SearchManager.

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.f.SearchManager(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
enableSuggestions boolean false

If true, a suggest event is fired when user types in the input and when the input is focused. On a phone device, a full screen dialog with suggestions is always shown even if the suggestions list is empty.

Visibility: public
enabled boolean true

Determines whether the control is enabled.

Visibility: public
maxLength int 0

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

Visibility: public
placeholder string

Defines the text that is displayed when no value is available. The default placeholder text is the word "Search" in the current local language (if supported) or in English.

Visibility: public
value string

Defines the input value.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
suggestionItems 0..n sap.m.SuggestionItem

SuggestionItems are the items which are displayed in the suggestions list. The following properties can be used:

  • key - it is not displayed and may be used as internal technical field
  • text - it is displayed as normal suggestion text
  • icon
  • description - additional text that may be used to visually display search item type or category


Events Overview

Event Description
liveChange

Fired when the value of the search field is changed by the user, for example at each key press.

Note: Do not invalidate or re-render a focused search field, especially during the liveChange event.

search

Fired when the user triggers a search.

suggest

Fired when the search field is initially focused or its value is changed by the user. This event means that suggestion data should be updated, in case if suggestions are used. Use the value parameter to create new suggestions for it.

liveChange

Fired when the value of the search field is changed by the user, for example at each key press.

Note: Do not invalidate or re-render a focused search field, especially during the liveChange event.

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

Current search string.

search

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 string.

clearButtonPressed boolean

Indicates if the user pressed the clear icon.

suggest

Fired when the search field is initially focused or its value is changed by the user. This event means that suggestion data should be updated, in case if suggestions are used. Use the value parameter to create new suggestions for it.

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

Current search string of the search field.


Methods Overview

Method Description
addSuggestionItem

Adds some suggestionItem to the aggregation suggestionItems.

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.f.SearchManager.

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.f.SearchManager itself.

Fired when the value of the search field is changed by the user, for example at each key press.

Note: Do not invalidate or re-render a focused search field, especially during the liveChange event.

attachSearch

Attaches event handler fnFunction to the search event of this sap.f.SearchManager.

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.f.SearchManager itself.

Fired when the user triggers a search.

attachSuggest

Attaches event handler fnFunction to the suggest event of this sap.f.SearchManager.

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.f.SearchManager itself.

Fired when the search field is initially focused or its value is changed by the user. This event means that suggestion data should be updated, in case if suggestions are used. Use the value parameter to create new suggestions for it.

bindValue

Binds property value to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

destroySuggestionItems

Destroys all the suggestionItems in the aggregation suggestionItems.

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.f.SearchManager.

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

detachSearch

Detaches event handler fnFunction from the search event of this sap.f.SearchManager.

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.f.SearchManager.

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

sap.f.SearchManager.extend

Creates a new subclass of class sap.f.SearchManager 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.Element.extend.

fireLiveChange

Fires event liveChange to attached listeners.

fireSearch

Fires event search to attached listeners.

fireSuggest

Fires event suggest to attached listeners.

getEnabled

Gets current value of property enabled.

Determines whether the control is enabled.

Default value is true.

getEnableSuggestions

Gets current value of property enableSuggestions.

If true, a suggest event is fired when user types in the input and when the input is focused. On a phone device, a full screen dialog with suggestions is always shown even if the suggestions list is empty.

Default value is false.

getMaxLength

Gets current value of property maxLength.

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

Default value is 0.

sap.f.SearchManager.getMetadata

Returns a metadata object for class sap.f.SearchManager.

getPlaceholder

Gets current value of property placeholder.

Defines the text that is displayed when no value is available. The default placeholder text is the word "Search" in the current local language (if supported) or in English.

getSuggestionItems

Gets content of aggregation suggestionItems.

SuggestionItems are the items which are displayed in the suggestions list. The following properties can be used:

  • key - it is not displayed and may be used as internal technical field
  • text - it is displayed as normal suggestion text
  • icon
  • description - additional text that may be used to visually display search item type or category

getValue

Gets current value of property value.

Defines the input value.

indexOfSuggestionItem

Checks for the provided sap.m.SuggestionItem in the aggregation suggestionItems. and returns its index if found or -1 otherwise.

insertSuggestionItem

Inserts a suggestionItem into the aggregation suggestionItems.

removeAllSuggestionItems

Removes all the controls from the aggregation suggestionItems.

Additionally, it unregisters them from the hosting UIArea.

removeSuggestionItem

Removes a suggestionItem from the aggregation suggestionItems.

setEnabled

Sets a new value for property enabled.

Determines whether the control is enabled.

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

Default value is true.

setEnableSuggestions

Sets a new value for property enableSuggestions.

If true, a suggest event is fired when user types in the input and when the input is focused. On a phone device, a full screen dialog with suggestions is always shown even if the suggestions list is empty.

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

Default value is false.

setMaxLength

Sets a new value for property maxLength.

Determines the 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.

setPlaceholder

Sets a new value for property placeholder.

Defines the text that is displayed when no value is available. The default placeholder text is the word "Search" in the current local language (if supported) or in English.

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

setValue

Sets a new value for property value.

Defines the input value.

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

unbindValue

Unbinds property value from model data.

addSuggestionItem

Adds some suggestionItem to the aggregation suggestionItems.

Param Type DefaultValue Description
oSuggestionItem sap.m.SuggestionItem

The suggestionItem to add; if empty, nothing is inserted

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.f.SearchManager.

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.f.SearchManager itself.

Fired when the value of the search field is changed by the user, for example at each key press.

Note: Do not invalidate or re-render a focused search field, especially during the liveChange event.

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.f.SearchManager itself

attachSearch

Attaches event handler fnFunction to the search event of this sap.f.SearchManager.

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.f.SearchManager itself.

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.f.SearchManager itself

attachSuggest

Attaches event handler fnFunction to the suggest event of this sap.f.SearchManager.

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.f.SearchManager itself.

Fired when the search field is initially focused or its value is changed by the user. This event means that suggestion data should be updated, in case if suggestions are used. Use the value parameter to create new suggestions for it.

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.f.SearchManager itself

bindValue

Binds property value to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.PropertyBindingInfo

The binding information

destroySuggestionItems

Destroys all the suggestionItems in the aggregation suggestionItems.

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.f.SearchManager.

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

detachSearch

Detaches event handler fnFunction from the search event of this sap.f.SearchManager.

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.f.SearchManager.

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.f.SearchManager.extend

Creates a new subclass of class sap.f.SearchManager 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.Element.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

fireLiveChange

Fires event liveChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

newValue string

Current search string.

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 string.

clearButtonPressed boolean

Indicates if the user pressed the clear icon.

fireSuggest

Fires event suggest to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

suggestValue string

Current search string of the search field.

getEnabled

Gets current value of property enabled.

Determines whether the control is enabled.

Default value is true.

getEnableSuggestions

Gets current value of property enableSuggestions.

If true, a suggest event is fired when user types in the input and when the input is focused. On a phone device, a full screen dialog with suggestions is always shown even if the suggestions list is empty.

Default value is false.

getMaxLength

Gets current value of property maxLength.

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

Default value is 0.

sap.f.SearchManager.getMetadata

Returns a metadata object for class sap.f.SearchManager.

getPlaceholder

Gets current value of property placeholder.

Defines the text that is displayed when no value is available. The default placeholder text is the word "Search" in the current local language (if supported) or in English.

getSuggestionItems

Gets content of aggregation suggestionItems.

SuggestionItems are the items which are displayed in the suggestions list. The following properties can be used:

getValue

Gets current value of property value.

Defines the input value.

indexOfSuggestionItem

Checks for the provided sap.m.SuggestionItem in the aggregation suggestionItems. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oSuggestionItem sap.m.SuggestionItem

The suggestionItem whose index is looked for

insertSuggestionItem

Inserts a suggestionItem into the aggregation suggestionItems.

Param Type DefaultValue Description
oSuggestionItem sap.m.SuggestionItem

The suggestionItem to insert; if empty, nothing is inserted

iIndex int

The 0-based index the suggestionItem should be inserted at; for a negative value of iIndex, the suggestionItem is inserted at position 0; for a value greater than the current size of the aggregation, the suggestionItem is inserted at the last position

removeAllSuggestionItems

Removes all the controls from the aggregation suggestionItems.

Additionally, it unregisters them from the hosting UIArea.

removeSuggestionItem

Removes a suggestionItem from the aggregation suggestionItems.

Param Type DefaultValue Description
vSuggestionItem int string sap.m.SuggestionItem

The suggestionItem to remove or its index or id

setEnabled

Sets a new value for property enabled.

Determines whether the control is enabled.

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

setEnableSuggestions

Sets a new value for property enableSuggestions.

If true, a suggest event is fired when user types in the input and when the input is focused. On a phone device, a full screen dialog with suggestions is always shown even if the suggestions list is empty.

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
bEnableSuggestions boolean false

New value for property enableSuggestions

setMaxLength

Sets a new value for property maxLength.

Determines the 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

setPlaceholder

Sets a new value for property placeholder.

Defines the text that is displayed when no value is available. The default placeholder text is the word "Search" in the current local language (if supported) or in English.

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

Param Type DefaultValue Description
sPlaceholder string

New value for property placeholder

setValue

Sets a new value for property value.

Defines the input value.

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

Param Type DefaultValue Description
sValue string

New value for property value

unbindValue

Unbinds property value from model data.