Form Layout

SAIL Design System guidance available for Form Layout When you need to collect data in a structured, intuitive way, use the form layout. Learn how to use the form layout to simplify data collection and create forms that work as seamlessly as they look.

Function

a!formLayout( titleBar, isTitleBarFixed, showTitleBarDivider, backgroundColor, showWhen, contents, contentsWidth, focusOnFirstInput, buttons, isButtonFooterFixed, showButtonDivider, validations, validationGroup )

Displays any arrangement of layouts and components beneath a header and above buttons. Use this as the top-level layout for start and task forms.

See also: Wizard Layout

Parameters

Usage considerations

Title bar options

Related style guidelines: Title bar guidelines

For the title bar, you can choose either a simple header, full header, image header or sidebar template. See the SAIL Design System for more information about when to choose each template.

You can also just enter text as a string. For example, titleBar: "Add Product".

Additionally, you can configure a custom header using billboard and card layouts.

Contents width in record action dialogs

Related style guidelines: Use "Full" width when displaying forms in dialogs, Use one narrow column for the form content, Don't add additional columns to center form content

If you are planning to display this component in a record action dialog, keep in mind that the dialog size is set in the record type and that the step contents width is set in the wizard layout. Open the record action to make sure the contents width works with the selected dialog size.

We recommend setting the contentsWidth parameter to "FULL" when displaying this component in a dialog.

Dynamic defaults

Some parameters have dynamic defaults that automatically adapt based on if they are displayed in a dialog or not.

The following table details the behavior of these parameters when they are not specified in the expression.

Specifying any of these parameters in the expression will override this behavior.

Using the focusOnFirstInput parameter

If focusOnFirstInput is true, the focus will be applied to the first component that is one of the following:

• Checkbox
• Date
• Date and Time
• Decimal
• Dropdown
• Encrypted Text
• File-Upload
• Integer
• Multi-Dropdown
• Paragraph
• Picker Components
• Radio Button
• Text

Responsiveness of sidebar template

Related style guidelines: Sidebar template guidelines

The sidebar is fully responsive and its appearance will change based on the screen width.

On narrow screens, the sidebar automatically displays as a header at the top of the interface. This includes when it displays in dialogs that use Medium width or narrower.

When the sidebar displays as a header, the image is hidden, but any components in the additionalContents parameter will still be displayed below the secondary text.

Sidebar on a wider screen:

Sidebar on a narrower screen:

Using a pane layout in a form layout

Related style guidelines: Turn off pane dividers in forms with header and button footer dividers

You can place a single pane layout within the contents parameter of a form layout to create forms with multiple, independently scrolling columns of content.

When a pane layout is used in a form layout:

• The form's header and button footer will span across the top and bottom of all panes.
• The contentsWidth parameter of the form layout will always use "FULL". The panes will always occupy the entire width of the form's content area.

Heading levels for headingTag parameters

In form layouts, the title bar title uses "H1" for the heading level. When you use the headingTag parameter in components such as box and section layouts, use "H2" for the highest-level headings.

Back buttons in activity chained tasks

For a back button to appear in activity-chained tasks a button layout must be present in the form.

Using the validations parameter

Use form validation messages for problems that are not specific to a single component.

Examples

Basic form

Use the interactive editor below to test out the example code.

Form with background color

