Intro
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.
Components
The smart field consists of a basic UI element and an optional label. The following UI elements are available:
Edit mode:
- One or two input fields (with or without a value help dialog)
- Select
- Combo box
- Text area
- Checkbox
- Date picker
- Date/time picker
- Time picker
Display mode:
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:
- Set a default value whenever appropriate (annotation: text, property: value).
- To show a static unit of measurement, use a description (annotation: text).
- To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
- If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
- You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
- If data entry is expected in a specific format, set a placeholder (property: Placeholder).
Behavior and Interaction
Context
- If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
- If you use a “standalone” smart field in a form-like arrangement, use a dash to show an empty value in display mode.
Switching Between Edit and Display Mode
Smart field as a select with 'required' indicator in edit mode
The same smart field in display mode
- Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
- For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
- Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
- When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).
Suggestions and Value Help
You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: 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: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)
Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).
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: IsConfigurationDeprecationCode).
The following controls are used to offer suggestions or value help:
- A fixed value list leads to a combo box or select, depending on the control configuration.
- A non-fixed value list leads to an input field with a value help dialog.
Smart field as a combo box
Smart field as an input field with suggestions, auto complete, and a value help button
The automatically generated value help dialog for the same smart field
Recently Used Values
Do not show recently used values for a field if:
- There are only a small number of options.
- The field contains personal sensitive data (annotation: IsPotentiallySensitive).
- It is unlikely that the same values will be selected again and again.
Recommended Values
In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).
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.
Validation
The smart field offers the following validations automatically:
- Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
- 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: fieldGroupIds).
- Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
- Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).
The validation result is indicated by a value state (property: showValueStateMessage).
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: ValueListNoValidation).
Examples:
- 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
Automatic validation
IDs
The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):
- It checks for non-negative numbers.
- It shows values containing only “0” digits as empty.
- It does not show leading zeros.
Units
Smart field showing an amount with a currency in display mode
The same smart field in display mode
Sensitive Data
Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).
Capitalizing Text Input
Text input can be capitalized automatically (property: IsUpperCase).
States
Smart fields support the following states (annotation: fieldControl):
- Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
- Enabled or disabled
- Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
- 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: Nullable, property: mandatory).
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: SideEffects).
Content Alignment
Responsiveness
The smart field acts exactly like the embedded controls. For details see:
Top Tips
-
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.
Properties
The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:
- The property: expandNavigationProperties is experimental. Do not use it.
- The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
- The property: jsontype is deprecated. Do not use it.
- The property: name is used in HTML forms that send data to the server via “Submit”.
- The property: uomEditState is for internal use only. Do not use it.
- The property: proposedControl is deprecated. Do not use it.
- The property: textDirection provides support for reading directions in different locales.
- The aggregation: controlProposal is deprecated. Do not use it.
- The association: ariaLabelledBy can be used for linking additional labels to the smart field.
Related Links
Elements and Controls
- Text (guidelines)
- Object Display Components (guidelines)
- Link (guidelines)
- Input Field (guidelines)
- Select (guidelines)
- Combo Box (guidelines)
- Date Picker (guidelines)
- Date/Time Picker (guidelines)
- Time Picker (guidelines)
- Text Area (guidelines)
- Checkbox (guidelines)
- Smart Link (guidelines)
Implementation
- Smart Field (SAPUI5 API reference)
- Smart Field (Developer Guide)
- Smart Field (SAPUI5 samples)
- Smart Controls (SAPUI5 samples)
- Side Effects (Developer Guide)
Visual Design
- Text (visual design specification)
- Object Identifier (visual design specification)
- Object Number (visual design specification)
- Object Status (visual design specification)
- Link (visual design specification)
- Smart Link (visual design specification)
- Input Field (visual design specification)
- Select (visual design specification)
- Combo Box (visual design specification)
- Date Picker (visual design specification)
- Time Picker (visual design specification)
- Text Area (visual design specification)
- Checkbox (visual design specification)