Updated: February 22, 2023

Smart Form

sap.ui.comp.smartform.SmartForm

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:

Components

The smart form consists of a toolbar and a form.

Toolbar

The following options are provided:

  1. Expand/collapse button
  2. Title
  3. App-specific actions

Expand/Collapse Button

The expand/collapse button is optional (properties: expandable,
expanded). It shows or hides the form.

Expanded smart form
Expanded smart form
Collapsed smart form
Collapsed smart form
Guidelines

  • Do not use the expand/collapse button in object pages.
  • Even in other places, it is not usually recommended.

Title

The title is optional (property: title).

App-Specific Actions

App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

Guidelines
For custom actions, follow the guidelines for object handling.
Developer Hint
The smart form can add its title to the custom toolbar.

Form

The form consists of form groups (sap.ui.comp.smartform.Group) and a layout.

Form Groups

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
A semantic form element in edit mode
The same semantic form element in display mode
The same semantic form element in display mode
Guidelines
When using more than one control in a form element, consider the semantic form element. In most cases, it will be the better choice.
Developer Hint

  • 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

The layout defines how the form groups and form elements are placed on the screen, depending on the available width (aggregation: layout). There are two layout options: column layout and responsive grid layout.

Guidelines

Behavior and Interaction

Display and Edit Mode

In display mode, the line height for each row is reduced (property: editable). This results in less white space between two lines of text. This setting is passed to all smart fields inside the smart form, which then also switch automatically.

Developer Hint
Controls other than the smart field need to be adapted manually.

Validation

The smart form offers two validation modes: standard and asynchronous (property: validationMode). The standard validation mode works only for smart fields and only with synchronous validation.

Developer Hint
Always use the asynchronous mode: it works for all form elements, not only for smart fields.

Responsiveness

The smart form acts exactly like the embedded controls. For details, see:

Size S
Size S
Size M
Size M
Size L
Size L
Size XL
Size XL

Example

Smart form in edit mode
Smart form in edit mode
The same smart form in display mode
The same smart form in display mode

Top Tips

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

Implementation