Lead: Liav Nadler
| Status | ||||
|---|---|---|---|---|
|
| Table of Contents |
|---|
Issues to cover
Validations
Invalid values
Blank mandatory fields
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 a further processing. store, retrieve, and update data.
Forms may appear in workspaces, wizards or dialog popups, filter panes and cards.
...
Basic Flow
There are two basic form types:
Configuration forms - allowing users to change predefined settings.
Entity forms - allowing users to create and edit entities. In this case, most of the fields in the initial form are blank by default.
Users can fill in form fields in any order before saving or applying the form.
While filling in the form
After filling in a form, clicking the Save button (in configuration pages) or the main button in dialogs triggers a validation (see below).
Usage & Behavior
...
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 |
 |  |
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 components, input fields including text Text fields, dropdown Drop-down menus, checkboxes Checkboxes, radio Radio buttons etc.
Related fields can be grouped into sections. For example, we may find Email and Phone fields under a section called Contact Information.
The action area usually consists of two buttons: Save for submitting the form and Cancel for resetting the form or closing the popup (see interactions below).
In case the form fills the entire area of a workspace, the action area will appear at the top of the page. In any other case, it will appear below the form and always be visible:
Within the container
Exceeds the container
Placement and Positioning
Forms may appear in workspaces, widgets, wizards or dialog popups.
In case the form takes the entire area of a workspace, the action area will appear at the top of the page, opposite to the page title.
If the form takes only part of the workspace (e.g., inside a dialog or a widget), the action area will appear at the bottom of the container. In this case, the action area will also be sticky, to allow users scrolling along the form, without hiding the action buttons.
Fields
...
Field labels will appear on top of the input field (e.g., a text field or a set of radio buttons).
...
Where relevant, a help icons will appear next to the label.
...
In some cases, two or more fields will be dependent. In this case, selecting a value for the dependent fields will not be possible until a value exists in the main field.
...
In configuration forms it is common the most or all fields have default values.
States
Forms can have 3 states:
Idle - this is the default for creation forms. Exiting the form without changing anything will not add that entity.
Dirty state - a form switches to this state after making changes to the idle form.
Saved - after clicking the Save button.
When first opening a configuration form it is defined as saved. Updating any of the fields, switches it to dirty state.
Interaction
Forms has no intrinsic interactions. For component-specific interactions see the documentation of that component.
Validations and errors
There are two types of validations related to forms: field validation and form validation.
Field Validation
This category includes all validations that are related to specific inputs, including text fields, text areas, sets of checkboxes, date and time pickers, etc.
The most common input-level errors are:
Invalid data, including invalid characters, invalid format and out-of-range values.
Missing mandatory, 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 occurs when a field looses focus (“onblur”).
When invalid data or missing mandatory field 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.
For more information, please refer to LUX Field Validation page.
Form Validation
A form cannot be saved / submitted if one or more of its fields are in error state.
Here is a typical saving flow:
When first entering a form, the Save button is disabled.
On updating a field, the Save button becomes enabled.
In case of a field 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.
Saving “dirty data” in local storage
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.
Edge case: navigating to another area of the form while some fields has errors
In case the user tries to navigate to another area of the form, while the current area has errors, a message popup will appear, allowing him to either continue, while loosing all the updated data, or cancel.
...
Edge case: exiting an updated form
In case the user tries to navigate away from a form after updating one or more fields, a message popup will appear, allowing her to either save and exit, exit without saving, or cancel.
...
Best practices
Use when:
Values have a distinct order.
There is a default value.
There are at least three possible values.
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 that label texts are not selectable.
Make sure there is a natural tab order between fields.the Action area, which consists of:
a submit button, such as Save, Create, or Edit.
a Cancel button.
additional actions, where needed.
The Input Area
For specific form elements, browse the Components section in LUX.
Where possible, field labels will appear above the input field.
Where relevant, a red mandatory indicator (*) will be 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).
...
The Action Area
The action area will always be visible.
Action buttons will be aligned to the right.
Where the action area appears at the bottom of the main workspace, it will be separated by a horizontal line.
Placement and positioning
In most cases, the action area will appear below the form.
Within the main workspace, where the form does not exceed the height of the container,
the action area will appear beneath the last form field.
Within the main workspace where the form reaches the bottom of the container, and within Popups and other modals:
the action area will stick to the bottom of the container.
the form above 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 |
|---|---|---|---|
 |  |  |  |
States
Forms have two possible states:
State | Usage |
|---|---|
Idle / Saved | Applies when first entering a form or after saving it. In this case, the submit button is disabled. |
Edited | Applies after changes are made to a form, but before saving or submitting. In this case:
|
The Cancel button is always enabled in all states.
Interaction
The submit button
Clicking the submit button sends the data for further processing. (For error handling see Validations and errors below).
In the main workspace, if the form was submitted successfully a success Toast will appear.
If the form was triggered from a parent page, the user will automatically be return to that page.
For 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 may close the Filter pane, depending on the pin state.
Validations and errors
Validation triggers
There are two types of validation which may affect a form:
Type | Trigger events | Examples | Notes |
|---|---|---|---|
Client-side validation |
|
| Client-side issues are either resolved immediately (for example, on deleting an invalid character) or when the field loses focus. |
Server-side validation |
| 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.  |
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 |
|---|---|
 Short form, where necessary:  |  Short form, where necessary:  |
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
 |  |
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 |
|---|---|
 |  |
Best practices
Use for:
Creating or updating entities, such as users, roles, and channels.
Configuration, such as service-level indicators or storage retention periods.
General
Form fields should be arranged in one column. Closely related fields (e.g. First name and Last name) may appear side by side.
Collections of related fields should be grouped into sections. For example, fields such as Email and Phone may be grouped under a Contact Information section.
Examples in different containers
Main workspace | Widget | Wizard | Details pane |
|---|---|---|---|
 |  |  |  |
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>>