smartfield/SmartField
The <code>SmartField</code> 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 <code>value</code> property.
<h3>Accessibility</h3>
For interoperability and accessibility reasons, the <code>SmartField</code> control must be labeled
by the <code>sap.ui.comp.smartfield.SmartLabel</code> control instead of the <code>sap.m.Label</code> control, as
the <code>sap.m.Label</code> control does not know of the inner structure of a <code>SmartField</code> control.
If the <code>SmartField</code> control is rendered inside a smart container control, for example, the <code>SmartForm</code>
control, the <code>SmartLabel</code> control is automatically generated to reduce the amount of code needed on
the application side.
However, in other scenarios when <code>SmartField</code> is used stand-alone or outside a smart container
control, for example, a <code>SimpleForm</code> control, the <code>SmartLabel</code> control is not automatically
generated in these cases.
Although the <code>sap.ui.comp.smartfield.SmartLabel</code> is a private/internal control, the following basic use
is allowed by applications for labeling the <code>SmartField</code> control.
<i>XML Example of a <code>SmartField</code> control labeled by a <code>SmartLabel</code> control</i>
<pre>
<sap.ui.comp.smartfield.SmartLabel labelFor="IDProduct"/>
<sap.ui.comp.smartfield.SmartField id="IDProduct" value="{ProductId}"/>
</pre>
sap.ui.core/Control
The binding path expression used to determine the bound Entity Data Model (EDM) property.
<b>Note:</b> Composite binding expressions for this property are not supported.
<b>Note:</b> Custom formatters for this property are not supported.
The <code>SmartField</code> 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.
<b>Note:</b> Named models are not supported, only the default model (named undefined) is supported.
For example, when the binding path expression contains a <code>></code> sign, the string
preceding it is a named model and the remainder after the <code>></code> is the binding path.
Indicates whether the user can interact with the control or not. <b>Note:</b> Disabled controls cannot be focused and they are out
of the tab order.
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, <code>Tasks('id-1428419016778-51')</code> is parsed to <code>Tasks</code>.
Indicates whether the control is in display or edit mode.
<b>Note:</b> The <code>SmartField</code> control is metadata-driven, and this control
property can be ignored if the following applies:
<ul>
<li>The bound Entity Data Model (EDM) property or its entity set are annotated with the
OData V2 <code>sap:updatable</code> annotation.</li>
<li>The bound EDM property or its entity set are annotated with the <code>sap:creatable</code>
annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V2
<code>sap:updatable-path</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Capabilities.V1.InsertRestrictions</code> annotation.</li>
<li>The bound EDM property is annotated with the
<code>com.sap.vocabularies.Common.v1.FieldControl</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Capabilities.V1.UpdateRestrictions</code> annotation.</li>
</ul>
Notifies the control whether controls using the <code>SmartField</code> control are editable.
Defines the width of the control.
Horizontal alignment of the text.
Text shown when no value available.
To be used in the HTML code (for example, for HTML forms that send data to the server via 'submit').
Visualizes the validation state of the control, e.g. <code>Error</code>, <code>Warning</code>,
<code>Success</code>, <code>Information</code>.
<b>Note:</b> This method is public because of an implementation side effect and should not be used
for validation purposes as it may conflict with the <code>SmartField</code> control's own binding
type validation logic based on the underlying metadata of the bound Entity Data Model (EDM)
property.
Invoking the <code>.setValueState()</code> and/or <code>.setValueStateText()</code> methods in a
<code>change</code> 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 <code>validationError</code> 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
<code>change</code> event handler.
Defines the text of the value state message popup.
<b>Note:</b> This method is public because of an implementation side effect and should not be used
for validation purposes as it may conflict with the <code>SmartField</code> control's own binding
type validation logic based on the underlying metadata of the bound Entity Data Model (EDM)
property.
Invoking the <code>.setValueState()</code> and/or <code>.setValueStateText()</code> methods in a
<code>change</code> 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 <code>validationError</code> 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
<code>change</code> event handler.
Defines whether the value state message is shown or not.
Data types to be used, if the <code>SmartField</code> 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.
Indicates whether user input is required.
<b>Note:</b> The <code>SmartField</code> control is metadata-driven and this property can
be ignored if the following applies:
<ul>
<li>The bound Entity Data Model (EDM) property is annotated with the <code>Nullable</code>
annotation. The <code>Nullable</code> 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 <code>Nullable</code> attribute is specified as <code>Nullable="false"</code>,
a value is mandatory.</li>
<li>The bound EDM property is annotated with the <code>com.sap.vocabularies.Common.v1.FieldControl</code>
annotation.</li>
</ul>
Defines the highest possible number of permitted input characters that the user can enter
into the text input field.
<h3>Computed <code>maxLength</code></h3>
If the specified <code>maxLength</code> value is greater than the <code>maxLength</code>
value specified for the underlying bound Entity Data Model (EDM) property in the service
metadata document, the <code>maxLength</code> value of the EDM property takes precedence.
Likewise, if the application code provides a binding data type for the <code>value</code>
property of the <code>SmartField</code> control and the binding data type has
<code>maxLength</code> constraints defined, this <code>maxLength</code> is also taken into
consideration to compute the final <code>maxLength</code> value.
<h3>Validation Behavior</h3>
By design, the <code>SmartField</code> 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 <code>SmartField</code> control is used more generically in broader contexts,
and adding a <code>maxLength</code> attribute to the HTML text input control may break data
type formatting in two-way data-binding scenarios.
Let's say the <code>maxLength</code> 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 <code>maxLength</code> setting.
If set to <code>true</code>, the suggestion feature for a hosted control is enabled, if the hosted control supports it.
If set to <code>true</code>, a value help indicator will be displayed inside the hosted control, if the hosted control supports
this.
If set to <code>false</code> the label is not displayed.
This property contains the text of an associated <code>SmartLabel</code>.
This property contains the tool tip of the associated <code>SmartLabel</code> control.
Indicates whether the unit of measure field is visible.
<b>Note:</b> This control property is only valid if the <code>SmartField</code> 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:
<ul>
<li>The bound Entity Data Model (EDM) property or its entity set are annotated with the
OData V2 <code>sap:unit</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Measures.V1.ISOCurrency</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Measures.V1.Unit</code> annotation.</li>
</ul>
<b>Note:</b> The <code>SmartField</code> control is metadata-driven, and this property can
be ignored if the bound EDM property is annotated with the <code>com.sap.vocabularies.Common.v1.FieldControl</code>
annotation.
Indicates whether the unit of measure field is in display or edit mode.
<b>Note:</b> This control property is only valid if the <code>SmartField</code> 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:
<ul>
<li>The bound Entity Data Model (EDM) property or its entity set are annotated with the
OData V2 <code>sap:unit</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Measures.V1.ISOCurrency</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Measures.V1.Unit</code> annotation.</li>
</ul>
<b>Note:</b> The <code>SmartField</code> control is metadata-driven, and this control
property can be ignored if the following applies:
<ul>
<li>The bound Entity Data Model (EDM) property or its entity set are annotated with the
OData V2 <code>sap:updatable</code> annotation.</li>
<li>The bound EDM property or its entity set are annotated with the <code>sap:creatable</code>
annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V2
<code>sap:updatable-path</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Capabilities.V1.InsertRestrictions</code> annotation.</li>
<li>The bound EDM property is annotated with the
<code>com.sap.vocabularies.Common.v1.FieldControl</code> annotation.</li>
<li>The entity set of the bound EDM property is annotated with the OData V4
<code>Org.OData.Capabilities.V1.UpdateRestrictions</code> annotation.</li>
</ul>
Enabled state of the unit, if the <code>SmartField</code> control addresses unit of measure use cases, for example, an amount and
its associated currency.
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 <code>Edm.String</code> and the <code>SmartField</code> is in display mode.
This property is for internal use only.
Defines the context in which the layout of the <code>SmartField</code> control has to be interpreted.
Proposes a control to be rendered. The <code>SmartField</code> control can ignore the proposal.
Indicates whether the control break lines (in display mode) to prevent overflow.
Determines if the mandatory check happens on the client side <code>true</code> or on the server side
<code>false</code>.
<b>Note:</b> If the {@link sap.ui.comp.smartfield.SmartField#value} property of the
<code>SmartField</code> control is bound to an Entity Data Model (EDM) property annotated as
<code>Nullable="false"</code>, the mandatory validation is performed on the client side regardless of
the <code>clientSideMandatoryCheck</code> setting.
<i>Example:</i>
<pre>
<Property Name="CategoryID" Type="Edm.String" Nullable="false"/>
</pre>
Indicates whether the value list collection is fetched in display mode from the resource path
specified in the <code>com.sap.vocabularies.Common.v1.ValueList</code> annotation.
This collection data is used to infer a descriptive text for the value of the <code>SmartField</code>
control. However, fetching the value list collection for every <code>SmartField</code> instance
individually may not be ideal in some performance-critical scenarios.
To optimize this default behavior, you can set this property to <code>false</code> and provide the
<code>com.sap.vocabularies.Common.v1.Text</code> 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
<code>SmartField</code> control is fetched, for example, LT (Laptop).
<b>Note:</b> Setting this property to <code>false</code> only has an effect if the <code>value</code>
property of the <code>SmartField</code> control is bound to an Entity Data Model (EDM) property typed
as <code>Edm.String</code>. In addition, applications or frameworks have to make sure the descriptive
text is fetched, for example, by expanding a navigation property.
Indicates if entities related to navigation properties inside the metadata are requested.
If set to <code>true</code>, then these related entities are loaded with an <code>$expand</code> request.
Annotations that can have navigation properties are the following:
<ul>
<li> <code>com.sap.vocabularies.Common.v1.Text</code> for text arrangements
<li> <code>Org.OData.Measures.V1.Unit</code> and <code>Org.OData.Measures.V1.ISOCurrency</code> for units
<li> <code>com.sap.vocabularies.Common.v1.FieldControl</code> for field control
</ul>
<b>Note:</b> Independent of the <code>fetchValueListReadOnly</code> value, setting this flag to <code>true</code>
requests data from the backend.
<b>Note:</b> The back-end request to expand the navigation properties is sent only if the entity to which
<code>SmartField</code> is bound is persisted.
For transient entities, there is no back-end request since no such data is available.
Sets the source from which text descriptions for <code>IDs</code> are fetched in edit mode, for example,
for LT (Laptop).
<b>Note</b>: The <code>sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty</code> and
<code>sap.ui.comp.smartfield.TextInEditModeSource.ValueList</code> enumeration members are only supported if the
following applies:
<ul>
<li>The <code>value</code> property of the <code>SmartField</code> control instance
is bound to an Entity Data Model (EDM) property typed as <code>Edm.String</code> or <code>Edm.Guid</code>.</li>
<li>The <code>com.sap.vocabularies.UI.v1.TextArrangement</code> annotation for the bound EDM property or entity
type is specified in the service metadata document or annotation file.</li>
<li>The binding mode for the <code>value</code> property of the <code>SmartField</code> control is the two-way binding
mode.</li>
<li>The field from which the description is fetched is filterable.</li>
</ul>
<b>Note</b>: In addition, the <code>sap.ui.comp.smartfield.TextInEditModeSource.NavigationProperty</code> enumeration
member is only supported if the following applies:
<ul>
<li>The EDM navigation property association is defined in the service metadata document.</li>
<li>The <code>com.sap.vocabularies.Common.v1.Text</code> annotation for the bound EDM property is specified in the
service metadata document or annotation file whose <code>Path</code> attribute points to a EDM navigation property
of a lookup entity set/type whose single key property is the <code>ID</code>, which contains (among other properties)
the descriptive value.</li>
<li>The lookup entity must be loaded. The lookup entity can be loaded by expanding the EDM navigation property via
a <code>$expand</code> query parameter.</li>
<li>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.</li>
<li>The EDM navigation property association end multiplicity of the lookup entity type/set is defined as <code>1</code>
in the service metadata document. There must be a single-valued navigation from the editable entity set/type
to the lookup entity set/type.</li>
<li>The lookup entity type/set from which the descriptive value is fetched contains a single-key EDM property.</li>
</ul>
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.
The path to the found entity set
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.
<b>Note:</b> 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.
The current value inside the text field
<b>Note:</b> 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.
The new value inside the text field
The event is fired after the smart field has calculated its metadata.
The event is fired after the visibility of the control has changed.
If <code>true</code>, the control is visible
The event is fired after the value of editable property of the control has changed.
If <code>true</code>, the control is in edit mode
The event is fired after the context editable property of the control has changed.
The value of the context editable property of the control
The event is fired after the inner controls have been created. The created controls can be obtained via oControl.getInnerControls().
The event is fired when after selection of values with value help or auto-suggest, the model is updated with the selected data.
An array of selected values
Fires when the user triggers the link control or taps/clicks on an active title of the object identifier control.
The content aggregation is used to hold the control that is hosted by the <code>SmartField</code> control.
Optional configuration for <code>SmartField</code>.
<b>Note</b>: By default, the value of the <code>displayBehaviour</code> property is not evaluated
in edit mode. To enable this feature in edit mode, set the <code>textInEditModeSource</code> control property
to a non-default value.
Proposes a control to be rendered. The <code>SmartField</code> control can ignore the proposal.
Collects the texts to be used for the ARIA labels.<br>
The InvisibleText controls will be added to the DOM by the <code>SmartField</code> control.
The Semantic Object Controller allows the user to specify and overwrite functionality for semantic object navigation.
Association to controls / IDs which label this control (see WAI-ARIA attribute <code>aria-labelledby</code>).