Smart Form

The sap.ui.comp.smartform.SmartForm control makes it possible to render a form. 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.

For more information about this control, see the API Reference in the Demo Kit and the sample in the Explored app in the Demo Kit.

Overview

The SmartForm control displays form content. If used in combination with the SmartField control and OData metadata annotations along with additional configuration, the control allows you to create a form with minimal effort.

The SmartForm control supports the following features:

Adaptation settings
A key user can adapt the form for all users in one client by doing the following:
- 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.

Note 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.

Note 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 is displayed.

Details

Groups

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 group elements. The group elements themselves aggregate elements of type sap.ui.core.Control.

The following example shows the SmartForm control and its entities:

#!xml

<smartForm:SmartForm id="MainForm" title="General Data"
				entityType="Header, Tax" editTogglable="true" expandable="true"
				expanded="true" ignoredFields="AccountingDocumentCategory"
				checkButton="true">
	<smartForm:customData>
		<core:CustomData key="suppressUnit" value="false" />
		<core:CustomData key="dateFormatSettings" value='\{"style":"short"\}' />
		<core:CustomData key="defaultDropDownDisplayBehaviour" value='descriptionAndId' />
	</smartForm:customData>
	<smartForm:customToolbar>
		<Toolbar height="3rem">
			<Text text="Custom Toolbar with a header text" />
			<ToolbarSpacer />
			<Button icon="sap-icon://settings" />
			<Button icon="sap-icon://drop-down-list" />
		</Toolbar>
	</smartForm:customToolbar>
	<smartForm:Group id="GeneralLedgerDocument" label="General Ledger Document"
					expandable="true">
		<smartForm:layout>
			<layout:GridData span="L4 M4 S4" />
		</smartForm:layout>
		<smartForm:GroupElement id="GeneralLedgerDocument.CompanyCode">
			<smartField:SmartField value="{CompanyCode}"
							enabled="true" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="GeneralLedgerDocument.AccountingDocument">
			<smartField:SmartField value="{AccountingDocument}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="GeneralLedgerDocument.FiscalYear">
			<smartField:SmartField value="{FiscalYear}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement
						id="GeneralLedgerDocument.AccountingDocumentType">
			<smartField:SmartField value="{AccountingDocumentType}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement
						id="GeneralLedgerDocument.AccountingDocumentHeaderText">
			<smartField:SmartField value="{AccountingDocumentHeaderText}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement
						id="GeneralLedgerDocument.AccountingDocumentTypeName">
			<smartField:SmartField value="{AccountingDocumentTypeName}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="GeneralLedgerDocument.AmountInCoCodeCrcy">
			<smartField:SmartField value="{AmountInCoCodeCrcy}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="GeneralLedgerDocument.CoCodeCurrency">
			<smartField:SmartField value="{CoCodeCurrency}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="GeneralLedgerDocument.LedgerGroup">
			<smartField:SmartField value="{LedgerGroup}" />
		</smartForm:GroupElement>
	</smartForm:Group>
	<smartForm:Group label="Dates" id="Dates">
		<smartForm:layout>
			<layout:GridData span="L3 M3 S3" />
		</smartForm:layout>
		<smartForm:GroupElement id="Dates.DocumentDate">
			<smartField:SmartField value="{DocumentDate}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="Dates.PostingDate">
			<smartField:SmartField value="{PostingDate}" />
		</smartForm:GroupElement>
	</smartForm:Group>
	<smartForm:Group label="Reversal" id="Reversal">
		<smartForm:layout>
			<layout:GridData span="L3 M3 S3" />
		</smartForm:layout>
		<smartForm:GroupElement id="Reversal.ReversalDocument">
			<smartField:SmartField value="{ReverseDocument}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="Reversal.ReversalReasonName">
			<smartField:SmartField value="{ReversalReasonName}" />
		</smartForm:GroupElement>
	</smartForm:Group>
	<smartForm:Group label="Administrative Data" id="AdministrativeData">
		<smartForm:layout>
			<layout:GridData span="L3 M3 S3" linebreak="true" />
		</smartForm:layout>
		<smartForm:GroupElement id="AdministrativeData.CreatedByUser">
			<smartField:SmartField value="{CreatedByUser}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="AdministrativeData.CreatedByUserName">
			<smartField:SmartField value="{CreatedByUserName}" />
		</smartForm:GroupElement>
		<smartForm:GroupElement id="AdministrativeData.CreationDate">
			<smartField:SmartField value="{CreationDate}" />
		</smartForm:GroupElement>
	</smartForm:Group>
</smartForm:SmartForm>

Layout

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.

Group Layout

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.

Toolbar

The SmartForm control uses a toolbar for displaying the title of the form and the following buttons (if configured):

Display/Edit (editTogglable property )
Check (checkButton property)
Adaptation settings

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.

Key-User-Specific Adaptation

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.

Integration of SmartField Control

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 controls.

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.