To experiment with examples, copy and paste the expression into an interface object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
a!localVariables(
  local!data:a!map( firstName:null, lastName:null, email:null, country:null, orgName:null, title:null ),
  a!formLayout(
    titleBar: a!headerTemplateSimple(
      title: "REGISTER NOW",
      secondaryText:"Enter your details below to register for the conference",
    ),
    backgroundColor: "#f8f6f0",
    contentsWidth: "MEDIUM",
    contents: {
      a!sectionLayout(
        label: "YOUR DETAILS",
        labelSize: "SMALL",
        labelColor: "STANDARD",
        contents: {
          a!cardLayout(
            contents: {
              a!columnsLayout(
                columns: {
                  a!columnLayout(
                    contents: {
                      a!textField(
                        label: "First name",
                        value: local!data.firstName,
                        saveInto: local!data.firstName
                      )
                    }
                  ),
                  a!columnLayout(
                    contents: {
                      a!textField(
                        label: "Last name",
                        value: local!data.lastName,
                        saveInto: local!data.lastName
                      )
                    }
                  )
                }
              ),
              a!textField(
                label: "Email address",
                labelPosition: "ABOVE",
                value: local!data.email,
                saveInto: local!data.email,
                marginAbove: "STANDARD"
              ),
              a!dropdownField(
                label: "Country",
                labelPosition: "ABOVE",
                placeholder: "Select your country of residence",
                choiceLabels: {"United States", "United Kingdom", "Canada"},
                choiceValues: {1, 2, 3},
                value: local!data.country,
                saveInto: local!data.country,
                marginAbove: "STANDARD"
              ),
              a!textField(
                label: "Organization name",
                labelPosition: "ABOVE",
                value: local!data.orgName,
                saveInto: local!data.orgName,
                marginAbove: "STANDARD"
              ),
              a!textField(
                label: "Job title",
                labelPosition: "ABOVE",
                value: local!data.title,
                saveInto: local!data.title,
                marginAbove: "STANDARD"
              )
            },
            style: "#f2ede1",
            shape: "SEMI_ROUNDED",
            padding: "STANDARD",
            marginBelow: "STANDARD",
            borderColor: "#d4cebe"
          )
        },
        marginAbove: "STANDARD"
      )
    },
    buttons: a!buttonLayout(
      primaryButtons: {
        a!buttonWidget(
          label: "Register",
          icon: "arrow-right",
          submit: true,
          validate: true,
          style: "SOLID",
          color: "#DEB03D"
        )
      },
      secondaryButtons: {
        a!buttonWidget(
          label: "Cancel",
          submit: true,
          validate: false,
          saveInto: {},
          style: "OUTLINE",
          color: "#000000",
          value: true
        )
      }
    ),
    showButtonDivider: false
  )
)

Displays the following:

Empty form with panes

This example shows an empty pane layout within a form layout.

To experiment with this example, copy and paste the expression into an interface object, or select the Form with Panes template from an empty interface object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
a!formLayout(
  titleBar: a!headerTemplateFull(
    title: "Form",
    secondaryText: "Enter your details",
    secondaryTextColor: "SECONDARY",
    backgroundColor: "ACCENT"
  ),
  showTitleBarDivider: false,
  contents: {
 a!paneLayout(
      panes: {
        a!pane(contents: {}, width: "NARROW_PLUS"),
        a!pane(contents: {}, width: "AUTO")
      }
    )
  },
  buttons: a!buttonLayout(
    primaryButtons: {
      a!buttonWidget(
        label: "Submit",
        submit: true,
        style: "SOLID",
        loadingIndicator: true
      )
    },
    secondaryButtons: {
      a!buttonWidget(
        label: "Cancel",
        value: true,
        saveInto: ri!cancel,
        submit: true,
        style: "OUTLINE",
        validate: false
      )
    }
  ),
  showButtonDivider: true
)

Pane layout in form layout

This example shows a document review form created with a pane layout in a form layout. It displays the following interface.

