class sap.ui.comp.smartfield.SmartField

Visiblity: public
UX Guidelines: Smart Field
Implements: sap.ui.core.IFormContentsap.ui.core.ISemanticFormContent
Available since: N/A
Module: sap/ui/comp/smartfield/SmartField
Application Component: CA-UI5-CMP

The SmartField control interprets metadata that represents entity-relationship models, data types, service capabilities, and annotations in OData services to automatically generate the underlying inner controls and reduce the amount of code needed for developing applications. In some cases, the OData entity is derived from the control's binding context. The OData entity's property that is changed or displayed with the control is derived from the control's value property.

Important: Keep in mind that SmartField, like all SAPUI5 smart controls, retrieves and analyzes the metadata and annotations of OData services. The OData metadata is its primary API. These OData services are not part of the SAPUI5 framework and are usually maintained by the backend developers of your application.

With time, SmartField can evolve and acquire new features. This means that its behavior or functionalities may change if the annotations that define this change are maintained in your backend metadata. To benefit from the new functionalities, your application should be able to adapt the backend metadata. Therefore, we recommend using SmartField only if you have control over the metadata of your application.

Accessibility

For interoperability and accessibility reasons, the SmartField control must be labeled by the sap.ui.comp.smartfield.SmartLabel control instead of the sap.m.Label control, as the sap.m.Label control does not know of the inner structure of a SmartField control. If the SmartField control is rendered inside a smart container control, for example, the SmartForm control, the SmartLabel control is automatically generated to reduce the amount of code needed on the application side. However, in other scenarios when SmartField is used stand-alone or outside a smart container control, for example, a SimpleForm control, the SmartLabel control is not automatically generated in these cases. Although the sap.ui.comp.smartfield.SmartLabel is a private/internal control, the following basic use is allowed by applications for labeling the SmartField control.

XML Example of a SmartField control labeled by a SmartLabel control

<sap.ui.comp.smartfield.SmartLabel labelFor="IDProduct"/>
<sap.ui.comp.smartfield.SmartField id="IDProduct" value="{ProductId}"/>

Note: Using the SmartLabel control on its own is not recommended. Only basic usage is allowed which does not include automatic handling of visibility. If used stand-alone, the application logic must take care of the visibility of the label.


Constructor

