class sap.ui.mdc.FilterField

Control sample: sap.ui.mdc.FilterField
Visiblity: restricted
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/mdc/FilterField
Application Component: CA-UI5-MDC

The FilterField control is used to filter data based on the conditions. The conditions are managed in the corresponding ConditionModel. That is why the conditions property must be bound to the related conditions in the ConditionModel. The type of this data must be defined in the dataType property.


Constructor

Constructor for a new FilterField.

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.mdc.FilterField(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
defaultOperator string

Default operator name for conditions. If empty, the relevant default operator depending on the data type used is taken.

Note: defaultOperator can be the name of an Operator or the instance itself.

Since: 1.88.0.

Visibility: public
operators string[]

Supported operator names for conditions.

If empty, default operators depending on used data type are used.

Since: 1.73.0.

Visibility: public

Borrowed Properties

Name Type Default Value Description
conditions object[]

Sets the conditions that represent the values of the field.

This should be bound to a ConditionModel using the corresponding fieldPath.

Note: For FilterField controls, the conditions property must be used to bind FilterField to a ConditionModel.
For example, for a FilterField control inside a FilterBar control the binding looks like this:
conditions="{$filters>/conditions/propertyPath}" with the following data:

  • $filters as the name of the condition model
  • /conditions/ as a required static part of the binding
  • propertyPath as the property name

For an Any (see sap.ui.model.FilterOperator) FilterField control, the binding looks like this:
conditions='{$filters>/conditions/navPath*/propertyPath}' with the following data:

  • $filters as the name of the condition model
  • /conditions/ as a required static part of the binding
  • navPath#42;/ as the navigation property name
  • propertyPath as the property name
Between navPath and propertyPath, */ is required.

Note: A condition must have the structure of ConditionObject.

Visibility: public
dataType string sap.ui.model.type.String

The type of data handled by the field. This type is used to parse, format, and validate the value.

Visibility: public
dataTypeConstraints object

The constraints of the type specified in dataType.

Visibility: public
dataTypeFormatOptions object

The format options of the type specified in dataType.

Visibility: public
delegate object ...see text or source

Path to FieldBaseDelegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. Once the required module is associated, this property might not be needed any longer.

Since: 1.72.0.

Visibility: public
display sap.ui.mdc.enum.FieldDisplay Value

Defines whether the value and/or description of the field is shown and in what order.

Visibility: public
editMode sap.ui.mdc.enum.EditMode Editable

Determines whether the field is editable, read-only, or disabled.

Visibility: public
label string empty string

Defines the label text for the field.

This can be used by FilterBar or Form controls to create a Label control for the field.

Since: 1.62.0.

Visibility: public
maxConditions int -1

Sets the maximum amount of conditions that are allowed for this field.

The default value of -1 indicates that an unlimited amount of conditions can be defined.

Note If the data type used doesn't support multiple conditions, an error is thrown.

Visibility: public
multipleLines boolean false

If set, the Field is rendered using a multi-line control.

This property only affects types that support multiple lines.

Note If the data type used doesn't support multiple lines an error is thrown.

Visibility: public
placeholder string empty string

Defines a short hint intended to aid the user with data entry when the control has no value. If the value is null no placeholder is shown.

Note: If the rendered control doesn't support this feature, this property is ignored.

Visibility: public
required boolean false

Indicates that user input is required.

Visibility: public
showEmptyIndicator boolean false

If set, an empty Field renders an empty-indicator in display mode.

This property only takes effect if editMode is set to Display.

Note Empty means the Field holds no value. If an empty string is a valid value, the Field might show nothing, depending on the display settings and assigned description or FieldHelp.

Since: 1.85.0.

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

Defines the horizontal alignment of the text that is shown inside the input field.

Note: If the rendered control doesn't support this feature, this property is ignored.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, for example RTL, LTR.

Note: If the rendered control doesn't support this feature, this property is ignored.

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

Visualizes the validation state of the control, for example Error, Warning, Success.

Note: The visualization of the ValueState property is handled by the inner rendered control. If a control is set (using content, contentEdit, or contentDisplay), this control needs to support the valueState behavior, otherwise valueState is not visualized.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this has not specified, a default text from the resource bundle is shown.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Visibility: public
delegate object

Path to the Delegate module that provides the required APIs to execute model-specific logic.
Note: Ensure that the related file can be requested (any required library has to be loaded before that).
Do not bind or modify the module. This property can only be configured during control initialization.

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
content 0..1 sap.ui.core.Control

Optional content that can be rendered.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

contentDisplay 0..1 sap.ui.core.Control

Optional content to be rendered if the editMode property is set to Display.

Note: If a control is assigned to the content aggregation, this one is ignored.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

Since: 1.61.0.

contentEdit 0..1 sap.ui.core.Control

Optional content to be rendered if the editMode property is not set to Display.

Note: If a control is assigned to the content aggregation, this one is ignored.

Note: Bind the value-holding property of the control to '$field>/conditions' using ConditionsType as type.

If the control needs to show multiple conditions, bind its aggregation to '$field>/conditions'. Bind the item controls value-holding property using ConditionType as type.

Warning: Only controls allowed in a Form are allowed to be used for this optional content. Other controls might break the layout. This means the IFormContent interface needs to be implemented by these controls.

Since: 1.61.0.

fieldInfo 0..1 sap.ui.mdc.field.FieldInfoBase

Optional FieldInfo used for detail information. This is only active in display mode.

Note: If a special data type is defined or a content control is set, this is ignored.


Events Overview

Event Description
change

This event is fired when the value property of the field is changed.

Note This event is only triggered if the used content control has a change event.

change

This event is fired when the value property of the field is changed.

Note This event is only triggered if the used content control has a change event.

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

The new value of the control

valid boolean

Flag that indicates if the entered value is valid

conditions object[]

Conditions of the field. This includes all conditions, not only the changed ones.

Since: 1.61.0.

promise boolean

Returns a Promise for the change. The Promise returns the value if it is resolved. If the change event is synchronous, the promise has already been already resolved. If it is asynchronous, it will be resolved after the value has been updated.

The FilterField should be set to busy during the parsing to prevent user input. As there might be a whole group of fields that needs to be busy, this cannot be done automatically.

Since: 1.69.0.


Methods Overview

Method Description
addOperator

Adds an operator to the list of known operators.

addOperators

Adds an array of operators to the list of known operators.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.mdc.FilterField.

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.mdc.FilterField itself.

This event is fired when the value property of the field is changed.

Note This event is only triggered if the used content control has a change event.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.mdc.FilterField.

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

sap.ui.mdc.FilterField.extend

Creates a new subclass of class sap.ui.mdc.FilterField 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.mdc.field.FieldBase.extend.

fireChange

Fires event change to attached listeners.

getDefaultOperator

Gets current value of property defaultOperator.

Default operator name for conditions. If empty, the relevant default operator depending on the data type used is taken.

Note: defaultOperator can be the name of an Operator or the instance itself.

sap.ui.mdc.FilterField.getMetadata

Returns a metadata object for class sap.ui.mdc.FilterField.

getOperators

Gets current value of property operators.

Supported operator names for conditions.

If empty, default operators depending on used data type are used.

Default value is [].

removeAllOperators

Removes all operators from the list of known operators.

removeOperator

Removes an operator from the list of known operators.

removeOperators

Removes all given operators from the list of known operators.

setDefaultOperator

Sets a new value for property defaultOperator.

Default operator name for conditions. If empty, the relevant default operator depending on the data type used is taken.

Note: defaultOperator can be the name of an Operator or the instance itself.

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

setOperators

Sets a new value for property operators.

Supported operator names for conditions.

If empty, default operators depending on used data type are used.

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

Default value is [].

addOperator

Adds an operator to the list of known operators.

Param Type DefaultValue Description
vOperator sap.ui.mdc.condition.Operator string

The operator instance or operator name

Note: If no operator is set, the used type of the FilterField defines the set of default operators.

addOperators

Adds an array of operators to the list of known operators.

Param Type DefaultValue Description
aOperators sap.ui.mdc.condition.Operator[]

Array of operators

Note: aOperators can be the name of an Operator, the instance itself, or multiple operators inside an array.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.mdc.FilterField.

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.mdc.FilterField itself.

This event is fired when the value property of the field is changed.

Note This event is only triggered if the used content control has a change 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.ui.mdc.FilterField itself

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.mdc.FilterField.

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.mdc.FilterField.extend

Creates a new subclass of class sap.ui.mdc.FilterField 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.mdc.field.FieldBase.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

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The new value of the control

valid boolean

Flag that indicates if the entered value is valid

conditions object[]

Conditions of the field. This includes all conditions, not only the changed ones.

promise boolean

Returns a Promise for the change. The Promise returns the value if it is resolved. If the change event is synchronous, the promise has already been already resolved. If it is asynchronous, it will be resolved after the value has been updated.

The FilterField should be set to busy during the parsing to prevent user input. As there might be a whole group of fields that needs to be busy, this cannot be done automatically.

getDefaultOperator

Gets current value of property defaultOperator.

Default operator name for conditions. If empty, the relevant default operator depending on the data type used is taken.

Note: defaultOperator can be the name of an Operator or the instance itself.

sap.ui.mdc.FilterField.getMetadata

Returns a metadata object for class sap.ui.mdc.FilterField.

getOperators

Gets current value of property operators.

Supported operator names for conditions.

If empty, default operators depending on used data type are used.

Default value is [].

removeAllOperators

Removes all operators from the list of known operators.

removeOperator

Removes an operator from the list of known operators.

Param Type DefaultValue Description
vOperator sap.ui.mdc.condition.Operator string

The operator instance or operator name

removeOperators

Removes all given operators from the list of known operators.

Param Type DefaultValue Description
aOperators sap.ui.mdc.condition.Operator[]

Array of operators

Note: aOperators can be the name of an Operator, the instance itself, or multiple operators inside an array.

setDefaultOperator

Sets a new value for property defaultOperator.

Default operator name for conditions. If empty, the relevant default operator depending on the data type used is taken.

Note: defaultOperator can be the name of an Operator or the instance itself.

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

Param Type DefaultValue Description
sDefaultOperator string

New value for property defaultOperator

setOperators

Sets a new value for property operators.

Supported operator names for conditions.

If empty, default operators depending on used data type are used.

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

Default value is [].

Param Type DefaultValue Description
sOperators string[] []

New value for property operators