Free cookie consent management tool by TermsFeed Columns Layout (a!columnsLayout)
Columns Layout
SAIL Design System guidance available for Columns Layout

When you need greater flexibility and control over the width of certain sections on your interface, use the columns layout. Learn how to use different column widths and configurations to bring greater balance to your content arrangements.

Function

a!columnsLayout( columns, alignVertical, showWhen, marginBelow, stackWhen, showDividers, spacing, marginAbove )

Displays any number of columns alongside each other. On narrow screens and mobile devices, columns are stacked.

See also:

Parameters

Name Keyword Types Description

Columns

columns

Any Type

Columns to display using a column layout, a!columnLayout().

Vertical Alignment

alignVertical

Text

Determines vertical alignment of all column content with the layout. Valid values are "TOP" (default), "MIDDLE", and "BOTTOM".

Visibility

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.

Margin Below

marginBelow

Text

Determines how much space is added below the layout. Valid values: "NONE", "EVEN_LESS", "LESS", "STANDARD" (default), "MORE", "EVEN_MORE".

Stack When

stackWhen

List of Text

Determines the window width at which column layouts stack vertically. List all widths where columns should stack. Valid Values: "PHONE" (default), "TABLET_PORTRAIT", "TABLET_LANDSCAPE","DESKTOP", "DESKTOP_WIDE", "NEVER".

Show Dividers

showDividers

Boolean

Determines whether dividers appear between the columns. Default: false.

Column Spacing

spacing

Text

Determines the space between columns in the layout when they are not stacked. Valid values: “STANDARD” (default), “NONE”, “DENSE”, “SPARSE”.

Margin Above

marginAbove

Text

Determines how much space is added above the layout. Valid values: "NONE" (default), "EVEN_LESS", "LESS", "STANDARD", "MORE", "EVEN_MORE".

Usage considerations

Stacking on mobile

  • On mobile phones, columns are stacked by default.

Examples

Click EXPRESSION to copy and paste an example into the Interface Definition to see it displayed.

Three columns within one columns layout

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
a!columnsLayout(
  columns: {
    a!columnLayout(
      contents: {
        a!textField(
          label: "Customer",
          value: "Jane Doe",
          readOnly: true
        ),
        a!textField(
          label: "Status",
          value: "Active",
          readOnly: true
        ),
        a!textField(
          label: "Priority",
          value: "High",
          readOnly: true
        )
      }
    ),
    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
        )
      }
    )
  }
)

Displays the following:

screenshot of three columns within one columns layouts

Columns layout nested in another columns layout

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
a!columnsLayout(
  columns: {
    a!columnLayout(
      contents: {
        a!textField(
          label: "Customer",
          value: "Jane Doe",
          readOnly: true
        ),
        a!textField(
          label: "Status",
          value: "Active",
          readOnly: true
        ),
        a!textField(
          label: "Priority",
          value: "High",
          readOnly: true
        )
      }
    ),
    a!columnLayout(
      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
                )
              }
            )
          }
        )
      }
    )
  }
)

Displays the following:

screenshot of nested columns layouts

Feature compatibility

The table below lists this SAIL component's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile 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.

