abstract class sap.ui.mdc.field.FieldBase

Visiblity: restricted
UX Guidelines:
Implements: sap.ui.core.IFormContentsap.ui.core.ISemanticFormContent
Available since: N/A
Module: sap/ui/mdc/field/FieldBase
Application Component: CA-UI5-MDC

The FieldBase control is the basic control to be used within the Field and FilterField controls. It must not be used stand-alone.


Constructor

Constructor for a new FieldBase.

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.field.FieldBase(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
_ariaAttributes object empty object

Sets the ARIA attributes added to the inner control.

The object contains ARIA attributes in an aria node. Additional attributes, such as role, autocomplete or valueHelpEnabled, are added on root level.

Visibility: hidden
_fieldHelpEnabled boolean false

Internal property to bind the showValueHelp property of the internal Input control.

Visibility: hidden
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

Borrowed Properties

Name Type Default Value Description
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

Aggregations

Default Aggregation: content

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

Internal content if no control set from outside.

content (default) 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.


Associations

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

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

fieldHelp 0..1 sap.ui.mdc.ValueHelp

Optional FieldHelp.

This is an association that allows the usage of one FieldHelp instance for multiple fields.

Note: If the field is inside of a table, do not set the FieldHelp instance as dependent to the field. If you do every field instance in every table row gets a clone of it. Put the FieldHelp instance e.g. as dependent on the table or page. The FieldHelp instance must be somewhere in the control tree, otherwise there might be rendering or update issues.

Note: For Boolean fields, no FieldHelp should be added, but a default FieldHelp used instead.


Events Overview

Event Description
liveChange

This event is fired when the value of the field is changed, for example, each time a key is pressed.

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

press

This event is fired if the inner control has a press event and this is fired.

submit

This event is fired when the user presses Enter. It allows the application to implement some submit logic.

Note This event is only triggered if the field is editable.

Since: 1.82.0.

liveChange

This event is fired when the value of the field is changed, for example, each time a key is pressed.

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

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

The new value of the input

escPressed boolean

Indicates that the ESC key triggered the event

previousValue string

The value of the input before pressing ESC key

press

This event is fired if the inner control has a press event and this is fired.

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

submit

This event is fired when the user presses Enter. It allows the application to implement some submit logic.

Note This event is only triggered if the field is editable.

Since: 1.82.0.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
promise Promise

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


Methods Overview

Method Description
_checkValueInitial

If the value is the initial value of the type (String types) and the field does not show tokens or operators, no condition must be set as the field is then empty.

_getFormatOptions

Provides some internals of the field to be used in the value help.

_observeChanges

Observes changes.

To be enhanced by Field, FilterField, or other inherited controls.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired when the value of the field is changed, for example, each time a key is pressed.

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

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired if the inner control has a press event and this is fired.

attachSubmit

Attaches event handler fnFunction to the submit event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired when the user presses Enter. It allows the application to implement some submit logic.

Note This event is only triggered if the field is editable.

connectLabel

Assigns a Label control to the Field or FilterField controls.

The text of the label is taken from the Field or FilterField controls. The labelFor association is set to the Field or FilterField control.

destroyContent

Destroys the content in the aggregation content.

destroyContentDisplay

Destroys the contentDisplay in the aggregation contentDisplay.

destroyContentEdit

Destroys the contentEdit in the aggregation contentEdit.

destroyFieldInfo

Destroys the fieldInfo in the aggregation fieldInfo.

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.ui.mdc.field.FieldBase.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.ui.mdc.field.FieldBase.

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

detachSubmit

Detaches event handler fnFunction from the submit event of this sap.ui.mdc.field.FieldBase.

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

sap.ui.mdc.field.FieldBase.extend

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

fireLiveChange

Fires event liveChange to attached listeners.

firePress

Fires event press to attached listeners.

fireSubmit

Fires event submit to attached listeners.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getAriaLabelledBy

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

getConditions

Gets current value of property conditions.

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.

Default value is [].

getContent

Gets content of aggregation content.

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.

getContentDisplay

Gets content of aggregation contentDisplay.

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.

getContentEdit

Gets content of aggregation contentEdit.

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.

getControlForSuggestion

Returns the control the value help is attached to.

In the case that number and unit are shown in different controls, this is the unit control, not the number control.

getDataType

Gets current value of property dataType.

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

Default value is 'sap.ui.model.type.String'.

getDataTypeConstraints

Gets current value of property dataTypeConstraints.

The constraints of the type specified in dataType.

getDataTypeFormatOptions

Gets current value of property dataTypeFormatOptions.

The format options of the type specified in dataType.

getDelegate

Gets current value of property delegate.

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.

Default value is ...see text or source.

getDisplay

Gets current value of property display.

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

Default value is Value.

getEditMode

Gets current value of property editMode.

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

Default value is Editable.

getFieldHelp

ID of the element which is the current target of the association fieldHelp, or null.

getFieldInfo

Gets content of aggregation fieldInfo.

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.

getFieldPath

Gets fieldPath.

If the conditions are bound to a ConditionModel, the FieldPath is determined from this binding.

getLabel

Gets current value of property label.

Defines the label text for the field.

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

Default value is empty string.

getMaxConditions

Gets current value of property maxConditions.

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.

Default value is -1.

getMaxConditionsForHelp

In the case that number and unit are shown in different controls, only one unit is supported. So the value help needs to be in single selection mode.

sap.ui.mdc.field.FieldBase.getMetadata

Returns a metadata object for class sap.ui.mdc.field.FieldBase.

getMultipleLines

Gets current value of property multipleLines.

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.

Default value is false.

getPlaceholder

Gets current value of property placeholder.

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.

Default value is empty string.

getRequired

Gets current value of property required.

Indicates that user input is required.

Default value is false.

getShowEmptyIndicator

Gets current value of property showEmptyIndicator.

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.

Default value is false.

getTextAlign

Gets current value of property textAlign.

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.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

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.

Default value is Inherit.

getValueState

Gets current value of property valueState.

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.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

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.

getWidth

Gets current value of property width.

Defines the width of the control.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setConditions

Sets a new value for property conditions.

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.

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

Default value is [].

setContent

Sets the aggregated content.

setContentDisplay

Sets the aggregated contentDisplay.

setContentEdit

Sets the aggregated contentEdit.

setDataType

Sets a new value for property dataType.

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

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

Default value is 'sap.ui.model.type.String'.

setDataTypeConstraints

Sets a new value for property dataTypeConstraints.

The constraints of the type specified in dataType.

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

setDataTypeFormatOptions

Sets a new value for property dataTypeFormatOptions.

The format options of the type specified in dataType.

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

setDelegate

Sets a new value for property delegate.

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.

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

Default value is ...see text or source.

setDisplay

Sets a new value for property display.

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

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

Default value is Value.

setEditMode

Sets a new value for property editMode.

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

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

Default value is Editable.

setFieldHelp

Sets the associated fieldHelp.

setFieldInfo

Sets the aggregated fieldInfo.

setLabel

Sets a new value for property label.

Defines the label text for the field.

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

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

Default value is empty string.

setMaxConditions

Sets a new value for property maxConditions.

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.

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

Default value is -1.

setMultipleLines

Sets a new value for property multipleLines.

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.

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

Default value is false.

setPlaceholder

Sets a new value for property placeholder.

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.

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

Default value is empty string.

setRequired

Sets a new value for property required.

Indicates that user input is required.

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

Default value is false.

setShowEmptyIndicator

Sets a new value for property showEmptyIndicator.

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.

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

Default value is false.

setTextAlign

Sets a new value for property textAlign.

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.

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

Default value is Initial.

setTextDirection

Sets a new value for property textDirection.

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.

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

Default value is Inherit.

setValueState

Sets a new value for property valueState.

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.

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

Default value is None.

setValueStateText

Sets a new value for property valueStateText.

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.

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

setWidth

Sets a new value for property width.

Defines the width of the control.

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

_checkValueInitial

If the value is the initial value of the type (String types) and the field does not show tokens or operators, no condition must be set as the field is then empty.

Param Type DefaultValue Description
vValue any

Value to be checked

_getFormatOptions

Provides some internals of the field to be used in the value help.

_observeChanges

Observes changes.

To be enhanced by Field, FilterField, or other inherited controls.

Param Type DefaultValue Description
oChanges object

Changes

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

attachLiveChange

Attaches event handler fnFunction to the liveChange event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired when the value of the field is changed, for example, each time a key is pressed.

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

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired if the inner control has a press event and this is fired.

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.field.FieldBase itself

attachSubmit

Attaches event handler fnFunction to the submit event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase itself.

This event is fired when the user presses Enter. It allows the application to implement some submit logic.

Note This event is only triggered if the field is editable.

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.field.FieldBase itself

connectLabel

Assigns a Label control to the Field or FilterField controls.

The text of the label is taken from the Field or FilterField controls. The labelFor association is set to the Field or FilterField control.

Param Type DefaultValue Description
oLabel sap.ui.core.Label

Label control

destroyContent

Destroys the content in the aggregation content.

destroyContentDisplay

Destroys the contentDisplay in the aggregation contentDisplay.

destroyContentEdit

Destroys the contentEdit in the aggregation contentEdit.

destroyFieldInfo

Destroys the fieldInfo in the aggregation fieldInfo.

detachLiveChange

Detaches event handler fnFunction from the liveChange event of this sap.ui.mdc.field.FieldBase.

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

detachPress

Detaches event handler fnFunction from the press event of this sap.ui.mdc.field.FieldBase.

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

detachSubmit

Detaches event handler fnFunction from the submit event of this sap.ui.mdc.field.FieldBase.

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.field.FieldBase.extend

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

fireLiveChange

Fires event liveChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The new value of the input

escPressed boolean

Indicates that the ESC key triggered the event

previousValue string

The value of the input before pressing ESC key

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireSubmit

Fires event submit to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

promise Promise

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

getAccessibilityInfo

References:

getAriaLabelledBy

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

getConditions

Gets current value of property conditions.

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:

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

Between navPath and propertyPath, */ is required.

Note: A condition must have the structure of ConditionObject.

Default value is [].

getContent

Gets content of aggregation content.

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.

getContentDisplay

Gets content of aggregation contentDisplay.

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.

getContentEdit

Gets content of aggregation contentEdit.

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.

getControlForSuggestion

Returns the control the value help is attached to.

In the case that number and unit are shown in different controls, this is the unit control, not the number control.

getDataType

Gets current value of property dataType.

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

Default value is 'sap.ui.model.type.String'.

getDataTypeConstraints

Gets current value of property dataTypeConstraints.

The constraints of the type specified in dataType.

getDataTypeFormatOptions

Gets current value of property dataTypeFormatOptions.

The format options of the type specified in dataType.

getDelegate

Gets current value of property delegate.

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.

Default value is ...see text or source.

getDisplay

Gets current value of property display.

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

Default value is Value.

getEditMode

Gets current value of property editMode.

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

Default value is Editable.

getFieldHelp

ID of the element which is the current target of the association fieldHelp, or null.

getFieldInfo

Gets content of aggregation fieldInfo.

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.

getFieldPath

Gets fieldPath.

If the conditions are bound to a ConditionModel, the FieldPath is determined from this binding.

getLabel

Gets current value of property label.

Defines the label text for the field.

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

Default value is empty string.

getMaxConditions

Gets current value of property maxConditions.

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.

Default value is -1.

getMaxConditionsForHelp

In the case that number and unit are shown in different controls, only one unit is supported. So the value help needs to be in single selection mode.

sap.ui.mdc.field.FieldBase.getMetadata

Returns a metadata object for class sap.ui.mdc.field.FieldBase.

getMultipleLines

Gets current value of property multipleLines.

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.

Default value is false.

getPlaceholder

Gets current value of property placeholder.

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.

Default value is empty string.

getRequired

Gets current value of property required.

Indicates that user input is required.

Default value is false.

getShowEmptyIndicator

Gets current value of property showEmptyIndicator.

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.

Default value is false.

getTextAlign

Gets current value of property textAlign.

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.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

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.

Default value is Inherit.

getValueState

Gets current value of property valueState.

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.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

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.

getWidth

Gets current value of property width.

Defines the width of the control.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

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

setConditions

Sets a new value for property conditions.

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:

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

Between navPath and propertyPath, */ is required.

Note: A condition must have the structure of ConditionObject.

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
sConditions object[] []

New value for property conditions

setContent

Sets the aggregated content.

Param Type DefaultValue Description
oContent sap.ui.core.Control

The content to set

setContentDisplay

Sets the aggregated contentDisplay.

Param Type DefaultValue Description
oContentDisplay sap.ui.core.Control

The contentDisplay to set

setContentEdit

Sets the aggregated contentEdit.

Param Type DefaultValue Description
oContentEdit sap.ui.core.Control

The contentEdit to set

setDataType

Sets a new value for property dataType.

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

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

Default value is 'sap.ui.model.type.String'.

Param Type DefaultValue Description
sDataType string 'sap.ui.model.type.String'

New value for property dataType

setDataTypeConstraints

Sets a new value for property dataTypeConstraints.

The constraints of the type specified in dataType.

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

Param Type DefaultValue Description
oDataTypeConstraints object

New value for property dataTypeConstraints

setDataTypeFormatOptions

Sets a new value for property dataTypeFormatOptions.

The format options of the type specified in dataType.

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

Param Type DefaultValue Description
oDataTypeFormatOptions object

New value for property dataTypeFormatOptions

setDelegate

Sets a new value for property delegate.

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.

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

Default value is ...see text or source.

Param Type DefaultValue Description
oDelegate object ...see text or source

New value for property delegate

setDisplay

Sets a new value for property display.

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

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

Default value is Value.

Param Type DefaultValue Description
sDisplay sap.ui.mdc.enum.FieldDisplay Value

New value for property display

setEditMode

Sets a new value for property editMode.

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

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

Default value is Editable.

Param Type DefaultValue Description
sEditMode sap.ui.mdc.enum.EditMode Editable

New value for property editMode

setFieldHelp

Sets the associated fieldHelp.

Param Type DefaultValue Description
oFieldHelp sap.ui.core.ID sap.ui.mdc.ValueHelp

ID of an element which becomes the new target of this fieldHelp association; alternatively, an element instance may be given

setFieldInfo

Sets the aggregated fieldInfo.

Param Type DefaultValue Description
oFieldInfo sap.ui.mdc.field.FieldInfoBase

The fieldInfo to set

setLabel

Sets a new value for property label.

Defines the label text for the field.

This can be used by FilterBar or Form controls to create a Label control for the 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
sLabel string ""

New value for property label

setMaxConditions

Sets a new value for property maxConditions.

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.

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

Default value is -1.

Param Type DefaultValue Description
iMaxConditions int -1

New value for property maxConditions

setMultipleLines

Sets a new value for property multipleLines.

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.

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

New value for property multipleLines

setPlaceholder

Sets a new value for property placeholder.

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.

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

setRequired

Sets a new value for property required.

Indicates that user input is required.

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

New value for property required

setShowEmptyIndicator

Sets a new value for property showEmptyIndicator.

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.

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

New value for property showEmptyIndicator

setTextAlign

Sets a new value for property textAlign.

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.

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

Default value is Initial.

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

New value for property textAlign

setTextDirection

Sets a new value for property textDirection.

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.

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

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setValueState

Sets a new value for property valueState.

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.

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

setValueStateText

Sets a new value for property valueStateText.

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.

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

Param Type DefaultValue Description
sValueStateText string

New value for property valueStateText

setWidth

Sets a new value for property width.

Defines the width of the control.

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