Constructor for a new sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField(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
clientSideMandatoryCheck boolean true

Determines if the mandatory check happens on the client side true or on the server side false.

Note: If the sap.ui.comp.smartfield.SmartField#value property of the SmartField control is bound to an Entity Data Model (EDM) property annotated as Nullable="false", the mandatory validation is performed on the client side regardless of the clientSideMandatoryCheck setting.

Example:

    <Property Name="CategoryID" Type="Edm.String" Nullable="false"/>


Since: 1.38.3.

Visibility: public
contextEditable boolean true

Notifies the control whether controls using the SmartField control are editable.

Since: 1.32.0.

Visibility: public
controlContext sap.ui.comp.smartfield.ControlContextType None

Defines the context in which the layout of the SmartField control has to be interpreted.

Since: 1.32.0.

Visibility: public
editable boolean true

Indicates whether the control is in display or edit mode.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

Visibility: public
enabled boolean true

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab order.

Visibility: public
entitySet string empty string

The name of an entity set for which the control manages values. This is an optional property.

If this property is left empty, the entity set is computed by parsing the binding context path, for example, Tasks('id-1428419016778-51') is parsed to Tasks.

Visibility: public
expandNavigationProperties boolean false

Indicates if entities related to navigation properties inside the metadata are requested. If set to true, then these related entities are loaded with an $expand request.

Annotations that can have navigation properties are the following:

  • com.sap.vocabularies.Common.v1.Text for text arrangements
  • Org.OData.Measures.V1.Unit and Org.OData.Measures.V1.ISOCurrency for units
  • com.sap.vocabularies.Common.v1.FieldControl for field control

Note: Independent of the fetchValueListReadOnly value, setting this flag to true requests data from the backend.

Note: The back-end request to expand the navigation properties is sent only if the entity to which SmartField is bound is persisted. For transient entities, there is no back-end request since no such data is available.

Since: 1.48.

Visibility: public
fetchValueListReadOnly boolean true

Indicates whether the value list collection is fetched in display mode from the resource path specified in the com.sap.vocabularies.Common.v1.ValueList annotation.

This collection data is used to infer a descriptive text for the value of the SmartField control. However, fetching the value list collection for every SmartField instance individually may not be ideal in some performance-critical scenarios. To optimize this default behavior, you can set this property to false and provide the com.sap.vocabularies.Common.v1.Text annotation, which is used to specify the URL path name to the Entity Data Model (EDM) property from which the descriptive text for the value of the SmartField control is fetched, for example, LT (Laptop).

Note: Setting this property to false only has an effect if the value property of the SmartField control is bound to an Entity Data Model (EDM) property typed as Edm.String. In addition, applications or frameworks have to make sure the descriptive text is fetched, for example, by expanding a navigation property.

Since: 1.42.0.

Visibility: public
fixedValueListValidationEnabled boolean false

If the property is set to true, a standard validation for sap.m.ComboBox is performed. An inner control sap.m.ComboBox is created and the binding is to selectedKey. Changes at runtime are not reflected.

Note: If the property is set to false, the inner control is sap.ui.comp.smartfield.ComboBox and the binding is to enteredValue. In this case, any entered value is valid irrespective of whether it's in the predefined list or not.

Note: This property is applicable only for fixed-value scenarios.

Since: 1.88.

Visibility: public
historyEnabled boolean true

If the property is set to false, history values are disabled. Changes at runtime are not reflected. The historyEnabled property is not applied to custom controls.

Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the historyEnabled property to true.

Since: 1.84.

Visibility: public
importance sap.ui.comp.smartfield.Importance Low

Specifies the importance of the field. Applicable only when the SmartField is used inside SmartForm.

Since: 1.87.

Visibility: public
jsontype sap.ui.comp.smartfield.JSONType

Data types to be used, if the SmartField control is interacting with a JSON model. If the value property of the control is bound to a property of an OData entity set, this property is not taken into consideration.

Visibility: public
mandatory boolean false

Indicates whether user input is required.

Note: The SmartField control is metadata-driven and this property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property is annotated with the Nullable annotation. The Nullable annotation is a capability of the OData service that specifies whether a value is mandatory, hence it overrules the control's API settings. Therefore, if the Nullable attribute is specified as Nullable="false", a value is mandatory.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

Visibility: public
maxLength int 0

Defines the highest possible number of permitted input characters that the user can enter into the text input field.

Computed maxLength

If the specified maxLength value is greater than the maxLength value specified for the underlying bound Entity Data Model (EDM) property in the service metadata document, the maxLength value of the EDM property takes precedence. Likewise, if the application code provides a binding data type for the value property of the SmartField control and the binding data type has maxLength constraints defined, this maxLength is also taken into consideration to compute the final maxLength value.

Validation Behavior

By design, the SmartField control does not restrict/validate the highest number of permitted input characters for every keystroke, but only when the text input field has changed, and the browser focus leaves the text input field or the ENTER key is pressed. The SmartField control is used more generically in broader contexts, and adding a maxLength attribute to the HTML text input control may break data type formatting in two-way data-binding scenarios. Let's say the maxLength property is set to 3, but the text input control has a formatter function attached to it to format the entered value "DE" to "Germany (DE)". In this case, the formatted value will be truncated by the maxLength setting.

Visibility: public
name string empty string

To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').

Visibility: public
placeholder string empty string

Text shown when no value available.

Visibility: public
proposedControl sap.ui.comp.smartfield.ControlProposalType None

Proposes a control to be rendered. The SmartField control can ignore the proposal.

Since: 1.32.0.

Visibility: public
showLabel boolean true

If set to false the label is not displayed.

Visibility: public
showSuggestion boolean true

If set to true, the suggestion feature for a hosted control is enabled, if the hosted control supports it.

Visibility: public
showValueHelp boolean true

If set to true, a value help indicator will be displayed inside the hosted control, if the hosted control supports this.

Visibility: public
showValueStateMessage boolean true

Defines whether the value state message is shown or not.

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

Horizontal alignment of the text.

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

The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control.

The textDirection property can be used when, for example, the text direction in the application is LTR but you want a specific field to have RTL text direction.

Note: The textDirection property is not applicable for the SmartField control for units of measure use cases.

Since: 1.86.0.

Visibility: public
textInEditModeSource sap.ui.comp.smartfield.TextInEditModeSource None

Sets the source from which text descriptions for IDs are fetched in edit mode, for example, for LT (Laptop).

Note: The sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty and sap.ui.comp.smartfield.TextInEditModeSource.ValueList enumeration members are only supported if the following applies:

  • The value property of the SmartField control instance is bound to an Entity Data Model (EDM) property typed as Edm.String or Edm.Guid.
  • The com.sap.vocabularies.UI.v1.TextArrangement annotation for the bound EDM property or entity type is specified in the service metadata document or annotation file.
  • The binding mode for the value property of the SmartField control is the two-way binding mode.
  • The field from which the description is fetched is filterable.

Note: In addition, the sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty enumeration member is only supported if the following applies:

  • The EDM navigation property association is defined in the service metadata document.
  • The com.sap.vocabularies.Common.v1.Text annotation for the bound EDM property is specified in the service metadata document or annotation file whose Path attribute points to a EDM navigation property of a lookup entity set/type whose single key property is the ID, which contains (among other properties) the descriptive value.
  • The lookup entity must be loaded. The lookup entity can be loaded by expanding the EDM navigation property via a $expand query parameter.
  • The EDM navigation property association defines a referential constraint that ties values of the dependent editable entity type/set to the lookup entity type/set in the service metadata document.
  • The EDM navigation property association end multiplicity of the lookup entity type/set is defined as 1 in the service metadata document. There must be a single-valued navigation from the editable entity set/type to the lookup entity set/type.
  • The lookup entity type/set from which the descriptive value is fetched contains a single-key EDM property.

Note: As of version 1.82, if SmartField is used inside a SmartForm, defaultTextInEditModeSource can be added as custom data to the form and it will be propagated to all smart fields that cover the above criteria. However, if textInEditModeSource is added to the SmartField as property, it will override the defaultTextInEditModeSource propagated from the SmartForm custom data.

Since: 1.83.

Visibility: public
textLabel string empty string

This property contains the text of an associated SmartLabel.

Visibility: public
tooltipLabel string empty string

This property contains the tool tip of the associated SmartLabel control.

Visibility: public
uomEditState int -1

This property is for internal use only.

Since: 1.32.0.

Visibility: public
uomEditable boolean true

Indicates whether the unit of measure field is in display or edit mode.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

Visibility: public
uomEnabled boolean true

Enabled state of the unit, if the SmartField control addresses unit of measure use cases, for example, an amount and its associated currency.

Visibility: public
uomVisible boolean true

Indicates whether the unit of measure field is visible.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this property can be ignored if the bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

Visibility: public
url string empty string

Contains a URL which is used to render a link. The link is rendered, if the OData property, to which the value property of the control is bound, is of type Edm.String and the SmartField is in display mode.

Visibility: public
value any

The binding path expression used to determine the bound Entity Data Model (EDM) property.

Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The SmartField control usually creates its own data type based on the service metadata for the formatting of values. Also, when a custom formatter is specified for a property, the binding mode is automatically switched to one-way binding mode. Note: Named models are not supported, only the default model (named undefined) is supported. For example, when the binding path expression contains a > sign, the string preceding it is a named model and the remainder after the > is the binding path.

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

Visualizes the validation state of the control, e.g. Error, Warning, Success, Information.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Visibility: public
valueStateText string empty string

Defines the text of the value state message popup.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Visibility: public
width sap.ui.core.CSSSize empty string

Defines the width of the control.

Visibility: public
wrapping boolean true

Indicates whether the control break lines (in display mode) to prevent overflow.

Since: 1.36.6.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_ariaLabelInvisibleText 0..n sap.ui.core.InvisibleText

Collects the texts to be used for the ARIA labels.
The InvisibleText controls will be added to the DOM by the SmartField control.

Since: 1.34.2.

_content 0..1 sap.ui.core.Control

The content aggregation is used to hold the control that is hosted by the SmartField control.

configuration 0..1 sap.ui.comp.smartfield.Configuration

Optional configuration for SmartField.

Note: By default, the value of the displayBehaviour property is not evaluated in edit mode. To enable this feature in edit mode, set the textInEditModeSource control property to a non-default value.

controlProposal 0..1 sap.ui.comp.smartfield.ControlProposal

Proposes a control to be rendered. The SmartField control can ignore the proposal.
Deprecated as of version 1.34.0

semanticObjectController 0..1 sap.ui.comp.navpopover.SemanticObjectController

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.


Associations

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

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

Since: 1.96.

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

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

Since: 1.34.2.


Events Overview

Event Description
change

The event is fired after the text in the field has been changed and the focus leaves the field, or after the Enter key has been pressed.

Note: This event is fired even if the value of the text input field is subject to data type constraints and the constraints are violated. Also, the invalid value is not stored in the binding/model.

changeModelValue

Fired after the text in the field has been changed by user interaction in combination with one of the following actions:

  • The focus leaves the field
  • The Enter key is pressed
  • The value is selected from the suggestions list
  • The value is selected from the ValueHelpDialog

If the value of the text input field is subject to data type constraints, the constraints must be fulfilled, which implies the value is stored in the binding/model before the event is fired.

Note: The changeModelValue event is currently experimental and might be redefined.

contextEditableChanged

The event is fired after the context editable property of the control has changed.

Since: 1.32.0.

editableChanged

The event is fired after the value of editable property of the control has changed.

Since: 1.30.0.

entitySetFound

The OData entity set is either derived from the control's binding context or from control's entity set property, if a value for it is specified. In both cases this event is fired.

initialise

The event is fired after the smart field has calculated its metadata.

innerControlsCreated

The event is fired after the inner controls have been created.

press

Fires when the user triggers the link control or taps/clicks on an active title of the object identifier control.

Since: 1.36.0.

valueListChanged

The event is fired when after selection of values with value help or auto-suggest, the model is updated with the selected data.

Since: 1.31.0.

visibleChanged

The event is fired after the visibility of the control has changed.

change

The event is fired after the text in the field has been changed and the focus leaves the field, or after the Enter key has been pressed.

Note: This event is fired even if the value of the text input field is subject to data type constraints and the constraints are violated. Also, the invalid value is not stored in the binding/model.

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

The current value inside the text field

Note: This value is the formatted value, and in some cases it might differ from the value stored in the binding/model. Usually, the value that is sent to the back-end system should be the value stored in the binding/model, which is the parsed and validated value.

newValue string

The new value inside the text field

changeModelValue

Fired after the text in the field has been changed by user interaction in combination with one of the following actions:

If the value of the text input field is subject to data type constraints, the constraints must be fulfilled, which implies the value is stored in the binding/model before the event is fired.

Note: The changeModelValue event is currently experimental and might be redefined.

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

Indicates whether the field quantity field has changed

valueLastValueState boolean

Last value of the valueState property of the field quantity field

unitChanged boolean

Indicates whether the field unit field has changed

unitLastValueState sap.ui.core.ValueState

Last value of the valueState property of the field unit field

contextEditableChanged

The event is fired after the context editable property of the control has changed.

Since: 1.32.0.

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

The value of the context editable property of the control

editableChanged

The event is fired after the value of editable property of the control has changed.

Since: 1.30.0.

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

If true, the control is in edit mode

entitySetFound

The OData entity set is either derived from the control's binding context or from control's entity set property, if a value for it is specified. In both cases this event is fired.

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

The path to the found entity set

initialise

The event is fired after the smart field has calculated its metadata.

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

innerControlsCreated

The event is fired after the inner controls have been created.

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

press

Fires when the user triggers the link control or taps/clicks on an active title of the object identifier control.

Since: 1.36.0.

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

valueListChanged

The event is fired when after selection of values with value help or auto-suggest, the model is updated with the selected data.

Since: 1.31.0.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
changes sap.ui.core.Control[]

An array of selected values

visibleChanged

The event is fired after the visibility of the control has changed.

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

If true, the control is visible


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the text in the field has been changed and the focus leaves the field, or after the Enter key has been pressed.

Note: This event is fired even if the value of the text input field is subject to data type constraints and the constraints are violated. Also, the invalid value is not stored in the binding/model.

attachChangeModelValue

Attaches event handler fnFunction to the changeModelValue event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

Fired after the text in the field has been changed by user interaction in combination with one of the following actions:

  • The focus leaves the field
  • The Enter key is pressed
  • The value is selected from the suggestions list
  • The value is selected from the ValueHelpDialog

If the value of the text input field is subject to data type constraints, the constraints must be fulfilled, which implies the value is stored in the binding/model before the event is fired.

Note: The changeModelValue event is currently experimental and might be redefined.

attachContextEditableChanged

Attaches event handler fnFunction to the contextEditableChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the context editable property of the control has changed.

attachEditableChanged

Attaches event handler fnFunction to the editableChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the value of editable property of the control has changed.

attachEntitySetFound

Attaches event handler fnFunction to the entitySetFound event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The OData entity set is either derived from the control's binding context or from control's entity set property, if a value for it is specified. In both cases this event is fired.

attachInitialise

Attaches event handler fnFunction to the initialise event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the smart field has calculated its metadata.

attachInnerControlsCreated

Attaches event handler fnFunction to the innerControlsCreated event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the inner controls have been created.

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

Fires when the user triggers the link control or taps/clicks on an active title of the object identifier control.

attachValueListChanged

Attaches event handler fnFunction to the valueListChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired when after selection of values with value help or auto-suggest, the model is updated with the selected data.

attachVisibleChanged

Attaches event handler fnFunction to the visibleChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the visibility of the control has changed.

checkClientError

Checks whether a client error has been detected in edit mode. Additionally the error message is shown, if this is not the case already.

This method is typically used to check whether the value of every inner text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

  • The Nullable constraint for an EDM property typed as Edm.String is violated.
  • A user input is invalid for the bound EDM property typed as Edm.DateTime.

If this happens, the following applies:

  • A validation error state is set on the text input field.
  • A validation error message is displayed for the text input field.
  • The validation error message (possibly generated by a user input) is added to a sap.ui.core.message.MessageManager object instance if, for example, a view object instance is registered to it.
  • The inner private text input field fires a sap.ui.base.EventProvider#event:validationError, or sap.ui.base.EventProvider#event:parseError event.

Since 1.64 replaced by {@link sap.ui.comp.smartfield.SmartField#checkValuesValidity}
checkUnitValidity

Checks the validity of the values for the given control.

checkValuesValidity

Checks whether the value of every inner text input field in edit mode is valid.

This method is typically used to check whether the value of every inner text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

Note: In some scenarios, invoking this method may also trigger a back-end request to check whether the value is valid.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

  • The Nullable constraint for an EDM property typed as Edm.String is violated.
  • A user input is invalid for the bound EDM property typed as Edm.DateTime.

If this happens, the following applies:

  • A validation error state is set on the text input field.
  • A validation error message is displayed for the text input field.
  • The validation error message (possibly generated by a user input) is added to a sap.ui.core.message.MessageManager object instance if, for example, a view object instance is registered to it.
  • The inner private text input field fires a sap.ui.base.EventProvider#event:validationError, or sap.ui.base.EventProvider#event:parseError event. Note that the events are fired synchronously if the value is validated on client side or asynchronously if, for example, the value is validated on back-end side.

The inner private text input field fires a sap.ui.base.EventProvider#event:validationSuccess if its validation passes.

Note: In display mode, this method always returns a fulfilled Promise object.

Note: In two-way data binding scenarios, it is usually not necessary to invoke this method explicitly to validate user input, as the data type validation is done automatically when the value in the input field has changed and the focus leaves the text input field or the enter key is pressed. However, in two-way data binding scenarios, this method may be used to check whether a value is valid before submitting it to the back-end system.

destroyConfiguration

Destroys the configuration in the aggregation configuration.

destroyControlProposal

Destroys the controlProposal in the aggregation controlProposal.

destroySemanticObjectController

Destroys the semanticObjectController in the aggregation semanticObjectController.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.comp.smartfield.SmartField.

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

detachChangeModelValue

Detaches event handler fnFunction from the changeModelValue event of this sap.ui.comp.smartfield.SmartField.

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

detachContextEditableChanged

Detaches event handler fnFunction from the contextEditableChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachEditableChanged

Detaches event handler fnFunction from the editableChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachEntitySetFound

Detaches event handler fnFunction from the entitySetFound event of this sap.ui.comp.smartfield.SmartField.

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

detachInitialise

Detaches event handler fnFunction from the initialise event of this sap.ui.comp.smartfield.SmartField.

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

detachInnerControlsCreated

Detaches event handler fnFunction from the innerControlsCreated event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField.

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

detachValueListChanged

Detaches event handler fnFunction from the valueListChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachVisibleChanged

Detaches event handler fnFunction from the visibleChanged event of this sap.ui.comp.smartfield.SmartField.

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

sap.ui.comp.smartfield.SmartField.extend

Creates a new subclass of class sap.ui.comp.smartfield.SmartField 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.

fireChange

Fires event change to attached listeners.

fireChangeModelValue

Fires event changeModelValue to attached listeners.

fireContextEditableChanged

Fires event contextEditableChanged to attached listeners.

fireEditableChanged

Fires event editableChanged to attached listeners.

fireEntitySetFound

Fires event entitySetFound to attached listeners.

fireInitialise

Fires event initialise to attached listeners.

fireInnerControlsCreated

Fires event innerControlsCreated to attached listeners.

firePress

Fires event press to attached listeners.

fireValueListChanged

Fires event valueListChanged to attached listeners.

fireVisibleChanged

Fires event visibleChanged 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.

getClientSideMandatoryCheck

Gets current value of property clientSideMandatoryCheck.

Determines if the mandatory check happens on the client side true or on the server side false.

Note: If the sap.ui.comp.smartfield.SmartField#value property of the SmartField control is bound to an Entity Data Model (EDM) property annotated as Nullable="false", the mandatory validation is performed on the client side regardless of the clientSideMandatoryCheck setting.

Example:

    <Property Name="CategoryID" Type="Edm.String" Nullable="false"/>

Default value is true.

getComputedTextLabel
getConfiguration

Gets content of aggregation configuration.

Optional configuration for SmartField.

Note: By default, the value of the displayBehaviour property is not evaluated in edit mode. To enable this feature in edit mode, set the textInEditModeSource control property to a non-default value.

getContextEditable

Gets current value of property contextEditable.

Notifies the control whether controls using the SmartField control are editable.

Default value is true.

getControlContext

Gets current value of property controlContext.

Defines the context in which the layout of the SmartField control has to be interpreted.

Default value is None.

getControlProposal

Gets content of aggregation controlProposal.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

getDataProperty

Returns the OData property to which the value property of the control is bound.

getDataSourceLabel

Returns the label computed from the SmartField annotations if available

getDataType

Returns the EDM data type of the OData property to which the value property of the control is bound. If no model or no OData property is available null is returned.

getEditable

Gets current value of property editable.

Indicates whether the control is in display or edit mode.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

Default value is true.

getEnabled

Gets current value of property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab order.

Default value is true.

getEntitySet

Gets current value of property entitySet.

The name of an entity set for which the control manages values. This is an optional property.

If this property is left empty, the entity set is computed by parsing the binding context path, for example, Tasks('id-1428419016778-51') is parsed to Tasks.

Default value is empty string.

getExpandNavigationProperties

Gets current value of property expandNavigationProperties.

Indicates if entities related to navigation properties inside the metadata are requested. If set to true, then these related entities are loaded with an $expand request.

Annotations that can have navigation properties are the following:

  • com.sap.vocabularies.Common.v1.Text for text arrangements
  • Org.OData.Measures.V1.Unit and Org.OData.Measures.V1.ISOCurrency for units
  • com.sap.vocabularies.Common.v1.FieldControl for field control

Note: Independent of the fetchValueListReadOnly value, setting this flag to true requests data from the backend.

Note: The back-end request to expand the navigation properties is sent only if the entity to which SmartField is bound is persisted. For transient entities, there is no back-end request since no such data is available.

Default value is false.

getFetchValueListReadOnly

Gets current value of property fetchValueListReadOnly.

Indicates whether the value list collection is fetched in display mode from the resource path specified in the com.sap.vocabularies.Common.v1.ValueList annotation.

This collection data is used to infer a descriptive text for the value of the SmartField control. However, fetching the value list collection for every SmartField instance individually may not be ideal in some performance-critical scenarios. To optimize this default behavior, you can set this property to false and provide the com.sap.vocabularies.Common.v1.Text annotation, which is used to specify the URL path name to the Entity Data Model (EDM) property from which the descriptive text for the value of the SmartField control is fetched, for example, LT (Laptop).

Note: Setting this property to false only has an effect if the value property of the SmartField control is bound to an Entity Data Model (EDM) property typed as Edm.String. In addition, applications or frameworks have to make sure the descriptive text is fetched, for example, by expanding a navigation property.

Default value is true.

getFixedValueListValidationEnabled

Gets current value of property fixedValueListValidationEnabled.

If the property is set to true, a standard validation for sap.m.ComboBox is performed. An inner control sap.m.ComboBox is created and the binding is to selectedKey. Changes at runtime are not reflected.

Note: If the property is set to false, the inner control is sap.ui.comp.smartfield.ComboBox and the binding is to enteredValue. In this case, any entered value is valid irrespective of whether it's in the predefined list or not.

Note: This property is applicable only for fixed-value scenarios.

Default value is false.

getFocusDomRef

Returns the DOM element that gets the focus.

getFormFormattedValue

Returns the formatted value of a control used in a SemanticFormElement.

getFormValueProperty

Returns the name of the value-holding property of a control used in a SemanticFormElement.

getHistoryEnabled

Gets current value of property historyEnabled.

If the property is set to false, history values are disabled. Changes at runtime are not reflected. The historyEnabled property is not applied to custom controls.

Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the historyEnabled property to true.

Default value is true.

getIdForLabel

Gets the ID of the control to which the label should point.

getImportance

Gets current value of property importance.

Specifies the importance of the field. Applicable only when the SmartField is used inside SmartForm.

Default value is Low.

getInnerControls

Resolves the controls hosted currently by this SmartField control.

getJsontype

Gets current value of property jsontype.

Data types to be used, if the SmartField control is interacting with a JSON model. If the value property of the control is bound to a property of an OData entity set, this property is not taken into consideration.

getMandatory

Gets current value of property mandatory.

Indicates whether user input is required.

Note: The SmartField control is metadata-driven and this property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property is annotated with the Nullable annotation. The Nullable annotation is a capability of the OData service that specifies whether a value is mandatory, hence it overrules the control's API settings. Therefore, if the Nullable attribute is specified as Nullable="false", a value is mandatory.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

Default value is false.

getMaxLength

Gets current value of property maxLength.

Defines the highest possible number of permitted input characters that the user can enter into the text input field.

Computed maxLength

If the specified maxLength value is greater than the maxLength value specified for the underlying bound Entity Data Model (EDM) property in the service metadata document, the maxLength value of the EDM property takes precedence. Likewise, if the application code provides a binding data type for the value property of the SmartField control and the binding data type has maxLength constraints defined, this maxLength is also taken into consideration to compute the final maxLength value.

Validation Behavior

By design, the SmartField control does not restrict/validate the highest number of permitted input characters for every keystroke, but only when the text input field has changed, and the browser focus leaves the text input field or the ENTER key is pressed. The SmartField control is used more generically in broader contexts, and adding a maxLength attribute to the HTML text input control may break data type formatting in two-way data-binding scenarios. Let's say the maxLength property is set to 3, but the text input control has a formatter function attached to it to format the entered value "DE" to "Germany (DE)". In this case, the formatted value will be truncated by the maxLength setting.

Default value is 0.

sap.ui.comp.smartfield.SmartField.getMetadata

Returns a metadata object for class sap.ui.comp.smartfield.SmartField.

getMode

Returns the current SmartField's edit mode

getName

Gets current value of property name.

To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').

Default value is empty string.

getPlaceholder

Gets current value of property placeholder.

Text shown when no value available.

Default value is empty string.

getProposedControl

Gets current value of property proposedControl.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

Default value is None.

getRequired

Gets the value of the mandatory property.

This function is needed as the "mandatory" feature is named "required" in a lot of other controls (like Label or Form).

getSemanticObjectController

Gets content of aggregation semanticObjectController.

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.

getShowLabel

Gets current value of property showLabel.

If set to false the label is not displayed.

Default value is true.

getShowSuggestion

Gets current value of property showSuggestion.

If set to true, the suggestion feature for a hosted control is enabled, if the hosted control supports it.

Default value is true.

getShowValueHelp

Gets current value of property showValueHelp.

If set to true, a value help indicator will be displayed inside the hosted control, if the hosted control supports this.

Default value is true.

getShowValueStateMessage

Gets current value of property showValueStateMessage.

Defines whether the value state message is shown or not.

Default value is true.

sap.ui.comp.smartfield.SmartField.getSupportedAnnotationPaths

Calculates the paths to the annotations used by the SmartField control.

getTextAlign

Gets current value of property textAlign.

Horizontal alignment of the text.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control.

The textDirection property can be used when, for example, the text direction in the application is LTR but you want a specific field to have RTL text direction.

Note: The textDirection property is not applicable for the SmartField control for units of measure use cases.

Default value is Inherit.

getTextInEditModeSource

Gets current value of property textInEditModeSource.

Sets the source from which text descriptions for IDs are fetched in edit mode, for example, for LT (Laptop).

Note: The sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty and sap.ui.comp.smartfield.TextInEditModeSource.ValueList enumeration members are only supported if the following applies:

  • The value property of the SmartField control instance is bound to an Entity Data Model (EDM) property typed as Edm.String or Edm.Guid.
  • The com.sap.vocabularies.UI.v1.TextArrangement annotation for the bound EDM property or entity type is specified in the service metadata document or annotation file.
  • The binding mode for the value property of the SmartField control is the two-way binding mode.
  • The field from which the description is fetched is filterable.

Note: In addition, the sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty enumeration member is only supported if the following applies:

  • The EDM navigation property association is defined in the service metadata document.
  • The com.sap.vocabularies.Common.v1.Text annotation for the bound EDM property is specified in the service metadata document or annotation file whose Path attribute points to a EDM navigation property of a lookup entity set/type whose single key property is the ID, which contains (among other properties) the descriptive value.
  • The lookup entity must be loaded. The lookup entity can be loaded by expanding the EDM navigation property via a $expand query parameter.
  • The EDM navigation property association defines a referential constraint that ties values of the dependent editable entity type/set to the lookup entity type/set in the service metadata document.
  • The EDM navigation property association end multiplicity of the lookup entity type/set is defined as 1 in the service metadata document. There must be a single-valued navigation from the editable entity set/type to the lookup entity set/type.
  • The lookup entity type/set from which the descriptive value is fetched contains a single-key EDM property.

Note: As of version 1.82, if SmartField is used inside a SmartForm, defaultTextInEditModeSource can be added as custom data to the form and it will be propagated to all smart fields that cover the above criteria. However, if textInEditModeSource is added to the SmartField as property, it will override the defaultTextInEditModeSource propagated from the SmartForm custom data.

Default value is None.

getTextLabel

Gets current value of property textLabel.

This property contains the text of an associated SmartLabel.

Default value is empty string.

getTooltipLabel

Gets current value of property tooltipLabel.

This property contains the tool tip of the associated SmartLabel control.

Default value is empty string.

getUnitOfMeasure

If the OData property to which the control's value property is bound semantically represents a unit of measure, the value of the current unit of measure is returned. Otherwise null is returned.

getUomEditable

Gets current value of property uomEditable.

Indicates whether the unit of measure field is in display or edit mode.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

Default value is true.

getUomEditState

Gets current value of property uomEditState.

This property is for internal use only.

Default value is -1.

getUomEnabled

Gets current value of property uomEnabled.

Enabled state of the unit, if the SmartField control addresses unit of measure use cases, for example, an amount and its associated currency.

Default value is true.

getUomVisible

Gets current value of property uomVisible.

Indicates whether the unit of measure field is visible.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this property can be ignored if the bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

Default value is true.

getUrl

Gets current value of property url.

Contains a URL which is used to render a link. The link is rendered, if the OData property, to which the value property of the control is bound, is of type Edm.String and the SmartField is in display mode.

Default value is empty string.

getValue

Gets current value of property value.

The binding path expression used to determine the bound Entity Data Model (EDM) property.

Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The SmartField control usually creates its own data type based on the service metadata for the formatting of values. Also, when a custom formatter is specified for a property, the binding mode is automatically switched to one-way binding mode. Note: Named models are not supported, only the default model (named undefined) is supported. For example, when the binding path expression contains a > sign, the string preceding it is a named model and the remainder after the > is the binding path.

getValueState

Gets current value of property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success, Information.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text of the value state message popup.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Default value is empty string.

getWidth

Gets current value of property width.

Defines the width of the control.

Default value is empty string.

getWrapping

Gets current value of property wrapping.

Indicates whether the control break lines (in display mode) to prevent overflow.

Default value is true.

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.

setClientSideMandatoryCheck

Sets a new value for property clientSideMandatoryCheck.

Determines if the mandatory check happens on the client side true or on the server side false.

Note: If the sap.ui.comp.smartfield.SmartField#value property of the SmartField control is bound to an Entity Data Model (EDM) property annotated as Nullable="false", the mandatory validation is performed on the client side regardless of the clientSideMandatoryCheck setting.

Example:

    <Property Name="CategoryID" Type="Edm.String" Nullable="false"/>

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

Default value is true.

setConfiguration

Sets the aggregated configuration.

setContextEditable

Sets a new value for property contextEditable.

Notifies the control whether controls using the SmartField control are editable.

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

Default value is true.

setControlContext

Sets a new value for property controlContext.

Defines the context in which the layout of the SmartField control has to be interpreted.

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

Default value is None.

setControlProposal

Sets the aggregated controlProposal.

setEditable

Sets a new value for property editable.

Indicates whether the control is in display or edit mode.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

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

Default value is true.

setEnabled

Sets a new value for property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab order.

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

Default value is true.

setEntitySet

Sets a new value for property entitySet.

The name of an entity set for which the control manages values. This is an optional property.

If this property is left empty, the entity set is computed by parsing the binding context path, for example, Tasks('id-1428419016778-51') is parsed to Tasks.

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

Default value is empty string.

setExpandNavigationProperties

Sets a new value for property expandNavigationProperties.

Indicates if entities related to navigation properties inside the metadata are requested. If set to true, then these related entities are loaded with an $expand request.

Annotations that can have navigation properties are the following:

  • com.sap.vocabularies.Common.v1.Text for text arrangements
  • Org.OData.Measures.V1.Unit and Org.OData.Measures.V1.ISOCurrency for units
  • com.sap.vocabularies.Common.v1.FieldControl for field control

Note: Independent of the fetchValueListReadOnly value, setting this flag to true requests data from the backend.

Note: The back-end request to expand the navigation properties is sent only if the entity to which SmartField is bound is persisted. For transient entities, there is no back-end request since no such data is available.

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

Default value is false.

setFetchValueListReadOnly

Sets a new value for property fetchValueListReadOnly.

Indicates whether the value list collection is fetched in display mode from the resource path specified in the com.sap.vocabularies.Common.v1.ValueList annotation.

This collection data is used to infer a descriptive text for the value of the SmartField control. However, fetching the value list collection for every SmartField instance individually may not be ideal in some performance-critical scenarios. To optimize this default behavior, you can set this property to false and provide the com.sap.vocabularies.Common.v1.Text annotation, which is used to specify the URL path name to the Entity Data Model (EDM) property from which the descriptive text for the value of the SmartField control is fetched, for example, LT (Laptop).

Note: Setting this property to false only has an effect if the value property of the SmartField control is bound to an Entity Data Model (EDM) property typed as Edm.String. In addition, applications or frameworks have to make sure the descriptive text is fetched, for example, by expanding a navigation property.

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

Default value is true.

setFixedValueListValidationEnabled

Sets a new value for property fixedValueListValidationEnabled.

If the property is set to true, a standard validation for sap.m.ComboBox is performed. An inner control sap.m.ComboBox is created and the binding is to selectedKey. Changes at runtime are not reflected.

Note: If the property is set to false, the inner control is sap.ui.comp.smartfield.ComboBox and the binding is to enteredValue. In this case, any entered value is valid irrespective of whether it's in the predefined list or not.

Note: This property is applicable only for fixed-value scenarios.

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

Default value is false.

setHistoryEnabled

Sets a new value for property historyEnabled.

If the property is set to false, history values are disabled. Changes at runtime are not reflected. The historyEnabled property is not applied to custom controls.

Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the historyEnabled property to true.

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

Default value is true.

setImportance

Sets a new value for property importance.

Specifies the importance of the field. Applicable only when the SmartField is used inside SmartForm.

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

Default value is Low.

setJsontype

Sets a new value for property jsontype.

Data types to be used, if the SmartField control is interacting with a JSON model. If the value property of the control is bound to a property of an OData entity set, this property is not taken into consideration.

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

setMandatory

Sets a new value for property mandatory.

Indicates whether user input is required.

Note: The SmartField control is metadata-driven and this property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property is annotated with the Nullable annotation. The Nullable annotation is a capability of the OData service that specifies whether a value is mandatory, hence it overrules the control's API settings. Therefore, if the Nullable attribute is specified as Nullable="false", a value is mandatory.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

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.

Defines the highest possible number of permitted input characters that the user can enter into the text input field.

Computed maxLength

If the specified maxLength value is greater than the maxLength value specified for the underlying bound Entity Data Model (EDM) property in the service metadata document, the maxLength value of the EDM property takes precedence. Likewise, if the application code provides a binding data type for the value property of the SmartField control and the binding data type has maxLength constraints defined, this maxLength is also taken into consideration to compute the final maxLength value.

Validation Behavior

By design, the SmartField control does not restrict/validate the highest number of permitted input characters for every keystroke, but only when the text input field has changed, and the browser focus leaves the text input field or the ENTER key is pressed. The SmartField control is used more generically in broader contexts, and adding a maxLength attribute to the HTML text input control may break data type formatting in two-way data-binding scenarios. Let's say the maxLength property is set to 3, but the text input control has a formatter function attached to it to format the entered value "DE" to "Germany (DE)". In this case, the formatted value will be truncated by the maxLength setting.

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

Default value is 0.

setName

Sets a new value for property name.

To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').

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

Default value is empty string.

setPlaceholder

Sets a new value for property placeholder.

Text shown when no value available.

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

Default value is empty string.

setProposedControl

Sets a new value for property proposedControl.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

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

Default value is None.

setSemanticObjectController

Sets the aggregated semanticObjectController.

setShowLabel

Sets a new value for property showLabel.

If set to false the label is not displayed.

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

Default value is true.

setShowSuggestion

Sets a new value for property showSuggestion.

If set to true, the suggestion feature for a hosted control is enabled, if the hosted control supports it.

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

Default value is true.

setShowValueHelp

Sets a new value for property showValueHelp.

If set to true, a value help indicator will be displayed inside the hosted control, if the hosted control supports this.

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

Default value is true.

setShowValueStateMessage

Sets a new value for property showValueStateMessage.

Defines whether the value state message is shown or not.

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

Default value is true.

setTextAlign

Sets a new value for property textAlign.

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

setTextDirection

Sets a new value for property textDirection.

The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control.

The textDirection property can be used when, for example, the text direction in the application is LTR but you want a specific field to have RTL text direction.

Note: The textDirection property is not applicable for the SmartField control for units of measure use cases.

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

Default value is Inherit.

setTextInEditModeSource

Sets a new value for property textInEditModeSource.

Sets the source from which text descriptions for IDs are fetched in edit mode, for example, for LT (Laptop).

Note: The sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty and sap.ui.comp.smartfield.TextInEditModeSource.ValueList enumeration members are only supported if the following applies:

  • The value property of the SmartField control instance is bound to an Entity Data Model (EDM) property typed as Edm.String or Edm.Guid.
  • The com.sap.vocabularies.UI.v1.TextArrangement annotation for the bound EDM property or entity type is specified in the service metadata document or annotation file.
  • The binding mode for the value property of the SmartField control is the two-way binding mode.
  • The field from which the description is fetched is filterable.

Note: In addition, the sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty enumeration member is only supported if the following applies:

  • The EDM navigation property association is defined in the service metadata document.
  • The com.sap.vocabularies.Common.v1.Text annotation for the bound EDM property is specified in the service metadata document or annotation file whose Path attribute points to a EDM navigation property of a lookup entity set/type whose single key property is the ID, which contains (among other properties) the descriptive value.
  • The lookup entity must be loaded. The lookup entity can be loaded by expanding the EDM navigation property via a $expand query parameter.
  • The EDM navigation property association defines a referential constraint that ties values of the dependent editable entity type/set to the lookup entity type/set in the service metadata document.
  • The EDM navigation property association end multiplicity of the lookup entity type/set is defined as 1 in the service metadata document. There must be a single-valued navigation from the editable entity set/type to the lookup entity set/type.
  • The lookup entity type/set from which the descriptive value is fetched contains a single-key EDM property.

Note: As of version 1.82, if SmartField is used inside a SmartForm, defaultTextInEditModeSource can be added as custom data to the form and it will be propagated to all smart fields that cover the above criteria. However, if textInEditModeSource is added to the SmartField as property, it will override the defaultTextInEditModeSource propagated from the SmartForm custom data.

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

Default value is None.

setTextLabel

Sets a new value for property textLabel.

This property contains the text of an associated SmartLabel.

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

Default value is empty string.

setTooltipLabel

Sets a new value for property tooltipLabel.

This property contains the tool tip of the associated SmartLabel control.

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

Default value is empty string.

setUnitOfMeasure

If the OData property the control's value property is bound to semantically represents a unit of measure, the value of the current unit of measure can be changed.

setUomEditable

Sets a new value for property uomEditable.

Indicates whether the unit of measure field is in display or edit mode.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:updatable annotation.
  • The bound EDM property or its entity set are annotated with the sap:creatable annotation.
  • The entity set of the bound EDM property is annotated with the OData V2 sap:updatable-path annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.InsertRestrictions annotation.
  • The bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Capabilities.V1.UpdateRestrictions annotation.

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

Default value is true.

setUomEnabled

Sets a new value for property uomEnabled.

Enabled state of the unit, if the SmartField control addresses unit of measure use cases, for example, an amount and its associated currency.

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

Default value is true.

setUomVisible

Sets a new value for property uomVisible.

Indicates whether the unit of measure field is visible.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

  • The bound Entity Data Model (EDM) property or its entity set are annotated with the OData V2 sap:unit annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.ISOCurrency annotation.
  • The entity set of the bound EDM property is annotated with the OData V4 Org.OData.Measures.V1.Unit annotation.

Note: The SmartField control is metadata-driven, and this property can be ignored if the bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

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

Default value is true.

setUrl

Setter for property url. Default value is null.

setValue

Sets a new value for property value.

The binding path expression used to determine the bound Entity Data Model (EDM) property.

Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The SmartField control usually creates its own data type based on the service metadata for the formatting of values. Also, when a custom formatter is specified for a property, the binding mode is automatically switched to one-way binding mode. Note: Named models are not supported, only the default model (named undefined) is supported. For example, when the binding path expression contains a > sign, the string preceding it is a named model and the remainder after the > is the binding path.

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

setValueState

Setter for property valueState. Default value is None.

setValueStateText

Setter for property valueStateText. Default value is empty/undefined.

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.

Default value is empty string.

setWrapping

Sets a new value for property wrapping.

Indicates whether the control break lines (in display mode) to prevent overflow.

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

Default value is true.

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

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the text in the field has been changed and the focus leaves the field, or after the Enter key has been pressed.

Note: This event is fired even if the value of the text input field is subject to data type constraints and the constraints are violated. Also, the invalid value is not stored in the binding/model.

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.comp.smartfield.SmartField itself

attachChangeModelValue

Attaches event handler fnFunction to the changeModelValue event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

Fired after the text in the field has been changed by user interaction in combination with one of the following actions:

If the value of the text input field is subject to data type constraints, the constraints must be fulfilled, which implies the value is stored in the binding/model before the event is fired.

Note: The changeModelValue event is currently experimental and might be redefined.

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.comp.smartfield.SmartField itself

attachContextEditableChanged

Attaches event handler fnFunction to the contextEditableChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the context editable property of the control has changed.

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.comp.smartfield.SmartField itself

attachEditableChanged

Attaches event handler fnFunction to the editableChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the value of editable property of the control has changed.

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.comp.smartfield.SmartField itself

attachEntitySetFound

Attaches event handler fnFunction to the entitySetFound event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The OData entity set is either derived from the control's binding context or from control's entity set property, if a value for it is specified. In both cases this event 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.comp.smartfield.SmartField itself

attachInitialise

Attaches event handler fnFunction to the initialise event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the smart field has calculated its metadata.

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.comp.smartfield.SmartField itself

attachInnerControlsCreated

Attaches event handler fnFunction to the innerControlsCreated event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the inner controls have been created.

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.comp.smartfield.SmartField itself

attachPress

Attaches event handler fnFunction to the press event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

Fires when the user triggers the link control or taps/clicks on an active title of the object identifier control.

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.comp.smartfield.SmartField itself

attachValueListChanged

Attaches event handler fnFunction to the valueListChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired when after selection of values with value help or auto-suggest, the model is updated with the selected data.

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.comp.smartfield.SmartField itself

attachVisibleChanged

Attaches event handler fnFunction to the visibleChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField itself.

The event is fired after the visibility of the control has changed.

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.comp.smartfield.SmartField itself

checkClientError

Checks whether a client error has been detected in edit mode. Additionally the error message is shown, if this is not the case already.

This method is typically used to check whether the value of every inner text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

If this happens, the following applies:

Since 1.64 replaced by {@link sap.ui.comp.smartfield.SmartField#checkValuesValidity}
Param Type DefaultValue Description
oSettings object

Settings

handleSuccess boolean false

Indicates whether client error checks are performed for the current value regardless of the current error state of the control. If the handleSuccess setting is set to true, the text input field fires a sap.ui.base.EventProvider#event:validationSuccess if its validation passes.

checkUnitValidity

Checks the validity of the values for the given control.

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

The control to be checked

oSettings object

Additional settings

checkValuesValidity

Checks whether the value of every inner text input field in edit mode is valid.

This method is typically used to check whether the value of every inner text input field in edit mode is subject to data type constraints and whether the constraints are fulfilled.

Note: In some scenarios, invoking this method may also trigger a back-end request to check whether the value is valid.

A data type constraint for a bound Entity Data Model (EDM) property can be violated in many ways, for example:

If this happens, the following applies:

The inner private text input field fires a sap.ui.base.EventProvider#event:validationSuccess if its validation passes.

Note: In display mode, this method always returns a fulfilled Promise object.

Note: In two-way data binding scenarios, it is usually not necessary to invoke this method explicitly to validate user input, as the data type validation is done automatically when the value in the input field has changed and the focus leaves the text input field or the enter key is pressed. However, in two-way data binding scenarios, this method may be used to check whether a value is valid before submitting it to the back-end system.

destroyConfiguration

Destroys the configuration in the aggregation configuration.

destroyControlProposal

Destroys the controlProposal in the aggregation controlProposal.

destroySemanticObjectController

Destroys the semanticObjectController in the aggregation semanticObjectController.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.comp.smartfield.SmartField.

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

detachChangeModelValue

Detaches event handler fnFunction from the changeModelValue event of this sap.ui.comp.smartfield.SmartField.

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

detachContextEditableChanged

Detaches event handler fnFunction from the contextEditableChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachEditableChanged

Detaches event handler fnFunction from the editableChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachEntitySetFound

Detaches event handler fnFunction from the entitySetFound event of this sap.ui.comp.smartfield.SmartField.

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

detachInitialise

Detaches event handler fnFunction from the initialise event of this sap.ui.comp.smartfield.SmartField.

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

detachInnerControlsCreated

Detaches event handler fnFunction from the innerControlsCreated event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField.

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

detachValueListChanged

Detaches event handler fnFunction from the valueListChanged event of this sap.ui.comp.smartfield.SmartField.

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

detachVisibleChanged

Detaches event handler fnFunction from the visibleChanged event of this sap.ui.comp.smartfield.SmartField.

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.comp.smartfield.SmartField.extend

Creates a new subclass of class sap.ui.comp.smartfield.SmartField 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

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The current value inside the text field

Note: This value is the formatted value, and in some cases it might differ from the value stored in the binding/model. Usually, the value that is sent to the back-end system should be the value stored in the binding/model, which is the parsed and validated value.

newValue string

The new value inside the text field

fireChangeModelValue

Fires event changeModelValue to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

valueChanged boolean

Indicates whether the field quantity field has changed

valueLastValueState boolean

Last value of the valueState property of the field quantity field

unitChanged boolean

Indicates whether the field unit field has changed

unitLastValueState sap.ui.core.ValueState

Last value of the valueState property of the field unit field

fireContextEditableChanged

Fires event contextEditableChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

editable boolean

The value of the context editable property of the control

fireEditableChanged

Fires event editableChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

editable boolean

If true, the control is in edit mode

fireEntitySetFound

Fires event entitySetFound to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

entitySet string

The path to the found entity set

fireInitialise

Fires event initialise to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireInnerControlsCreated

Fires event innerControlsCreated to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireValueListChanged

Fires event valueListChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

changes sap.ui.core.Control[]

An array of selected values

fireVisibleChanged

Fires event visibleChanged to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

visible boolean

If true, the control is visible

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.

getClientSideMandatoryCheck

Gets current value of property clientSideMandatoryCheck.

Determines if the mandatory check happens on the client side true or on the server side false.

Note: If the sap.ui.comp.smartfield.SmartField#value property of the SmartField control is bound to an Entity Data Model (EDM) property annotated as Nullable="false", the mandatory validation is performed on the client side regardless of the clientSideMandatoryCheck setting.

Example:

    <Property Name="CategoryID" Type="Edm.String" Nullable="false"/>

Default value is true.

getComputedTextLabel

getConfiguration

Gets content of aggregation configuration.

Optional configuration for SmartField.

Note: By default, the value of the displayBehaviour property is not evaluated in edit mode. To enable this feature in edit mode, set the textInEditModeSource control property to a non-default value.

getContextEditable

Gets current value of property contextEditable.

Notifies the control whether controls using the SmartField control are editable.

Default value is true.

getControlContext

Gets current value of property controlContext.

Defines the context in which the layout of the SmartField control has to be interpreted.

Default value is None.

getControlProposal

Gets content of aggregation controlProposal.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

getDataProperty

Returns the OData property to which the value property of the control is bound.

getDataSourceLabel

Returns the label computed from the SmartField annotations if available

getDataType

Returns the EDM data type of the OData property to which the value property of the control is bound. If no model or no OData property is available null is returned.

getEditable

Gets current value of property editable.

Indicates whether the control is in display or edit mode.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

Default value is true.

getEnabled

Gets current value of property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab order.

Default value is true.

getEntitySet

Gets current value of property entitySet.

The name of an entity set for which the control manages values. This is an optional property.

If this property is left empty, the entity set is computed by parsing the binding context path, for example, Tasks('id-1428419016778-51') is parsed to Tasks.

Default value is empty string.

getExpandNavigationProperties

Gets current value of property expandNavigationProperties.

Indicates if entities related to navigation properties inside the metadata are requested. If set to true, then these related entities are loaded with an $expand request.

Annotations that can have navigation properties are the following:

Note: Independent of the fetchValueListReadOnly value, setting this flag to true requests data from the backend.

Note: The back-end request to expand the navigation properties is sent only if the entity to which SmartField is bound is persisted. For transient entities, there is no back-end request since no such data is available.

Default value is false.

getFetchValueListReadOnly

Gets current value of property fetchValueListReadOnly.

Indicates whether the value list collection is fetched in display mode from the resource path specified in the com.sap.vocabularies.Common.v1.ValueList annotation.

This collection data is used to infer a descriptive text for the value of the SmartField control. However, fetching the value list collection for every SmartField instance individually may not be ideal in some performance-critical scenarios. To optimize this default behavior, you can set this property to false and provide the com.sap.vocabularies.Common.v1.Text annotation, which is used to specify the URL path name to the Entity Data Model (EDM) property from which the descriptive text for the value of the SmartField control is fetched, for example, LT (Laptop).

Note: Setting this property to false only has an effect if the value property of the SmartField control is bound to an Entity Data Model (EDM) property typed as Edm.String. In addition, applications or frameworks have to make sure the descriptive text is fetched, for example, by expanding a navigation property.

Default value is true.

getFixedValueListValidationEnabled

Gets current value of property fixedValueListValidationEnabled.

If the property is set to true, a standard validation for sap.m.ComboBox is performed. An inner control sap.m.ComboBox is created and the binding is to selectedKey. Changes at runtime are not reflected.

Note: If the property is set to false, the inner control is sap.ui.comp.smartfield.ComboBox and the binding is to enteredValue. In this case, any entered value is valid irrespective of whether it's in the predefined list or not.

Note: This property is applicable only for fixed-value scenarios.

Default value is false.

getFocusDomRef

Returns the DOM element that gets the focus.

getFormFormattedValue

Returns the formatted value of a control used in a SemanticFormElement.

getFormValueProperty

Returns the name of the value-holding property of a control used in a SemanticFormElement.

getHistoryEnabled

Gets current value of property historyEnabled.

If the property is set to false, history values are disabled. Changes at runtime are not reflected. The historyEnabled property is not applied to custom controls.

Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the historyEnabled property to true.

Default value is true.

getIdForLabel

Gets the ID of the control to which the label should point.

getImportance

Gets current value of property importance.

Specifies the importance of the field. Applicable only when the SmartField is used inside SmartForm.

Default value is Low.

getInnerControls

Resolves the controls hosted currently by this SmartField control.

getJsontype

Gets current value of property jsontype.

Data types to be used, if the SmartField control is interacting with a JSON model. If the value property of the control is bound to a property of an OData entity set, this property is not taken into consideration.

getMandatory

Gets current value of property mandatory.

Indicates whether user input is required.

Note: The SmartField control is metadata-driven and this property can be ignored if the following applies:

Default value is false.

getMaxLength

Gets current value of property maxLength.

Defines the highest possible number of permitted input characters that the user can enter into the text input field.

Computed maxLength

If the specified maxLength value is greater than the maxLength value specified for the underlying bound Entity Data Model (EDM) property in the service metadata document, the maxLength value of the EDM property takes precedence. Likewise, if the application code provides a binding data type for the value property of the SmartField control and the binding data type has maxLength constraints defined, this maxLength is also taken into consideration to compute the final maxLength value.

Validation Behavior

By design, the SmartField control does not restrict/validate the highest number of permitted input characters for every keystroke, but only when the text input field has changed, and the browser focus leaves the text input field or the ENTER key is pressed. The SmartField control is used more generically in broader contexts, and adding a maxLength attribute to the HTML text input control may break data type formatting in two-way data-binding scenarios. Let's say the maxLength property is set to 3, but the text input control has a formatter function attached to it to format the entered value "DE" to "Germany (DE)". In this case, the formatted value will be truncated by the maxLength setting.

Default value is 0.

sap.ui.comp.smartfield.SmartField.getMetadata

Returns a metadata object for class sap.ui.comp.smartfield.SmartField.

getMode

Returns the current SmartField's edit mode

getName

Gets current value of property name.

To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').

Default value is empty string.

getPlaceholder

Gets current value of property placeholder.

Text shown when no value available.

Default value is empty string.

getProposedControl

Gets current value of property proposedControl.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

Default value is None.

getRequired

Gets the value of the mandatory property.

This function is needed as the "mandatory" feature is named "required" in a lot of other controls (like Label or Form).

getSemanticObjectController

Gets content of aggregation semanticObjectController.

The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.

getShowLabel

Gets current value of property showLabel.

If set to false the label is not displayed.

Default value is true.

getShowSuggestion

Gets current value of property showSuggestion.

If set to true, the suggestion feature for a hosted control is enabled, if the hosted control supports it.

Default value is true.

getShowValueHelp

Gets current value of property showValueHelp.

If set to true, a value help indicator will be displayed inside the hosted control, if the hosted control supports this.

Default value is true.

getShowValueStateMessage

Gets current value of property showValueStateMessage.

Defines whether the value state message is shown or not.

Default value is true.

sap.ui.comp.smartfield.SmartField.getSupportedAnnotationPaths

Calculates the paths to the annotations used by the SmartField control.

Param Type DefaultValue Description
oMetaModel sap.ui.model.odata.ODataMetaModel

The given OData meta model

oEntitySet object

The given entity set

sValueBinding string

The path identifying the OData property to which the value property of the SmartField control is bound

bNavigationPathsOnly boolean

If set to true, no properties are returned

getTextAlign

Gets current value of property textAlign.

Horizontal alignment of the text.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control.

The textDirection property can be used when, for example, the text direction in the application is LTR but you want a specific field to have RTL text direction.

Note: The textDirection property is not applicable for the SmartField control for units of measure use cases.

Default value is Inherit.

getTextInEditModeSource

Gets current value of property textInEditModeSource.

Sets the source from which text descriptions for IDs are fetched in edit mode, for example, for LT (Laptop).

Note: The sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty and sap.ui.comp.smartfield.TextInEditModeSource.ValueList enumeration members are only supported if the following applies:

Note: In addition, the sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty enumeration member is only supported if the following applies:

Note: As of version 1.82, if SmartField is used inside a SmartForm, defaultTextInEditModeSource can be added as custom data to the form and it will be propagated to all smart fields that cover the above criteria. However, if textInEditModeSource is added to the SmartField as property, it will override the defaultTextInEditModeSource propagated from the SmartForm custom data.

Default value is None.

getTextLabel

Gets current value of property textLabel.

This property contains the text of an associated SmartLabel.

Default value is empty string.

getTooltipLabel

Gets current value of property tooltipLabel.

This property contains the tool tip of the associated SmartLabel control.

Default value is empty string.

getUnitOfMeasure

If the OData property to which the control's value property is bound semantically represents a unit of measure, the value of the current unit of measure is returned. Otherwise null is returned.

getUomEditable

Gets current value of property uomEditable.

Indicates whether the unit of measure field is in display or edit mode.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

Default value is true.

getUomEditState

Gets current value of property uomEditState.

This property is for internal use only.

Default value is -1.

getUomEnabled

Gets current value of property uomEnabled.

Enabled state of the unit, if the SmartField control addresses unit of measure use cases, for example, an amount and its associated currency.

Default value is true.

getUomVisible

Gets current value of property uomVisible.

Indicates whether the unit of measure field is visible.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

Note: The SmartField control is metadata-driven, and this property can be ignored if the bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

Default value is true.

getUrl

Gets current value of property url.

Contains a URL which is used to render a link. The link is rendered, if the OData property, to which the value property of the control is bound, is of type Edm.String and the SmartField is in display mode.

Default value is empty string.

getValue

Gets current value of property value.

The binding path expression used to determine the bound Entity Data Model (EDM) property.

Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The SmartField control usually creates its own data type based on the service metadata for the formatting of values. Also, when a custom formatter is specified for a property, the binding mode is automatically switched to one-way binding mode. Note: Named models are not supported, only the default model (named undefined) is supported. For example, when the binding path expression contains a > sign, the string preceding it is a named model and the remainder after the > is the binding path.

getValueState

Gets current value of property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success, Information.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text of the value state message popup.

Note: This method is public because of an implementation side effect and should not be used for validation purposes as it may conflict with the SmartField control's own binding type validation logic based on the underlying metadata of the bound Entity Data Model (EDM) property. Invoking the .setValueState() and/or .setValueStateText() methods in a change event handle to set an error state does not prevent an invalid value from being stored in the binding/model in two-way data binding scenarios. In addition, it does not fire the validationError event, which is usually required by some upstream modules, for example, the message manager.

Custom validation logic must be implemented in a custom binding type rather than in a change event handler.

Default value is empty string.

getWidth

Gets current value of property width.

Defines the width of the control.

Default value is empty string.

getWrapping

Gets current value of property wrapping.

Indicates whether the control break lines (in display mode) to prevent overflow.

Default value is true.

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

setClientSideMandatoryCheck

Sets a new value for property clientSideMandatoryCheck.

Determines if the mandatory check happens on the client side true or on the server side false.

Note: If the sap.ui.comp.smartfield.SmartField#value property of the SmartField control is bound to an Entity Data Model (EDM) property annotated as Nullable="false", the mandatory validation is performed on the client side regardless of the clientSideMandatoryCheck setting.

Example:

    <Property Name="CategoryID" Type="Edm.String" Nullable="false"/>

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
bClientSideMandatoryCheck boolean true

New value for property clientSideMandatoryCheck

setConfiguration

Sets the aggregated configuration.

Param Type DefaultValue Description
oConfiguration sap.ui.comp.smartfield.Configuration

The configuration to set

setContextEditable

Sets a new value for property contextEditable.

Notifies the control whether controls using the SmartField control are editable.

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
bContextEditable boolean true

New value for property contextEditable

setControlContext

Sets a new value for property controlContext.

Defines the context in which the layout of the SmartField control has to be interpreted.

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
sControlContext sap.ui.comp.smartfield.ControlContextType None

New value for property controlContext

setControlProposal

Sets the aggregated controlProposal.

Param Type DefaultValue Description
oControlProposal sap.ui.comp.smartfield.ControlProposal

The controlProposal to set

setEditable

Sets a new value for property editable.

Indicates whether the control is in display or edit mode.

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

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

setEnabled

Sets a new value for property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab order.

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

setEntitySet

Sets a new value for property entitySet.

The name of an entity set for which the control manages values. This is an optional property.

If this property is left empty, the entity set is computed by parsing the binding context path, for example, Tasks('id-1428419016778-51') is parsed to Tasks.

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
sEntitySet string ""

New value for property entitySet

setExpandNavigationProperties

Sets a new value for property expandNavigationProperties.

Indicates if entities related to navigation properties inside the metadata are requested. If set to true, then these related entities are loaded with an $expand request.

Annotations that can have navigation properties are the following:

Note: Independent of the fetchValueListReadOnly value, setting this flag to true requests data from the backend.

Note: The back-end request to expand the navigation properties is sent only if the entity to which SmartField is bound is persisted. For transient entities, there is no back-end request since no such data is available.

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

New value for property expandNavigationProperties

setFetchValueListReadOnly

Sets a new value for property fetchValueListReadOnly.

Indicates whether the value list collection is fetched in display mode from the resource path specified in the com.sap.vocabularies.Common.v1.ValueList annotation.

This collection data is used to infer a descriptive text for the value of the SmartField control. However, fetching the value list collection for every SmartField instance individually may not be ideal in some performance-critical scenarios. To optimize this default behavior, you can set this property to false and provide the com.sap.vocabularies.Common.v1.Text annotation, which is used to specify the URL path name to the Entity Data Model (EDM) property from which the descriptive text for the value of the SmartField control is fetched, for example, LT (Laptop).

Note: Setting this property to false only has an effect if the value property of the SmartField control is bound to an Entity Data Model (EDM) property typed as Edm.String. In addition, applications or frameworks have to make sure the descriptive text is fetched, for example, by expanding a navigation property.

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
bFetchValueListReadOnly boolean true

New value for property fetchValueListReadOnly

setFixedValueListValidationEnabled

Sets a new value for property fixedValueListValidationEnabled.

If the property is set to true, a standard validation for sap.m.ComboBox is performed. An inner control sap.m.ComboBox is created and the binding is to selectedKey. Changes at runtime are not reflected.

Note: If the property is set to false, the inner control is sap.ui.comp.smartfield.ComboBox and the binding is to enteredValue. In this case, any entered value is valid irrespective of whether it's in the predefined list or not.

Note: This property is applicable only for fixed-value scenarios.

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

New value for property fixedValueListValidationEnabled

setHistoryEnabled

Sets a new value for property historyEnabled.

If the property is set to false, history values are disabled. Changes at runtime are not reflected. The historyEnabled property is not applied to custom controls.

Note: For sap.m.ComboBox and sap.m.MultiComboBox the history values are disabled by default. To enable them for these controls, you need to set the historyEnabled property to true.

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
bHistoryEnabled boolean true

New value for property historyEnabled

setImportance

Sets a new value for property importance.

Specifies the importance of the field. Applicable only when the SmartField is used inside SmartForm.

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

Default value is Low.

Param Type DefaultValue Description
sImportance sap.ui.comp.smartfield.Importance Low

New value for property importance

setJsontype

Sets a new value for property jsontype.

Data types to be used, if the SmartField control is interacting with a JSON model. If the value property of the control is bound to a property of an OData entity set, this property is not taken into consideration.

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

Param Type DefaultValue Description
sJsontype sap.ui.comp.smartfield.JSONType

New value for property jsontype

setMandatory

Sets a new value for property mandatory.

Indicates whether user input is required.

Note: The SmartField control is metadata-driven and this property can be ignored if the following applies:

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

New value for property mandatory

setMaxLength

Sets a new value for property maxLength.

Defines the highest possible number of permitted input characters that the user can enter into the text input field.

Computed maxLength

If the specified maxLength value is greater than the maxLength value specified for the underlying bound Entity Data Model (EDM) property in the service metadata document, the maxLength value of the EDM property takes precedence. Likewise, if the application code provides a binding data type for the value property of the SmartField control and the binding data type has maxLength constraints defined, this maxLength is also taken into consideration to compute the final maxLength value.

Validation Behavior

By design, the SmartField control does not restrict/validate the highest number of permitted input characters for every keystroke, but only when the text input field has changed, and the browser focus leaves the text input field or the ENTER key is pressed. The SmartField control is used more generically in broader contexts, and adding a maxLength attribute to the HTML text input control may break data type formatting in two-way data-binding scenarios. Let's say the maxLength property is set to 3, but the text input control has a formatter function attached to it to format the entered value "DE" to "Germany (DE)". In this case, the formatted value will be truncated by the maxLength setting.

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

setName

Sets a new value for property name.

To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').

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
sName string ""

New value for property name

setPlaceholder

Sets a new value for property placeholder.

Text shown when no value available.

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

setProposedControl

Sets a new value for property proposedControl.

Proposes a control to be rendered. The SmartField control can ignore the proposal.

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
sProposedControl sap.ui.comp.smartfield.ControlProposalType None

New value for property proposedControl

setSemanticObjectController

Sets the aggregated semanticObjectController.

Param Type DefaultValue Description
oSemanticObjectController sap.ui.comp.navpopover.SemanticObjectController

The semanticObjectController to set

setShowLabel

Sets a new value for property showLabel.

If set to false the label is not displayed.

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
bShowLabel boolean true

New value for property showLabel

setShowSuggestion

Sets a new value for property showSuggestion.

If set to true, the suggestion feature for a hosted control is enabled, if the hosted control supports it.

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
bShowSuggestion boolean true

New value for property showSuggestion

setShowValueHelp

Sets a new value for property showValueHelp.

If set to true, a value help indicator will be displayed inside the hosted control, if the hosted control supports this.

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
bShowValueHelp boolean true

New value for property showValueHelp

setShowValueStateMessage

Sets a new value for property showValueStateMessage.

Defines whether the value state message is shown or not.

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
bShowValueStateMessage boolean true

New value for property showValueStateMessage

setTextAlign

Sets a new value for property textAlign.

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

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

New value for property textAlign

setTextDirection

Sets a new value for property textDirection.

The available text direction options are LTR and RTL. By default, the control inherits the text direction from its parent control.

The textDirection property can be used when, for example, the text direction in the application is LTR but you want a specific field to have RTL text direction.

Note: The textDirection property is not applicable for the SmartField control for units of measure use cases.

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

setTextInEditModeSource

Sets a new value for property textInEditModeSource.

Sets the source from which text descriptions for IDs are fetched in edit mode, for example, for LT (Laptop).

Note: The sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty and sap.ui.comp.smartfield.TextInEditModeSource.ValueList enumeration members are only supported if the following applies:

Note: In addition, the sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty enumeration member is only supported if the following applies:

Note: As of version 1.82, if SmartField is used inside a SmartForm, defaultTextInEditModeSource can be added as custom data to the form and it will be propagated to all smart fields that cover the above criteria. However, if textInEditModeSource is added to the SmartField as property, it will override the defaultTextInEditModeSource propagated from the SmartForm custom data.

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
sTextInEditModeSource sap.ui.comp.smartfield.TextInEditModeSource None

New value for property textInEditModeSource

setTextLabel

Sets a new value for property textLabel.

This property contains the text of an associated SmartLabel.

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
sTextLabel string ""

New value for property textLabel

setTooltipLabel

Sets a new value for property tooltipLabel.

This property contains the tool tip of the associated SmartLabel control.

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
sTooltipLabel string ""

New value for property tooltipLabel

setUnitOfMeasure

If the OData property the control's value property is bound to semantically represents a unit of measure, the value of the current unit of measure can be changed.

Param Type DefaultValue Description
sUnit string

The new unit of measure to be set.

setUomEditable

Sets a new value for property uomEditable.

Indicates whether the unit of measure field is in display or edit mode.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

Note: The SmartField control is metadata-driven, and this control property can be ignored if the following applies:

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
bUomEditable boolean true

New value for property uomEditable

setUomEnabled

Sets a new value for property uomEnabled.

Enabled state of the unit, if the SmartField control addresses unit of measure use cases, for example, an amount and its associated currency.

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
bUomEnabled boolean true

New value for property uomEnabled

setUomVisible

Sets a new value for property uomVisible.

Indicates whether the unit of measure field is visible.

Note: This control property is only valid if the SmartField control addresses a unit of measure composite field, for example, an amount field and its associated currency field. The field must then be annotated with one of the following annotations:

Note: The SmartField control is metadata-driven, and this property can be ignored if the bound EDM property is annotated with the com.sap.vocabularies.Common.v1.FieldControl annotation.

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
bUomVisible boolean true

New value for property uomVisible

setUrl

Setter for property url. Default value is null.

Param Type DefaultValue Description
sValue string

The new value for property url

setValue

Sets a new value for property value.

The binding path expression used to determine the bound Entity Data Model (EDM) property.

Note: Composite binding expressions for this property are not supported. Note: Custom formatters for this property are not supported. The SmartField control usually creates its own data type based on the service metadata for the formatting of values. Also, when a custom formatter is specified for a property, the binding mode is automatically switched to one-way binding mode. Note: Named models are not supported, only the default model (named undefined) is supported. For example, when the binding path expression contains a > sign, the string preceding it is a named model and the remainder after the > is the binding path.

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

Param Type DefaultValue Description
oValue any

New value for property value

setValueState

Setter for property valueState. Default value is None.

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

The new value for property valueState

setValueStateText

Setter for property valueStateText. Default value is empty/undefined.

Param Type DefaultValue Description
sText string

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

Default value is empty string.

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

New value for property width

setWrapping

Sets a new value for property wrapping.

Indicates whether the control break lines (in display mode) to prevent overflow.

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
bWrapping boolean true

New value for property wrapping