Free cookie consent management tool by TermsFeed Read-Only Grid Column Component (a!gridColumn)
Read-Only Grid Column Component
SAIL Design System guidance available for Grids

Grids should help your users take action and make decisions. Check out the grids design guidance page to learn how to display your data in a structured, easy-to-scan layout to help your users find what they need.

Function

a!gridColumn( label, sortField, helpTooltip, value, showWhen, align, width, backgroundColor, accessibilityText )

Displays a column of data as read-only text, links, images, rich text, buttons, tags, record actions, or progress bars within the Read-Only Grid Component.

When configuring the component, click Display Options after choosing a value.

Grid column display options dialog

Parameters

Name Keyword Types Description

Label

label

Text

Text to display as the column header.

Sort Field

sortField

Any Type

The field used to sort the grid when selecting this column header. Grids that use record data must use the recordType! domain to reference a record field or related record field. For example, recordType!Case.fields.caseName.

Help Tooltip

helpTooltip

Text

Displays a help icon in the column header with the specified text as a tooltip.

Display Value

value

Any Type

The value to display in each cell within the column. The value can be text, a!imageField(), a!linkField(), a!richTextDisplayField(), a!tagField(), a!buttonArrayLayout(), a!recordActionField(), or a!progressBarField(). It is evaluated once for each row.

Reference fields from the source using dot notation, such as fv!row.status, or the identifier using fv!identifier. Grids that use record data must use the recordType! domain to reference a record field or related record field. For example, fv!row[recordType!Case.fields.caseName].

If you use a!recordData() to populate your grid and you specify a fields parameter, any field references that are not included in that parameter will be ignored.

Visibility

showWhen

Boolean

Determines whether the column is displayed in the grid. When set to false, the column is hidden and is not evaluated. Default: true.

Alignment

align

Text

Determines the alignment for the header label and all values within the column. Valid values: "START" (default), "CENTER", "END".

Width

width

Text

Determines the column width. Valid values: "AUTO", "ICON", "ICON_PLUS", "NARROW", "NARROW_PLUS", "MEDIUM", "MEDIUM_PLUS", "WIDE", "1X", "2X", "3X", "4X", "5X", "6X", "7X", "8X", "9X", and "10X".

Background Color

backgroundColor

Text

Determines the cell background color. To set the color based on the value of the cell, use fv!row and dot notation to reference the field (such as fv!row.status). Grids that use record data must use the recordType! domain to reference a record field or related record field. For example, fv!row[recordType!Case.fields.status]. Valid colors: Any valid hex color or "NONE" (default), "ACCENT", "SUCCESS", "INFO", "WARN", "ERROR".

Accessibility Text

accessibilityText

Text

Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Usage considerations

Using the value parameter

  • If the value parameter for a column is empty or null, the grid still renders the column with just the label.
  • If the value parameter contains a data query, each row of the column may be evaluated in parallel to reduce the overall evaluation time of the grid.

Using the width parameter

  • For columns using the "AUTO" width, the width is determined by the length of the longest unbroken value in that column.
    • For example, this could be the length of the longest word in a paragraph or the width of the widest image.
  • Avoid using "AUTO" and weighted column widths (such as "1X", "2X", "3X", etc) together.
  • If you use a fixed width (such as "NARROW", "MEDIUM", etc) for a column that doesn't take up the width of the page, the width will auto distribute depending on the content inside the column.
  • If you use "ICON" & "AUTO" widths together, the column using "ICON" will always be the same width and the column using "AUTO" will fill up the remaining space.
  • For complete guidance on when and how to use column widths, see Column Widths.

Using the backgroundColor parameter

  • To conditionally format the background color, use a logical function like a!match() to define the conditions and the color to display when the condition is met. See the grid with heatmap pattern for an example of a grid with conditionally formatted background colors.
  • Header cells do not display a background color.
  • Background colors are not included when you export the grid to an Excel document. Instead, you can save the page as a PDF if you want to share the grid to those without access to your app.

Using the accessibilityText parameter

When you've configured a background color, you should also set equivalent accessibilityText values for screen readers to announce. This way, your grid will be accessible to a wider range of users.

For example, say your grid shows product information and one column shows the average customer rating. You could set the column's backgroundColor to be red, yellow, or green based on the value of that field. To indicate the meaning of these values to screen readers, add the accessibilityText parameter with text to read when the same conditions are met.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
a!gridColumn(
  label: "Average customer rating",
  backgroundColor: a!match(
    value: fv!row,
    whenTrue: fv!row <= 4,
    then: "NEGATIVE",
    whenTrue: fv!row <= 7,
    then: "WARN",
    whenTrue: fv!row >= 8,
    then: "SUCCESS"
    default: "NONE"),
  accessibilityText: a!match(
    value: fv!row,
    whenTrue: fv!row <= 4,
    then: "Poor",
    whenTrue: fv!row <= 7,
    then: "OK",
    whenTrue: fv!row >= 8,
    then: "Good",
    default: "No ratings")

The screen reader will announce the value of label, so you don't need to include the word rating in the accessibilityText values.

Examples

You can find example configurations of a read-only grid and its columns at Configuring the Read-Only Grid and Grid Tutorial.

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.

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.

Old Versions Reason for Update
a!gridTextColumn

Now supports multiple interface components.

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

The following patterns include usage of the Read-Only Grid Column Component.

Open in Github Built: Fri, Feb 23, 2024 (09:14:09 PM)

Read-Only Grid Column Component

FEEDBACK