To experiment with examples, copy and paste the expression into an interface object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
a!formLayout(
  titleBar: a!headerTemplateSimple(
    title: "Review Form Data",
    secondaryText: "Review the information extracted from the submitted document. Compare the details below with the form on the left. Correct any fields that are inaccurate before submitting.",
    secondaryTextColor: "STANDARD"
  ),
  showTitleBarDivider: true,
  contents: {
    a!paneLayout(
      panes: {
        a!pane(
          contents: {
            a!documentViewerField(
              labelPosition: "COLLAPSED",
              /* Replace this with a document constant in your environment */
              /* document: cons!DOC_EXAMPLE, */
              height: "TALL"
            )
          },
          width: "AUTO",
          padding: "NONE"
        ),
        a!pane(
          contents: {
            a!textField(
              label: "Name"
            ),
            a!textField(
              label: "Street Address"
            ),
            a!textField(
              label: "City"
            ),
            a!dropdownField(
              data: null,
              label: "State",
              placeholder: "Select a state"
            ),
            a!integerField(
              label: "Zip Code"
            ),
            a!textField(
              label: "Phone Number"
            ),
            a!textField(
              label: "Email"
            ),
            a!paragraphField(
              label: "Supporting Information",
              height: "TALL"
            ),
            a!dateField(
              label: "Start Date"
            ),
            a!dateField(
              label: "End Date"
            )
          },
          width: "NARROW_PLUS",
          backgroundColor: "GRAY"
        )
      },
      showPaneDividers: false
    )
  },
  buttons: a!buttonLayout(
    primaryButtons: {
      a!buttonWidget(
        label: "Submit",
        style: "SOLID"
      )
    },
    secondaryButtons: {
      a!buttonWidget(
        label: "Cancel"
      )
    }
  ),
  showButtonDivider: true
)

Feature compatibility

Old versions

There are older versions of this interface component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Related Patterns

The following patterns include usage of the Form Layout.

• Add Multiple Validation Rules to One Component (Validation): Enforce that the user enters at least a certain number of characters in their text field, and also enforce that it contains the "@" character.

• Add Validations to an Inline Editable Grid (Validation, Grids, Looping): Allows the user to change data directly in a grid, and validate a various entries.

• Add, Edit, and Remove Data in an Inline Editable Grid (Grids, Looping): Allow the user to change data directly in an inline editable grid.

• Add, Remove, and Move Group Members Browser (Hierarchical Data, Group Management): Display the membership tree for a given group and provide users with the ability to add, remove, and move user members from a single interface.

• Build a Wizard with Milestone Navigation (Conditional Display, Validation, Wizards): Create a wizard that divides a form into validated steps and uses the milestone component to display progress.

• Configure Buttons with Conditional Requiredness (Validation): Present two buttons to the end user and only make certain fields required if the user clicks a particular button

• Configure a Boolean Checkbox (Choice Components): Configure a checkbox that saves a boolean (true/false) value, and validate that the user selects the checkbox before submitting a form.

• Configure a Dropdown Field to Save a CDT (Choice Components): When using a dropdown to select values from the database, or generally from an array of CDT values, configure it to save the entire CDT value rather than just a single field.

• Configure a Dropdown with an Extra Option for Other (Choice Components): Show a dropdown that has an "Other" option at the end of the list of choices. If the user selects "Other", show a required text field.

• Make a Component Required Based on a User Selection (Validation): Make a paragraph component conditionally required based on the user selection.

• Set the Default Value Based on a User Input (Default Value): Set the default value of a variable based on what the user enters in another component.

• Set the Default Value of CDT Fields Based on a User Input (Default Value): Set the value of a CDT field based on a user input.

• Set the Default Value of an Input on a Start Form (Default Value): Display a default value in some form inputs on a start form, and save the value into the process when submitting.

• Set the Default Value of an Input on a Task Form (Default Value): Display a default value in some form inputs on a task form, and save the value to process when submitting.

• Showing Validation Errors that Aren't Specific to One Component (Validation): Alert the user about form problems that aren't specific to one component, showing the message only when the user clicks "Submit".

• Track Adds and Deletes in Inline Editable Grid (Grids): In an inline editable grid, track the employees that are added for further processing in the next process steps.

• Upload Multiple Documents in an Editable Grid (Document Management, Records): Build a form that allows users to create a record and upload related documents in an editable grid.

• Upload and name a file (Document Management, Records): Allow users to upload and name a file.

• Use Links in a Grid to Show More Details and Edit Data in External System (Grids, Web Services): Allow end users to click a link in a read-only grid to view the details for the row, and make changes to the data.

• Use Selection For Bulk Actions in an Inline Editable Grid (Grids): Allow the user to edit data inline in a grid one field at a time, or in bulk using selection.

• Use Validation Groups for Buttons with Multiple Validation Rules (Validation): Present two buttons to the end user that, based on the selection, will validate only after a particular button is clicked.

Feedback