The following patterns include usage of the Columns Layout.

  • Build a Wizard with Milestone Navigation (Wizards): Use the milestone component to show steps in a wizard.

  • Build an Interface Wizard (Wizards): Divide a big form into sections presented one step at a time with validation.

  • Call to Action Pattern (Formatting): Use the call to action pattern as a landing page when your users have a single action to take.

  • Cards as Buttons Pattern (Choice Components, Formatting, Conditional Display): The cards as buttons pattern is a great way to prominently display a select few choices.

  • Cards as List Items Patterns (Choice Components, Images): Use the cards as list items pattern to create visually rich lists as an alternative to grids or feeds. This pattern uses a combination of cards and billboards to show lists of like items. You can easily modify the pattern to change the card content or the number of cards per row to fit your use case.

  • Comments Patterns (Comments, Looping): Use this pattern when displaying a chronological list of messages from different users, such as comments on a topic or notes on a case.

  • Conditionally Hide a Column in a Grid (Grids, Conditional Display): Conditionally hide a column in a read-only grid when all data for that column is a specific value.

  • Document List (Documents): Use the document list items pattern to display a list of documents that can be searched and filtered. This pattern uses a combination of cards and rich text to show an easy to navigate list of documents of different types.

  • Drilldown Pattern (Grids): The drilldown pattern allows users to select an item from a grid to see more details in place of the grid.

  • Drilldown Report Pattern (Grids, Charts, Reports): The drilldown report pattern consists of a bar chart and column chart, which each drill down into a grid.

  • Dual Picklist Pattern (Choice Components, Cards, Checkboxes, Buttons): Use this pattern to view side-by-side lists and move items from one list to the other. The dual picklist is great for moving items from one state to another, like from active to inactive.

  • Dynamic Inputs (Inputs, Dynamic Links): Use the dynamic inputs pattern to allow users to easily add or remove as many values as needed.

  • Dynamically Show Sales by Product Category Compared to Total Sales (Records, Reports, Charts, Filtering): This pattern illustrates how to create an area chart that dynamically displays sales generated by product category compared to total sales.

  • Event Timelines (Timeline, Events): Use the event timeline pattern to display a dated list of events and actions in chronological order. This pattern uses a combination of cards, rich text, and user images to show an easy to navigate list of dated events.

  • Filter the Data in a Grid (Grids, Filtering, Records): Configure a user filter for your read-only grid that uses a record type as the data source. When the user selects a value to filter by, update the grid to show the result.

  • Form Steps (Stamps): Use the form steps patten to break down complicated forms into a series of quickly completed steps that are well organized and easy to navigate. This pattern uses a combination of cards and rich text to create steps that can represent fields from one or more interfaces.

  • Grid With Detail (Grids): The grid with detail pattern allows users to select an item from a grid to see more details next to the grid.

  • Grid with Heatmap Pattern (Grids): Displays a grid with conditional formatting of background colors at different thresholds.

  • Grid with Selection Pattern (Grids): This pattern is an example of good UX design for a grid that allows users to select items and easily view their selections when there are multiple pages of data. It also provides information on a common save behavior.

  • Inline Survey (Radio Buttons, Checkboxes, Buttons): Use this pattern to create a clean and easy to navigate survey.

  • KPI Patterns (Formatting): The Key Performance Indicator (KPI) patterns provide a common style and format for displaying important performance measures.

  • Leaderboard (Looping): Use the leaderboard pattern to show a selection of your data in an easy to read ranked display.

  • Limit the Number of Rows in a Grid That Can Be Selected (Validation, Grids, Records): Limit the number of rows that can be selected to an arbitrary number.

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

  • Milestone Patterns (Looping): There are three options for milestone patterns which all display some form of a progress indicator to guide users through a series of steps.

  • Navigation Patterns (Conditional Display, Formatting, Navigation): Use the navigation patterns to help orient users and enable them to easily navigate pages and content.

  • Percentage of Online Sales (Records, Reports, Formatting): This pattern illustrates how to calculate the percent of sales generated from online orders and display it in a gauge component.

  • Refresh Data After Executing a Smart Service (Auto-Refresh, Smart Services):

  • Refresh Until Asynchronous Action Completes (Auto-Refresh): Use a refresh interval to display the results of an asynchronous action automatically.

  • Sales by Country and Currency (Records, Reports): This pattern illustrates how to create two different charts. One chart shows sales (calculated in US dollars) by country and the currency paid. The other shows sales by currency type, comparing the number of sales paid in US dollars versus the local currency.

  • Save a User's Report Filters to a Data Store Entity (Grids, Smart Services, Filtering, Reports): Allow a user to save their preferred filter on a report and automatically load it when they revisit the report later.

  • Searching on Multiple Columns (Grids, Filtering, Reports): Display a grid populated based on search criteria specified by end users.

  • Stamp Steps (Stamps): There are two similar stamp steps patterns. The stamp steps (icon) pattern is primarily icons and titles. It should be used for simple steps that don't require much information or instruction. The stamp steps (numbered) pattern is primarily text and should be used for steps that require context or explanation.

  • Task Report Pattern (Grids, Filters, Process Task Links, Task Reports): Provides a simple way to create and display an Appian task report.

  • Trend-Over-Time Report (Charts, Reports): This report provides an attractive, interactive design for exploring different series of data over time.

  • Update an Entity-Backed Record from its Summary View (Records, Smart Services): Enable users to make quick changes to a record by updating it right from a record view.

  • Use Links in a Grid to Show More Details and Edit Data (Grids): 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. The data available for editing may include more fields than are displayed in the grid.

  • Use the Gauge Fraction and Gauge Percentage Configurations (Formatting, Reports): This recipe provides a common configuration of the Gauge Component using a!gaugeFraction() and a!gaugePercentage(), and includes a walkthrough that demonstrates the benefits of using design mode when configuring the gauge component.

  • Year-Over-Year Report (Charts, Reports, Formatting): This is a feature-rich, interactive report for sales and profits by products over select periods of time.

  • Year-Over-Year Sales Growth (Records, Reports, Formatting): This pattern illustrates how to calculate year-over-year sales growth and display it in a KPI.

Columns Layout

FEEDBACK