Lead:  Liav Nadler

Description

A form is a collection of input fields, allowing users to enter data that is then sent for further processingstore, retrieve, and update data.

Forms may appear in workspaces, dialog popups, popovers,wizards,filter panes, details panes and cards.

...

either in the main workspace or within other containers, such as Dialog popups, Popovers,Wizards,Filter panes, Details panes and Cards.

In a workspace	In a Dialog popup
Image Added	Image Added

Usage & Behavior

Structure

A form consists of two areas:

• the input area and the action area.The input area may contain Input area, containing any set of input fields , including text Text fields, dropdown Drop-down menus, checkboxes Checkboxes, radio Radio buttons etc.

• The action the Action area, which consists of:

  • a submit button

  (

  • , such as Save, Create,

  Update etc.) and

  • or Edit.

  • a Cancel button.

  • additional actions,

  if

  • where needed.

  In dialog popups, wizards,filter panes, details panes and cards, an additional Cancel button may appear.

The Input Area

• For specific form elements, browse the Components section in LUX.

• Where possible, field labels will appear 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 labelbe shown to the right of the label.

  • Where a majority of fields are mandatory, a message will appear above the form indicating that all fields are mandatory unless otherwise specified.

• Where relevant, a help icon will appear next to the label (aligned to the right side of the field, if possible).For forms with inline inputs, see Inline Inputs.

...

The Action Area

• The action area will always be visible.

  In case the form takes
• up the entire workspace,

  Action buttons will be aligned to the right.

• Where the action area

  will appear

  appears at the

  top

  bottom of the

  page (see Examples below).In any other case, the action area will appear below the form,

  main workspace, it will be separated by a horizontal line.

Placement and positioning

In

...

most cases, the action area will appear

...

In workspaces:

...

below the form.

• Within the main workspace, where the form does not exceed the height of

  its

  the container,

  • the action area will appear

    below

    beneath the last form field

    of the form

    .

    If

• Within the main workspace where the form

  exceeds

  reaches the

  height

  bottom of

  its

  the container, and within Popups and other modals:

  • the action area will stick to the bottom of the container

    , allowing users to scroll

    .

  • the form above

    it.

...

...

• Buttons for main actions will be aligned to the right. Buttons for secondary actions, such as clear or delete will be aligned to the left.

...

States

• Forms can have two states:

  • Idle / Saved - when just entering a form or after clicking the submit button. In this state:

    The

    will have a scrollbar.

In some cases, where a form uses the entire workspace and is shown across multiple containers, the action area may appear at the top of the workspace.

Main workspace - less than two thirds height	Main workspace - more than two thirds height	Popup	Entire workspace - form across multiple containers
Image Added	Image Added	Image Added	Image Added

States

Forms have two possible states:

...

Exiting the form will not save it.

Edited - after making changes but before clicking the submit button. In this state:

...

The submit button is enabled.

...

...

...

The Cancel button is always enabled in all states.

Interaction

The submit button

• Clicking the submit button : sends the data for further processing. (

  for

  For error handling see Validations and errors below).

• On workspace forms:

  If

  In the main workspace, if the form was submitted successfully

  ,

  a success

  toast

  Toast will appear

  (see Toasts)

  .

  • If the form was triggered from a parent page, the user will automatically be

    directed back

    return to that page.

• For

  dialog popups, popovers,wizards,filter panes, details panes and cards, see the corresponding component documentation.

  Clicking the Cancel button will close the corresponding component (if not pinned), without saving the data (a confirmation popup may appear)forms inside containers, refer to the corresponding pattern documentation. For example:

  • clicking the submit button in a Dialog popup closes it.

  • clicking the Apply button on a Filter pane applies the filter and disables the button.

The Cancel button

• Clicking Cancel on a form with unsaved changes may trigger a warning message, where necessary.

• In the main workspace clicking Cancel will return to user to the parent page, without saving the data.

• For forms inside containers, refer to the corresponding pattern documentation. For example:

  • clicking Cancel will close Popups and Popovers.

  • clicking Cancel may close the Filter pane, depending on the pin state.

Validations and errors

...

For input-specific validations see Field Validation.

...

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

• When entering a form, the submit button is disabled (the Cancel button is always enabled).

• On updating any field, the submit button becomes enabled.

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

• After clicking the submit button:

  • it becomes disabled,

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

...

This flow is similar where the form is in a dialog popup, but in this case, clicking the submit button closes the popup.

...

When a form has a single required field, the validation will appear only after the user clicks the submit button.

...

Validation triggers

There are two types of validation which may affect a form:

Type	Trigger events	Examples	Notes
Client-side validation	Moving focus away from a field. Clicking the submit button on the form.	Invalid values. Invalid formats. Blank mandatory fields.	Client-side issues are either resolved immediately (for example, on deleting an invalid character) or when the field loses focus.
Server-side validation	Clicking the submit button (or Next button in Wizards). Clicking the Save button of an Inline input.	When logical problems are detected, e.g. trying to create an object with a name that already exists.	In some cases, a Dialog popup may appear with additional instructions required to complete the action. When validation takes more than a few seconds, a Progress indicator will appear in a modal. Image Added

Presentation of errors and warnings

Errors and warnings are shown:

• against individual form fields - see Field validation for more information.

• as a message in the action area - see details below.

While the form contains an error, the submit button will be disabled.

...

A dedicated message will appear to the left of the action area. It will include:

• a status icon. If both errors and warnings are present, an error icon will be used.

• descriptive text including a link, and showing the total number of errors and warnings.

Error message	Warning message
Image Added Short form, where necessary: Image Added	Image Added Short form, where necessary: Image Added

Clicking the link opens a Popover, containing additional information. The popover includes:

• general introductory text describing the number of issues and how to resolve them.

• a list of issues, with errors appearing before warnings. Each issue will show:

  • an error or warning status icon.

  • a description of the issue and how to resolve it.

  • a Resolve or Review link, where relevant. Clicking the link closes the popover and sets the focus on the corresponding form field. The form may auto-scroll where necessary.

Examples

Image Added

Image Added

Leaving an incomplete form

When the user navigates away from a form in the Edited state (after updating one or more fields), or while there are errors on the form:

• a Message popup will appear. See Common messages repository for appropriate message text.

• the user will choose to either keep editing the form or leave and discard changes.

In case of unsaved changed	In case of form errors
Image Added	Image Added

Best practices

Use for:

• Creating or updating entities (, such as users, roles, and channels etc.).

• Configuration (services , such as service-level indicators , or storage retention periods etc.).

General

• In general, form Form fields should have be arranged in one column. Closely related fields (e.g. , first First name and last Last name) can may appear side by side.

• Collections of related fields should be grouped into sections. For example, fields like such as Email and Phone may be found grouped under a Contact Information section.

Examples in different containers

Main workspace	Widget	Wizard	Details pane
Image Added	Image Modified	Image Added

Image Removed

Image Added

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

...

Zeplin link

...

Screen thumbnail

...

.

...

<<Screen with 200 width>>

Code

<<a box containing the code - discuss with Femi>>