Lead:  Liav Nadler

Issues to cover

• Form-level elements

  • Status tags

  • Messages

• Action buttons

  • Distances between buttons (if more than 2)

• Guidance

  • Form instructions

  • Field help

  • Ask Femi about web SDK form guidance

• Autosave

Description

A form is a collection of input fields, allowing users to enter data that is then sent for further processing.
Forms may appear in workspaces, dialog popups, popovers,wizards,filter panes, details panes and cards.

...

• A form consists of two areas: the input area and the action area.

• The input area may contain any set of input fields, including text fields, dropdown menus, checkboxes, radio buttons etc.

• The action area usually consists of at least two buttons: a submit button (Save, or Create, or Update etc.) and Cancel.

• For form with inline input see Inline input

The Input Area

• Field Where possible, field labels will appear on top of above the input field (for example, above a text field or a set of radio buttons).

• Where relevant, a red mandatory indicator (*) will show next to the label.

• Where relevant, a help icon will appear next to the label (aligned to the right side of the field, if possible).

• A collection of related fields can be grouped into a section. For example, fields like Email and Phone can be found under a section called Contact Information.

• Two or more fields may be dependent. In this case:

  • Any dependent field will appear below the original (independent) field.

  • selecting a value for a dependent field will be possible only if there is a value in the original (independent) field.

The Action Area

• The action area will always be visible:

  • In case the form takes up the entire workspace, the action area will appear at the top of the page (see examples below).

  • In any other case, the action area it will appear below the form:

    • In dialog popups, popovers,wizards,filter panes, details panes and cards, the action area will appear at the bottom of the container.

    • In workspaces:

      • If the form does not exceed the height of its container, the action area will appear directly below the last field of the form.

      • If the form exceeds the height of its container, the action area will stick to the bottom of the container, allowing users to scroll the form above it. Add example

• Primary buttons Buttons for main actions will be aligned to the right. Additional buttons, such as Clear or Reset will be aligned to the left.

...

• Forms can have 3 states:

  • Idle - this is the default state when entering a form. In On this casestate, exiting the form will not save it.

  • Dirty Edited state - the state of a form after making changes but before clicking the Save button. In On this casestate, exiting the form will trigger an error a confirmation message (see below).

  • Saved - the state of a form after clicking the Save button.

...

• Clicking the submit button (Save / Create / Update etc.) switches the form to the saved state, and sends the data for further processing.

• In case of creating or updating an entity, the user may be automatically directed to the original page (e.g., list of entities).

• In case of a dialog popup or a popover, clicking the submit button will also close the popup / popover.

In case of a wizard:

• Clicking a Next / Previous button may also direct the user to the next / previous page.

Clicking the Done button may also close the wizard

.

• Clicking the Cancel button will close the dialog popup / popover, or automatically direct the user to the original page, without saving the form.

Validations and errors

There are two types of validations related to forms: input field validation and form validation.

...

Field Validation

• This type includes all validations related to specific inputs, such as text fields, text areas, sets of checkboxes, etc. (see Field Validation).

• The most common input-level errors are:

  • Invalid input, including invalid characters, invalid format and out-of-range data.

  • Missing mandatory input, where a required field was left blank.

• Field validations for invalid characters or invalid format occurs while typing (“onkeydown”).

• Field validations for out of range data or missing mandatory input occurs when a field looses focus (“onblur”).

• When invalid input or missing mandatory input was detected, the field changes its status to error.

• In some cases, the entered value is valid, but may call for a special attention (for example: a very large value). In this case, the field will change its status to warning, but will not prevent the form from being submitted.

Form Validation

• A form cannot be saved or submitted if one or more of its fields are in error state. Here is a typical flow:

  • When entering a form, the Save button is disabled.

  • On updating a any field, the Save button becomes enabled.

  • In case of an input error the Save button becomes disabled (an additional form-level indication may appear). Only after the error was resolved, the Save button is enabled again.

  • After clicking the Save button:

    • it becomes disabled again,

    • a toast message may appear, indicating that the form was saved.

• This flow is also relevant when the form is in a dialog popup. In this case, the Cancel button is always enabled.

• In case a single Save button applies to multiple areas (tabs, master items in a master-detail layout, etc.), updated values will be saved in a local storage even before clicking the Save button.

• In this case, if the user updated a value in the first area, navigated to another area and went back to the first area, all updated values will remain intact.

...

• Creating or updating entities (e.g., users, roles, channels).

• Configuration pages (e.g., services level indicators, storage retention periods).

Don’t use:

• When?

General

• In case of large number of fields, group related fields together, providing a clear title to each group.

• Make sure there is a natural tab order between fields.

• Make sure that label texts are not selectable.

Examples

Update screen

Accessibility compliance

Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility

text highlight when using a keyboard + using arrows when in edit mode (left, up or home to set the insertion point at the beginning; right, down or end to set it at the end).

Design

...