Intro

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

• Form – sap.ui.layout.form.Form (API)
• Simple form – sap.ui.layout.form.SimpleForm (API)

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

• The layout and structure are defined by the content that is entered.
• Form containers and form elements are created automatically according to the content type.
• A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
• All other controls following this label will be assigned to its row (form element).

Types

There are three types of forms:

• Display-only: the data is presented only as label-value field pairs without editable fields.
• Editable: the data is presented as label-input field pairs, so users can enter data.
• Mixed: some fields are editable and some are not.

Responsiveness

The default settings of the control are not ideal for all possible use cases. Instead, applications can use one of the various layouts for the S, M, L and XL sizes.

Column Layout

Responsive Grid Layout

The responsive grid layout is a form using a responsive grid. Depending on the available space, the groups are rendered in one or multiple columns, and the labels are rendered in the same row as the fields or above the fields. This behavior can be influenced by the properties of this layout control.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is the column layout, not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

Breakpoints

Label-Field Ratio

Size S (Smartphones and Dialogs)

Size M

Size L

Size XL

Layout

One Page, One Form

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Size M (Tablet) – Full Screen

Size L (Desktop Screens)

Size XL (Desktop Wide Screens)

Components

The following UI elements can be placed in the form container:

• Button and segmented button
• Checkbox
• File uploader
• Icon
• Image
• Input controls, such as the combo box, multi-combo box, date picker, date/time picker, dynamic date, time picker, input field, multi-input field, and mask input.
• Object number
• Object status
• Progress indicator
• Radio button and radio button group
• Rating indicator
• Search field
• Select
• Slider
• Step input
• Switch
• Text and text area

Guidelines

• Order the form logically from a user’s perspective. For example, ask for a user’s name before asking them for their address.

• Group related information by using form and group titles.

• Use Column layout instead of Responsive Grid layout, if possible.

• Try to arrange form groups (especially in size L and XL) in a way that the form:

  • Is easy to read and understand.
  • Does not contain too much white space (split groups if necessary).

• If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.

• Less is more: try to minimize the number of labels and their corresponding fields as much as possible.

• If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Label

To avoid truncation, labels within forms wrap automatically.

Always aim to keep your labels as concise as possible. Remember that a label is not a help text. It must be meaningful, succinct, short, and descriptive. The purpose of the wrapping feature is to make the full label text legible and to help avoid unnecessary use of abbreviations. It is not intended as a fallback for very long labels.

• A label is not a help text. Give each field a meaningful label. Make labels succinct, short and descriptive.
• The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property, and the asterisk will be inserted automatically.
• At the end of the label, the form container automatically inserts a colon (:), which is triggered by the style sheet. Do not write the colon manually in the label text.
• Use default settings for labels. (For example, labels are not supported for manual bold formatting.)

Label Alignment

• We generally recommend placing the label above the field. This is the most usable option, since it best supports the reading flow and avoids unnecessary eye movements.
• If there is enough space on the screen, you can right-align the labels next to the value. Right-aligned labels minimize the gap between the label and field, and give the eye one line to scan along. Only place labels next to the value if there is also enough space to allow for longer labels in other languages.

Empty State Indicator

Unit of Measurement

Amount Alignment

When the form is in edit mode (label-value field pairs with editable and non-editable fields), right-align amounts.

When a form is in display mode (label-value field pairs without editable fields), left-align amounts to avoid large gaps between the labels and values, and to improve readability.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page (for example, if the user selects a list item in a list-detail layout and then clicks the the Back or Home button). For details about how the message is delivered and what text you can use, see Message Handling.

Form Field Validation

Input Assistance

Intelligent systems can help users by recommending appropriate content or suggesting an action or input the user may “prefer”. The system assists the user by entering data or filtering data. Typical examples might be a search phrase suggestion, an appropriate form template, or a set of suggested default values for certain fields, based on the user input and interaction history.

For more information, see Designing Intelligent Systems – Input Assistance.

Error Prevention

Help the user to avoid errors by using input types (sap.m.InputTypes) and mask input (sap.m.MaskInput). The input fields automatically get a specific format, which helps prevent the user from making invalid entries.

Always start with the least complex control (for example, use select instead of value help if the user needs to select only one item from a short list). Use more intricate controls only if the use case really requires it.

Placeholder

Provide a placeholder (or input prompt) as a short hint (a word or short phrase) to help the user with data entry. A hint can be a sample value or a brief description of the expected format.

Avoid using the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible.

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

Toolbar

The form supports actions on form toolbar level as well as on group header level. Application development teams can add actions such as ‘Edit’, ‘Save’ or ‘Cancel’. If there is an action that only applies to the specific group on group level, it can only be added on the group header level of the specific group.

Expanded/ Collapsed Form

The form supports expand / collapse buttons on a per-group level. However, we recommend avoiding the usage of expand / collapse behavior on a form.

Resources