Show TOC

Smart FieldLocate this document in the navigation structure

The sap.ui.comp.smartfield.SmartField control offers a wrapper for other controls using OData metadata to determine which control has to be instantiated and makes it possible to add input-enabled fields to an application.

Overview

The SmartField control provides an efficient way to add input-enabled fields to an SAP Fiori application. The control automatically adjusts to the meta data of the underlying OData service, for example, by doing the following:

  • Hosting controls for editing and displaying values of OData properties

  • Providing value help automatically

  • Performing input checks

In addition, the SmartField control implements field control and supports message handling.

The SmartField control can be used in the following ways:

  • As a standalone control, for example, in XML views

  • In combination with a SmartForm control

  • In combination with a SmartTable control

    Used in particular as cell editor in editing scenarios.

The SmartField control selects a control for displaying and a control for editing the OData property to which they are bound. The main criterion for selecting nested controls is the EDM type of the OData property to which a SmartField control is bound.

Binding

The OData property that a SmartField control manages is determined by the binding of the value property of the control. Here arbitrarily and deeply nested, complex properties are supported.

The SmartField control allows for binding of navigation properties.

The entity set to which the bindings are related is either specified in the entitySet attribute of the control or derived from the binding context at runtime.

When binding SmartField against the OData service property of type Edm.Boolean and if SmartField is in read-only mode, static texts are used for visual representation. In addition, a configuration parameter in the SmartField control can define the properties of the static texts of the CheckBox, such as Yes/No or True/False. For the SmartForm control, the custom data can be used for this purpose.

Note

You can use any available predefined model for data binding in the SmartField control.

Table 1: Control Selection for Editing Use Cases

EDM Type

Control

Edm.Boolean

sap.m.CheckBox

Edm.Int16

sap.m.Input

Edm.Int32

Edm.Int64

Edm.SByte

Edm.Byte

Edm.Single

Edm.Float

Edm.Double

Edm.Decimal

Edm.DateTime

Edm.DateTimeOffset

Edm.String

Annotations

The following table shows a selection of the annotations used by the SmartField control:
Table 2: Annotations

Element

Annotation

Further Distinction

Value

Description

Value list

ValueList

    

Provides the value help dialog and type-ahead function

Value list

ValueList at EntitySet

 Annotated with sap:semantics fixed-values Renders a combo box

Currency

Org.OData.Measures.V1.ISOCurrency

Annotated with sap:semantics

Shows currencies

Unit of measure

Org.OData.Measures.V1.Unit

 Annotated with sap:semantics

Shows units of measure

Date/time

sap:display-format

OData property of type Edm.DateTime

date

Renders a DatePickercontrol

OData property of type Edm.Time

time

Renders a sap.m.TimePicker control

Upper case strings

sap:display-format and com.sap.vocabularies.Common.v1.IsUpperCase

OData property of type Edm.String

UpperCase

Shows capitalized strings

Numeric values

sap:precision=" DisplayScale"

OData property of numeric type, such as Edm.Decimal

Displays an amount or measure with the sap:precision attribute

Masking

com.sap.vocabularies.Common.v1.Masked

 

Masks content of child input field

Multiple lines

com.sap.vocabularies.ui.v1.MultiLineText

Displays a field with multiple lines of text

Smart links

SemanticObject

Determines that SmartField must host a SmartLink control

Status control

UI.CriticalityType

Uses the ObjectStatus class for status control

Displays status icons based on the annotation

The annotations are used as described below:

  • Value list annotation

    The annotation determines whether a value help dialog and the type ahead function are available.

    • If the entitySet that is addressed in the value list annotation has in turn the sap:semantics annotation with the value fixed-values, a combo box is rendered.

  • sap:semantics annotation

    The annotation is used to determine, for example, whether the SmartField control manages currencies.

  • Semantic object annotation

    The annotation is used to determine whether the SmartField control must manage a SmartLink control.

    For more information, see Smart Link.

  • If the relevant OData property is of type Edm.DateTime and the sap:display-format annotation with the date value is used, a DatePicker control is rendered.
  • If the relevant OData property is of type Edm.String, the sap:display-format annotation with UpperCase is used.
  • If the relevant OData property is of a numeric EDM type, such as Edm.Decimal, scale and precision are used.

  • The com.sap.vocabularies.Common.v1.Masked annotation is used to mask the content of its child input field.

  • The com.sap.vocabularies.ui.v1.MultiLineText annotation is used to represent a field as a multiline text field.

For the sap:field-control attribute, the following annotations are available:

Table 3: v2 and v4 Annotations along with Vocabulary

OData v2 SAP Extension

OData v4 Annotation

Vocabulary
updatable (EntitySet)

UpdateRestrictions/Updatable

OASIS - Capabilities

creatable="true" (property)

updatable="false" (property)

Immutable

OASIS - Core

creatable="false" (property)

updatable="false" (property)

Computed

OASIS - Core

updatable-path (EntitySet)

UpdateRestrictions/Updatable

OASIS - Capabilities

visible="false"

FieldControl EnumMember="Hidden"

SAP - Common

field-control

FieldControl

SAP - Common

Configuration

The SmartField control provides the option to overwrite the default behavior for control selection by using a specific configuration.

You have the following options:

  • If the relevant OData property is of type Edm.String or Edm.Boolean, the SmartField control can be configured to render a combo box.

  • If the relevant OData property is of type Edm.DateTime, the SmartField control can be configured to render a date picker.

    In addition, the display format of the date in the date picker can also be configured.

    Table 4: Control Selection for Display Use Cases

    EDM Type

    Control

    Edm.Boolean

    sap.m.CheckBox

    Edm.Int16

    sap.m.Text

    Edm.Int32

    Edm.Int64

    Edm.SByte

    Edm.Byte

    Edm.Single

    Edm.Float

    Edm.Double

    Edm.Decimal

    Edm.DateTime

    Edm.DateTimeOffset

    Edm.String

Field Control

The field control handles the visual representation of SmartField controls, such as:

  • Whether input is mandatory

  • Whether the controls are read-only

  • Whether the controls are hidden as defined by the SAP Fiori user interface programming model

The following attributes are available to implement field control:

  • Enabled

    Toggles from display to edit mode.

  • Visible

    Hides the SmartField control.

  • Mandatory

    Determines whether input is required.

Consumers of the SmartField control can further adapt the runtime behavior by binding these attributes.

The behavior can only be made more restrictive on client side, for example, if an OData property is mandatory, this cannot be overwritten on SmartField control level.