Intro
The smart form control creates a form. If used with smart fields, the smart form provides both read-only and editable views, and OData annotations for the smart fields are taken into account. The smart form also provides a toolbar with a title.
When to Use
Use the smart form if:
- You use an OData service for your app (OData version 2 only).
- You are using only (or primarily) smart fields inside your form. In this case, the smart form is faster to implement.
Do not use the smart form if:
- You use a different technology to OData version 2. Use the form or simple form.
- You need several other controls in your form that are not provided by the smart field, such as buttons, progress indicators, or sliders. In this case, use the form or simple form.
- You just want to display a few fields within a very strict layout (such as in the object page header facets). In this case, use layout containers for placing the controls.
- You want to place several input fields in one column of the responsive table. In this case, use layout containers for placing the controls.
Components
Toolbar
The following options are provided:
- Expand/collapse button
- Title
- App-specific actions
Expand/Collapse Button
Expanded smart form
Collapsed smart form
- Do not use the expand/collapse button in object pages.
- Even in other places, it is not usually recommended.
Each form group comes with:
- A title
- One or several form elements and/or semantic form elements
Form elements (sap.ui.comp.smartform.GroupElement) consist of a label and one or several UI elements. If smart fields are used, the label is automatically provided by the corresponding metadata. If more than one smart field is used, define which label to display (GroupElement, property: elementForLabel).
The semantic form element (sap.ui.comp.smartform.SemanticGroupSlement) provides additional support when more than one control is attached to a single label. In display mode, the corresponding texts are displayed as a single value and therefore use less space. You can define a delimiter, which is shown between the fields.
A semantic form element in edit mode
The same semantic form element in display mode
- Ideally, use only smart fields.
- If this is not possible, use only controls that implement theIFormContent interface . Other controls could damage the visual layout, keyboard support, and screen reader support.
Layout
- Always use the column layout.
- If using a smart form on an object page, additional guidelines apply.
Behavior and Interaction
Display and Edit Mode
Validation
Responsiveness
The smart form acts exactly like the embedded controls. For details, see:
Size S
Size M
Size L
Size XL
Example
Smart form in edit mode
The same smart form in display mode
Top Tips
- Use smart fields wherever it makes sense.
- Use the column layout.
- When using one label for several controls, consider the semantic form element.
Properties
The following properties are available for sap.ui.comp.smartform.SmartForm:
- The property: checkButton adds a button labeled Check to the toolbar. The button triggers front-end validation on available smart fields. Do not use it. Follow the guidelines for form field validation instead.
- The property: editToggable adds an icon-only button to the toolbar, which switches the editable property. Do not use it. Follow the guidelines for object handling instead.
- The property: entityType is used for key user adaptations.
- The property: flexEnabled is used for key user adaptations.
- The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Do not use it. Use the column layout instead.
- The property: ignoredFields is used for key user adaptations.
- The property: importance hides all smart fields with lower importance. Do not use it.
- The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.
The following properties are available for sap.ui.comp.smartform.Group:
- The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Use the column layout instead.
- The property: label is deprecated. Use the aggregation: title instead.
- The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.
- The aggregation: layout is deprecated. Use the aggregation: layoutData instead.
Related Links
Elements and Controls
- Form / Simple Form (guidelines)
- Smart Field (guidelines)
- Toolbar Overview (guidelines)
- Object Handling (guidelines)
- Object Page Floorplan (guidelines)
Implementation
- Smart Form (SAPUI5 samples)
- Smart Form (SAPUI5 API reference)
- Smart Form (Developer Guide)