a!formLayout_25r1 Component

On This Page

This page contains information related to an old version of the Form Layout.

To take advantage of the latest features and improvements, we always recommend you use the latest version whenever possible. For what's changed, see New version details.

Function

a!formLayout_25r1( backgroundColor, formWidth, showWhen, label, instructions, showHeaderDivider, isHeaderFixed, contents, skipAutoFocus, buttons, showButtonFooterDivider, 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.

form_layout_example

Parameters

Name	Keyword	Types	Description
Background Color	backgroundColor	Text	Color to show behind the contents of the form. Valid values: Any valid hex color or "WHITE" (default), "TRANSPARENT", "CHARCOAL_SCHEME", "NAVY_SCHEME", "PLUM_SCHEME".
Form Width	formWidth	Text	Determines the maximum width of the form on a page or in a dialog. If the page or dialog is narrower than the selected value, the form will fill the entire width. Valid values: "FULL" (default), "WIDE", "MEDIUM", "NARROW", "EXTRA_NARROW".
Show When	showWhen	Boolean	Determines whether the layout is displayed on the interface. When set to false, the layout is hidden and is not evaluated. Default: true.
Label	label	Text	Optional text to display as the interface's title.
Instructions	instructions	Text	Optional text displayed below the field's label.
Show header divider	showHeaderDivider	Boolean	Determines whether to display a divider line below the header to separate it from the rest of the content. Default: true.
Fix header when scrolling	isHeaderFixed	Boolean	Determines whether the header remains at the top of the form when scrolling. In Appian Mobile, the header is never fixed. Default: In dialogs, the header is fixed; otherwise, it is not fixed. Setting this parameter to true or false will override this behavior.
Contents	contents	Any Type Array	Components and layouts to display in the form body.
Don’t automatically focus on first input	skipAutoFocus	Boolean	Determines whether the first input will receive focus when a form loads. Default is false.
Buttons	buttons	Button Layout	Buttons to display at the bottom of the form, arranged using a!buttonLayout().
Show button footer divider	showButtonFooterDivider	Boolean	Determines whether to display a divider line above the button footer to separate it from the rest of the content. Default: true.
Validations	validations	Text or Validation Message	Validation errors displayed above the form buttons. Configured using a text array or an array with a mix of text and Validation Message using `a!validationMessage(message, validateAfter)`.
Validation Group	validationGroup	Text or Validation Message Array	When present, the requiredness of the field is only evaluated when a button in the same validation group is pressed. The value for this parameter cannot contain spaces. For example, `“validation group”` is not a valid value. You need to add an underscore between words: `“validation_group”`. See the following recipes for more information: Configure Buttons with Conditional Requiredness Validation Groups for Buttons with Multiple Validation Rules'

Usage considerations

Using a!formLayout()

A button layout must be present for a back button to appear for activity-chained tasks.
Use form validation messages for problems that are not specific to a single component.
This component cannot be read-only or disabled.

Form width in record action dialogs

If you are planning to display the form in a record action dialog, keep in mind that the dialog size is set in the record type and that the form width is set in the form layout. Be sure to open the record action to make sure the form width looks good with the dialog size.

We recommend setting the formWidth parameter to "FULL" when displaying the form in a dialog.

Initial behavior & focusing

The component is not in an initially collapsed section.
Focus will automatically be applied on initial load to the first component in a form 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

Scroll behavior in wizards

In wizards, Appian automatically handles the page scrolling between each step of the wizard. This means that whenever a user navigates to the next step, the page will automatically scroll to the top of the page.

If you are using the form layout in a wizard, make sure that the buttons or dynamic links that control form navigation are placed in the buttons parameter. If they are placed in the contents parameter, auto scrolling will not work.

Examples

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

Read-only form

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

a!formLayout(
  label: "Customers for Review",
  formWidth: "MEDIUM",
  instructions: "Review the profiles for the customers below and contact as needed",
  contents: {
    a!columnsLayout(
      columns: {
        a!columnLayout(
          contents: {
            a!textField(
              label: "Customer",
              value: "John Smith",
              readOnly: true
            ),
            a!textField(
              label: "Status",
              value: "Prospective",
              readOnly: true
            ),
            a!textField(
              label: "Priority",
              value: "High",
              readOnly: true
            )
          }
        ),
        a!columnLayout(
          contents: {
            a!textField(
              label: "Customer",
              value: "Michael Johnson",
              readOnly: true
            ),
            a!textField(
              label: "Status",
              value: "Prospective",
              readOnly: true
            ),
            a!textField(
              label: "Priority",
              value: "Medium",
              readOnly: true
            )
          }
        )
      }
    )
  },
  buttons: a!buttonLayout(
    primaryButtons: {
      a!buttonWidget(
        label: "Submit",
        style: "SOLID",
        submit: true
      )
    },
    secondaryButtons: {
      a!buttonWidget(
        label: "Cancel",
        submit: true
      )
    }
  )
)

Form with background color

a!localVariables(
  local!data:a!map( firstName:null, lastName:null, email:null, country:null, orgName:null, title:null ),
  a!formLayout(
    backgroundColor: "#f8f6f0",
    formWidth: "MEDIUM",
    label: "REGISTER NOW",
    instructions: "Enter your details below to register for the conference",
    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
        )
      }
    ),
    showButtonFooterDivider: false
  )
)

Displays the following:

screenshot of a form with background color

New version details

The form layout was evolved to implement the new title bar templates. We've made the following changes to parameters to accommodate the new title bar design experience, as well as to align the parameters with wizard layout.

Change type	Original parameter	New parameter
Added	`titleBar`	None
Removed	`label`	None
Removed	`instructions`	None
Renamed	`formWidth`	`contentsWidth`
Renamed	`showHeaderFixed`	`isTitleBarFixed`
Renamed	`skipAutoFocus`	`focusOnFirstInput`
Renamed	`showButtonFooterDivider`	`showButtonDivider`

Additional updates:

We've reorganized the parameter order and design view and introduced dynamic defaults for certain parameters.
The default behavior for contentsWidth, showTitleBarDivider, and showButtonDivider parameters will automatically adapt based on if the form is displayed in a dialog or not.
The title bar divider's width depends on the isTitleBarFixed parameter:
- If isTitleBarFixed is false, the divider's width matches the content width.
- If isTitleBarFixed is true, the divider extends to the full width of the screen or dialog.

Feature compatibility

The table below lists this component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Compatible
Offline Interfaces	Compatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Incompatible	Cannot be used to configure a process event node, such as a start event or timer event.
Process Autoscaling	Incompatible	Cannot be used in autoscaled processes.
Event Consumer Filter Conditions	Compatible	Can be used in filter conditions.
Event Consumer Event Handlers	Compatible	Can be used in event handler expressions.

Feedback

Was this page helpful?