The sap.ui.comp.smartform.SmartForm control makes it possible to render a form using OData metadata annotations. Depending on user authorizations, the form enables users, for example, to switch from display to edit mode, add and group fields, rename field labels, and implement a user input check.
The SmartForm control displays form content. If used in combination with the SmartField control and OData metadata annotations along with additional configuration, a form can be created with minimal effort.
The SmartForm control supports the following features:
Adaptation settings
Adding and hiding fields
Adding and hiding groups
Changing the order of fields and groups
Renaming field labels
Display/Edit button
This optional button allows the user to toggle from display to edit mode.
Fields are automatically displayed with the appropriate control, for example, texts on the user interface in display mode and user input in edit mode.
Field labels
For fields of type SmartField, the SmartForm control automatically creates a label based on the OData metadata annotations.
Check button
This optional button allows the user to check the current user input.
For fields of type SmartField, values will be checked based on the OData metadata annotations. Fields with errors will be circled in red. When the user clicks on one of these fields, the relevant error message will be displayed.
Forms consist of groups (sap.ui.comp.smartform.Group) and group elements (sap.ui.comp.smartform.GroupElement).
A group element is a collection of controls that are displayed along with a label. Typically, a group element consists of exactly one control and the respective label. Multiple group elements can be grouped together. This group then also has a label.
The SmartForm control aggregates groups, and a group aggregates groupElements. The groupElements themselves aggregate elements of type sap.ui.core.Control.
The SmartForm control uses a ResponsiveGridLayout that can be adjusted. The following properties are exposed in the aggregation layout:
labelSpanL, labelSpanM, labelSpanS
emptySpanL emptySpanM, emptySpanS
columnsL, columnsM
breakpointL, breakpointM
Alternatively, ResponsiveLayout can be used to display the fields next to each other with a label on top. This type of layout can be defined using the useHorizontalLayout property.
The form will be embedded in an sap.m.Panel if the expandable property is set. Using this property, the form can also be collapsed and expanded.
The aggregation layout of a group can be used to define a GridData layout. With this layout, the span of a single group can be changed to allow this group to have more than one column. Moreover, a line break can be inserted to display the group in a new line.
The SmartForm control uses a toolbar for displaying the title of the form and the following buttons (if configured):
Display/Edit (editTogglable property )
Alternatively, the custom toolbar can be used (customToolbar aggregation). The SmartForm control will then replace the standard toolbar with the custom toolbar and add the title and the buttons if requested.
The following table shows a selection of the annotations used by the SmartForm control:
Element |
Annotation |
Further Distinction |
Comment |
---|---|---|---|
Field Label |
sap:label |
Text used for group element label |
|
Mandatory attribute |
Nullable='false' |
||
Field control |
sap:field-control |
||
Display format |
sap:display-format |
UpperCase NonNegative |
To enable key user adaptation settings, the following prerequisites have to be fulfilled:
Use of stable IDs for every Group, GroupElement, and field in the XML view
The adaptation settings use control IDs to identify the entities that can be modified.
Use of the entityType property
The property determines the entity type of the OData service defining the fields that can be added to the form.
Fields that must not be available on the adaptation dialog can be listed in the ignoredFields property. Separate the property names by commas without using spaces.
The SmartForm control allows you to define a default configuration for the SmartField control. This configuration is done using the customData aggregation. The complete customData aggregation is copied to the SmartField control.
Also, the value for the defaultDropDownDisplayBehaviour key is set to displayBehaviour in the SmartField configuration if it has not been defined for the SmartField control itself.