Wizard Layout

SAIL Design System guidance available for Wizard Layout When you want to display complex, multi-step forms, use the wizard layout. Learn how to use the wizard layout to organize forms into seamless, easy-to-use steps.

About the wizard layout

Displays a multi-step form with a step indicator. Use this as the top-level layout for complex forms to organize inputs into steps. Reference information about wizard steps using fv!activeStepIndex, fv!isFirstStep, and fv!isLastStep.

See When to use a wizard layout for guidance on when to use this component versus a form layout.

Where to use the wizard layout

The a!wizardLayout() is a top-level layout that can only be used as the outermost component of an interface. It can't be nested inside another component.

Supported components

The following a!wizardLayout() parameters support certain components:

• The titleBar parameter supports:
  • a!headerTemplateSimple()
  • a!headerTemplateFull()
  • a!headerTemplateImage()
  • a!sidebarTemplate()
  • A list of a!billboardLayout() and/or a!cardLayout()
  • A text string (such as "Wizard Title")
• The steps parameter supports a!wizardStep().
• The primaryButtons parameter supports a list of a!buttonWidget().
• The secondaryButtons parameter supports a list of a!buttonWidget().

Parameters

a!wizardLayout( titleBar, isTitleBarFixed, showTitleBarDivider, backgroundColor, style, showWhen, steps, contentsWidth, showStepHeadings, focusOnFirstInput, primaryButtons, secondaryButtons, showButtonDivider, isButtonFooterFixed )

Using the wizard layout

The following sections cover important details about the wizard layout.

Using the titleBar parameter

For the titleBar parameter, you can choose either a simple header, full header, image header, or sidebar template. See Choosing a title bar template 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.

Related style guidelines:

• Title bar guidelines

Using the contentsWidth parameter in record action dialogs

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.

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

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

Using the style parameter

The style parameter allows you to select a wizard style to choose the appearance and location of the milestone. Vertical styles display a milestone to the side of the wizard step contents, and horizontal styles display a milestone above the wizard step contents.

In general, you should use a vertical style if your wizard has a large number of steps, since too many steps in a horizontal milestone can appear crowded and hard to understand. You should also use a vertical style if your step contents are very tall, to minimize the need to scroll within the wizard.

If you don't want to display the milestone, select "MINIMAL" to show the step number above the contents instead (for example, "Step 1 of 2").

On smaller screens, wizards will responsively display a minimal milestone style.

Wizard buttons

In a wizard layout, the Next and Back buttons are added automatically and can't be configured. If you drag and drop the wizard layout into an interface, Submit and Cancel buttons are also added automatically.

You can use the disableNextButton parameter in a!wizardStep() to specify when the Next button is disabled for a user on a step.

You can add more buttons to your wizard with the primaryButtons and secondaryButtons parameters. When you add more primary buttons, they appear next to the Next button. When you add more secondary buttons, they appear next to the Back button.

Related style guidelines:

• Button guidelines

Referencing wizard step information

The following function variables can be used anywhere within the wizard layout to reference information about wizard steps:

fv!isFirstStep and fv!isLastStep will not be true for hidden wizard steps. For example, if you configured four wizard steps (A, B, C, and D), and the showWhen parameter for step D is false, then fv!isLastStep will be true for step C.

Hidden wizard steps are still counted by fv!activeStepIndex to determine the step's index.

Using sidebar template with wizard layout

Vertical milestone behavior in sidebar

When using a sidebar template in an a!wizardLayout() with a vertical milestone, the milestone steps will automatically be moved into the sidebar, appearing below the secondaryText and above any additionalContents.

When the sidebar's responsive behavior causes it to display as a header, the milestone will display below the header using the "MINIMAL" style.

Responsiveness of sidebar

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:

Related style guidelines:

• Sidebar template guidelines

Heading levels for headingTag parameters

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

Async loading placeholder

If a wizard step relies on an async variable, a placeholder will be displayed for the wizard step contents until the async data is finished loading. See a!asyncVariable() for more information on how the placeholder behavior works.

Appian Mobile considerations

On Appian Mobile, the style parameter is ignored. Wizard layouts viewed in Appian Mobile use the default "LINE" style.

Example

The following example demonstrates the wizard layout.

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

Wizard with three steps

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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
a!wizardLayout(
  titleBar: a!headerTemplateFull(
    title: "Request a Quote",
    secondaryText: "Customize your coverage",
    backgroundColor: "#434343"
  ),
  isTitleBarFixed: false,
  showTitleBarDivider: false,
  style: "DOT_VERTICAL",
  steps: {
    a!wizardStep(
      label: "About You",
      instructions: "Tell us about yourself",
      contents: {
        a!columnsLayout(
          columns: {
            a!columnLayout(
              contents: {
                a!textField(
                  label: "First Name",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            ),
            a!columnLayout(
              contents: {
                a!textField(
                  label: "Last Name",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            )
          }
        ),
        a!columnsLayout(
          columns: {
            a!columnLayout(
              contents: {
                a!textField(
                  label: "Email",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            ),
            a!columnLayout(
              contents: {
                a!integerField(
                  label: "Phone",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            ),
            a!columnLayout(
              contents: {
                a!checkboxField(
                  choiceLabels: {"Email Me", "Text Me"},
                  choiceValues: {1, 2},
                  label: "Contact Preference",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  choiceLayout: "COMPACT",
                  validations: {}
                )
              }
            )
          }
        ),
        a!textField(
          label: "Street Address",
          labelPosition: "ABOVE",
          saveInto: {},
          refreshAfter: "UNFOCUS",
          validations: {}
        ),
        a!columnsLayout(
          columns: {
            a!columnLayout(
              contents: {
                a!textField(
                  label: "City",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            ),
            a!columnLayout(
              contents: {
                a!dropdownField(
                  choiceLabels: {"Option 1", "Option 2", "Option 3", "Option 4",
                                  "Option 5", "Option 6", "Option 7", "Option 8",
                                  "Option 9", "Option 10", "Option 11", "Option 12"},
                  choiceValues: {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12},
                  label: "State",
                  labelPosition: "ABOVE",
                  placeholder: "Select state",
                  saveInto: {},
                  searchDisplay: "AUTO",
                  validations: {}
                )
              }
            ),
            a!columnLayout(
              contents: {
                a!integerField(
                  label: "Zip Code",
                  labelPosition: "ABOVE",
                  saveInto: {},
                  refreshAfter: "UNFOCUS",
                  validations: {}
                )
              }
            )
          }
        )
      }
    ),
    a!wizardStep(
      label: "Coverage Options",
      contents: {}
    ),
    a!wizardStep(
      label: "Quote",
      contents: {}
    )
  },
  contentsWidth: "FULL",
  primaryButtons: {
    a!buttonWidget(
      label: "Submit",
      submit: true,
      style: "SOLID",
      loadingIndicator: true,
      showWhen: fv!isLastStep
    )
  },
  secondaryButtons: {
    a!buttonWidget(
      label: "Cancel",
      value: true,
      saveInto: {},
      submit: true,
      style: "LINK",
      validate: false
    )
  }
)

Feature compatibility

Related recipes

The following recipes include usage of the Wizard Layout.

• Upload Multiple Documents and Edit Document Properties (Document Management, Records):

  Build a form that allows users to create a record and upload related documents. Users can edit the document name and add a document description before submitting the form.

Feedback