The smart field creates different user input controls and their read-only equivalents based on an OData (Open Data Protocol) service and its annotations. It comes with additional built-in features, such as autocomplete and suggestions, value help dialog, recently used and recommended values, validation, and message handling.
When to Use
Use the smart field if:
- You use an OData service for your app (OData version 2 only).
- The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
- You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
- You use a smart form.
Do not use the smart field if:
- You use a different technology to OData version 2. Use the corresponding controls directly.
- You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
- You need a different dialog for offering value help, such as the select dialog or table select dialog.
- You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.
The smart field consists of a basic UI element and an optional label. The following UI elements are available:
For details, see the corresponding guideline topics.
User Input Control
The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:
|Read-Only||Edit||Edm Types / Annotations / Properties||Comment|
|Single-line text||Text||Input field||Edm.String
Configuration: controlType, value: input
Configuration: controlType, value: dropDownList
Configuration: controlType, value: selection
|Multi-line text||Text||Text area||Edm.String
|Decimal numbers||Text||One or two input fields
(for number and unit)
|Edm.Int16, Edm.Int32, Edm.Int64,
Edm.Single, Edm.Float, Edm.Double,
|Status information||Object status||Edm.String
|Text and ID||Text||Input field||TextArrangement
|The following patterns can be selected via displayBehavior:
(with/without quick view)
|Dates and times||Text||Date/time picker||Edm.DateTime
|Fiscal periods||Text||Input field||IsFiscalYear, IsFiscalPeriod,
|Amounts with currencies||Text||One or two input fields||ISOCurrency or sap:unit with sap:semantics=”currency-code”|
|Phone numbers||Text||Input field||IsPhoneNumber|
|The text in display mode can be influenced via displayBehavior:
Behavior and Interaction
You can use the smart field in different contexts
- Within a form (depending on the form layout)
- Within a table (depending on the table type)
The context influences:
Switching Between Edit and Display Mode
Switching between edit and display mode can be controlled manually (annotation:
editable) or automatically by the containing smart form or smart table (property:
You can enable suggestions for controls that offer this feature (property:
showSuggestions). The list of suggestible values must be provided (annotation:
ValueListWithFixedValues only for
entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.
Autocomplete is enabled automatically.
For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property:
showValueHelp). The table in the value help dialog can be filled with initial content (annotation:
Both the value help dialog and the suggestion list can be prefiltered (annotation:
valueListParameterIn). The selected items can be used to prefilter other fields (annotation:
ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (
If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation:
Recently Used Values
Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property:
historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.
In addition to recently used values, a smart field can show recommended values (annotation:
The corresponding smart field is highlighted and/or prefilled:
- If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
- If a recommendation is available and there is no user input, the smart field is shown in the information state.
- If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.
The recommended values are shown as soon as the user focuses on the smart field.
The smart field offers the following validations automatically:
- Validation for required fields: This can be done on the client or server side (property:
- Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property:
- Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property:
The validation result is indicated by a value state (property:
When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation:
- Allowing the user to enter additional values (which are not in the suggestion list)
- Typing a text instead of an ID to filter down the suggestion list
- Using the smart field in a draft
The smart field offers automatic validation for number-only ID fields (annotations:
- It checks for non-negative numbers.
- It shows values containing only “0” digits as empty.
- It does not show leading zeros.
For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure (annotations:
uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties:
Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations:
Capitalizing Text Input
Text input can be capitalized automatically (property:
Smart fields support the following states (annotation:
- Editable or display only (additional annotations:
- Enabled or disabled
- Visible or hidden (additional annotations: property:
- Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation:
The following states for a unit of measurement can be set independently of the corresponding field:
Dependencies between Smart Fields
If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation:
You can change the horizontal alignment of the text within any kind of input field (property:
- Always label a smart field if it is not inside a table context.
- Use suggestions with autocomplete whenever possible and meaningful.
- Do not show suggestions if there are only a few choices.
- Use recently used values as appropriate.
- Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
- Make use of validation features.
The following properties, aggregations, and associations are available for
- The property:
expandNavigationPropertiesis experimental. Do not use it.
- The property:
jsontypeis deprecated. Do not use it.
- The property:
nameis used in HTML forms that send data to the server via “Submit”.
- The property:
uomEditStateis for internal use only. Do not use it.
- The property:
proposedControlis deprecated. Do not use it.
- The property:
textDirectionprovides support for reading directions in different locales.
- The aggregation:
controlProposalis deprecated. Do not use it.
- The association:
ariaLabelledBycan be used for linking additional labels to the smart field.