Read-Only Grid Component

Eager to get started with the read-only grid? Check out the Grid Tutorial for the fastest and easiest way to create a read-only grid.

Read-Only Grid

Function: a!gridField()

The a!gridField() function allows you to create a read-only grid in your interface to display data as rich text, links, images, buttons, tags, record actions, and progress bars. This grid component also supports searching, filtering, selecting, sorting, and paging.

From Design mode, you can quickly and easily set up a read-only grid by dragging and dropping the component into live view and selecting your grid's data source. You can choose from record type, query, variable, rule, or expression. When you choose a record type as your data source, you can reuse features configured on your record list such as user filters, record actions, and export to Excel. Although, Design mode allows for a easier and faster setup for your read-only grid, you can still use the a!gridField() function in Expression mode to customize and configure your read-only grid.

Parameters

Note: not all parameters are immediately available in Design Mode; some display only after enabling others. For example, after selecting Selectable, other selection-related parameters will be available.

Name Keyword Types Description

Label

label

Text

Text to display as the grid label.

Label Position

labelPosition

Text

Determines where the label appears. Valid values:

  • ABOVE (default) Displays the label above the component.
  • ADJACENT Displays the label to the left of the component.
  • COLLAPSED Hides the label. The label will still be read by screen readers; see accessibility considerations for more information.
  • JUSTIFIED Aligns the label alongside the component starting at the edge of the page.

Instructions

instructions

Text

Supplemental text about this grid.

Help Tooltip

helpTooltip

Text

Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".

Empty Grid Message

emptyGridMessage

Text

Text to display in the grid when no data is available. Default is "No items available".

Data

data

recordType, List of Map and List of Dictionary, DataSubset, or PortalReportDataSubset

The data to display in the grid. Use a record type reference or a!recordData() to source your data from records and utilize records functionality, such as user filters and export. For other cases, you can use a query, such as a!queryEntity() with pagingInfo set as fv!pagingInfo to have the grid automatically manage paging. The function a!queryProcessAnalytics(), a Data Subset, a list of Dictionary, or an array of data can also be used. When using a query that returns a datasubset, you must pass the total count (fetchTotalCount: true on the query).

Columns

columns

List of a!gridColumn()

The columns to display in the grid, configured using a!gridColumn().

Rows to Display Per Page

pageSize

Number (Integer)

The maximum number of rows to display at a time. Default: 10

Initial Sorts

initialSorts

List of SortInfo

Sorts applied to the grid upon initial load only. Each sort is applied in the order listed. The first sort in the list will display an active-sort arrow indicator (either up or down for ascending or descending) in its corresponding grid column (if applicable).

Secondary Sorts

secondarySorts

List of SortInfo

Sorts applied to the grid after every user interaction. If the user activates a sort on a column, these sorts will be applied to the other columns in the order they're listed. For example, adding a secondary sort on Month will keep them in order when the user sorts on Year. Secondary sorts do not display an active-sort indicator.

Paging Save Into

pagingSaveInto

List of Save

One or more variables that are updated only when user invokes a paging action on the grid. You can reference the current paging of the grid using fv!pagingInfo.

Selectable

selectable

Boolean

Determines if grid rows are selectable. When selection style is "CHECKBOX" (default), the selection column is displayed. Default: false.

Selection Style

selectionStyle

Text

Determines the style when a row is selected. Valid values: "CHECKBOX" (default), "ROW_HIGHLIGHT".

Selection Value

selectionValue

Text Array or Integer Array

Identifiers of the rows that should appear as selected. Can be set to have rows be pre-selected for the user. Supported types: Text Array and Integer Array.

Save Selection To

selectionSaveInto

List of Save

One or more variables that are updated with the selected identifiers when the user changes selections. Use a!save() to save a modified or alternative value to a variable. You can reference the rows selected and deselected in the most recent user interaction (not all selected or deselected rows) using fv!selectedRows and fv!deselectedRows respectively.

Selection required

selectionRequired

Boolean

Determines if a selection is required to submit the form. Default: false.

Selection Required Message

selectionRequiredMessage

Text

Custom message to display when a selection is required and not provided.

Disable Row Selection

disableRowSelectionWhen

Boolean

Determines for each row if selection is disabled. The condition defined in this parameter is evaluated once for each row. Enter an expression that evaluates to true or false. When the expression evaluates to true, that row is disabled. You can reference fields from the source using dot notation, such as fv!row.status. You will need to use the recordType! domain when referencing record data. For example, fv!row[recordType!Case.fields.caseName]. You can also reference the identifier of the row using fv!identifier. Default: false. For example, you can disableRowSelectionWhen: isnull(fv!row.status).

Validations

validations

List of Variant

Validation errors to display below the grid when the data is invalid, configured using a!validationMessage(). You can reference the current page of data using fv!currentPage.

Validation Group

validationGroup

Text

When present, this field is only validated when a button in the same validation group is pressed.

Visibility

showWhen

Boolean

Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.

Spacing

spacing

Text

Determines the spacing within grid cells. Valid values: "STANDARD" (default), "DENSE".

Height

height

Text

Determines height of the grid. Valid values: "SHORT", "MEDIUM", "TALL", "AUTO" (default). When it is set to SHORT, MEDIUM, or TALL, the header is frozen.

Border Style

borderStyle

Text

'Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT".

Shade Alternate Rows

shadeAlternateRows

Boolean

Determines whether alternate rows are shaded. Default: true.

Row Header

rowHeader

Number (Integer)

Index of the column to be used as the row header. Screen readers will announce the value in each row header when navigating to other cells within that row. Used only for accessibility; produces no visible change.

Accessibility Text

accessibilityText

Text

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

Refresh Always

refreshAlways

Boolean

When true, the value of this local variable will be refreshed after each user interaction and each interval refresh. Because the variable is continually refreshed, you cannot update its value by saving into it. Default: false.

Refresh After

refreshAfter

List of Text String

Refreshes the value of the local variable each time a specified event completes. Valid values: "RECORD_ACTION".

Refresh After an Interval of Time

refreshInterval

Number (Decimal)

How often the variable value gets refreshed in minutes. When null, the variable will not be refreshed on an interval. Because the variable is periodically refreshed, you cannot update its value by saving into it. You can access the current value of the variable using fv!value (see the documentation for an example). Valid values: "0.5", "1, 2", "3", "4", "5", "10", "30", and "60".

Refresh on Reference Variable Change

refreshOnReferencedVarChange

Boolean

When true, the value of this local variable will be refreshed each time the value of any variable it references within the value parameter is updated. To refresh the local variable when another variable that is not used within value changes, use refreshOnVarChange. Default: true.

Refresh on Variable Change

refreshOnVarChange

Any Type

Refreshes the value of the local variable each time any of these specific variables change. This allows you to refresh the value when a variable that is not referenced within the value parameter is updated. You can define either using a single variable (e.g. refreshOnVarChange: local!var1) or a list of variables (e.g. refreshOnVarChange: {local!var1, local!var2}).

User Filters

userFilters

List of Variant

List of user filter references to display, configured using the recordType! domain. For example, recordType!Case.filters.status. You may only reference user filters defined on the source record type used for the grid data. This parameter only applies when a record type is used as the source in the data parameter.

Show search box

showSearchBox

Boolean

Determines if the record search box should be shown. This parameter only applies when a record type is used as the source in the data parameter. Default: true.

Show Refresh Button

showRefreshButton

Boolean

Determines if the grid should include a refresh button to manually refresh data. This parameter only applies when a record type is used as the source in the data parameter. Default: true.

Show Export to Excel Button

showExportButton

Boolean

Determines if grid data can be exported. This parameter only applies when a record type is used as the source in the data parameter. Default: false.

Record Actions

recordActions

List of Variant

List of record action items to display above the grid, configured using a!recordActionItem(). If you use fv!identifier in the identifier parameter of a!recordActionItem(), you will also need to configure selection for the grid. This parameter only applies when a record type is used as the source in the data parameter.

Open Actions In

openActionsIn

Text

Determines how record actions should open to the user. Valid values: "DIALOG" (default), "NEW_TAB", SAME_TAB.

Actions Display

actionsDisplay

Text

Determines which details are shown for record actions, regardless of style. Valid values: "LABEL_AND_ICON" (default), "LABEL", "ICON".

Display Notes

  • To reduce clutter on smaller grids, the following happens:
    • No paging controls are displayed when all rows are on one page.
    • Paging controls to jump to the first or last page are not displayed when a grid has less than 3 pages.
  • If the Value for a column is empty or null, the grid still renders the column with just the label.
  • For columns using the "AUTO" width, each column's width is determined by the length of the longest value in that column.
  • Paging and sorting do not function and images do not render when this component is used offline.
  • Grid heights behave as a fixed height on web but a maximum height on mobile.
  • The Selection Style (selectionStyle) of ROW_HIGHLIGHT does not have any visual indicator when selection is disabled through the Disable Row Selection (disablerowselectionwhen) parameter.
  • When using records-specific components on the read-only grid, such as user filters, export to Excel, and related actions the grid will automatically style the component header for you.

Configuration Notes

  • In order to use an existing record type created with Appian 20.2 and earlier as the data source for your read-only grid, you will need to update the record type to the latest Appian version.
  • When a record type is used as the data source for your read-only grid, Appian automatically generates grid columns based on the columns configured for the record list. A record list action configured on the record list is also automatically generated for the grid.
  • If you are managing your own paging, you cannot pass a datasubset whose paging configuration uses a batchSize of -1.
  • See also: a!queryEntity() Function.
  • For accessibility purposes, every grid should have a row header configured. The first column containing text is usually the correct choice for row header. See the UX Design Guide for more information.
  • When entering a query in the Data parameter (either directly, or indirectly from a rule reference), the query must return the total count (fetchTotalCount: true).

Query Editor Notes

The following notes apply when you use the query editor in Design Mode to configure a query and use it as the data source for your read-only grid:

  • Appian will automatically use the value set for the query's batchSize (Rows Per Page) as the value for the grid's Page Size (pageSize) parameter.
  • Appian will automatically use the value set for the query's sortInfo as the value for the grid's Initial Sorts (initialSorts) parameter.

Design Mode Notes

The following guidance applies when configuring a read-only grid in Design Mode. This guidance does not with the apply to grids that use a record type as the data source:

  • The grid cannot use a query whose paging info contains a batchSize of -1 from Design Mode.
  • When setting up a grid, if you populate the Data parameter from Design Mode, and let the grid manage the paging, the grid will automatically generate an initial set of columns in the order they appear.
    • Note that when you use a local variable as the data source for the read-only grid, grid columns are not automatically generated.
  • After initial columns have been generated, Appian will automatically update the grid with new columns to match any new fields you added to the data source. To trigger this behavior when using an indirect data source (from an expression or a rule), from the Data parameter, click Edit then OK.
    • Note that if you have changed the arrangement of existing grid columns, new columns will not be automatically generated.
    • Columns will not be removed if the corresponding fields are removed from the source data. You will need to manually delete these columns.
  • The initial values for automatically-generated columns are:
    • label: fv!row.<fieldname>, where the field name is converted to title case.
      • If the field name is in camel case, it will be split and converted to title case.
      • If the field name is too long, it will be truncated with elipses (...).
    • value: fv!row.<fieldname>
    • sortField: <fieldname> of the primary key
    • If the data type for the column value is numerical or date-based, then it will set align: "END".
    • If the data type for the column value is a decimal, then it will be wrapped in the fixed() function to two decimal places. Ex. value: fixed(fv!row.cost, 2).

Examples

You can find example configurations of the grid at Configuring the Read-Only Grid.

Common Questions

Should I change my existing grid to a read-only grid?

If you're using an editable grid as a read-only grid, because you didn't have access to the rich-text component, then you could see a performance improvement changing that editable grid to a read-only grid.

If you're using a paging grid (a!gridField_19r1), we recommend you upgrade to the read-only grid. The advantages are:

  • Better UX (column widths, header tooltips, rich text).
  • Native handling of common data errors when you use fv!pagingInfo.
  • Deterministic sorting (from secondarySorts).
  • Helpful function variables for passing selected row data (fv!selectedRows, fv!deselectedRows) that can be used to avoid requerying data.

How do I convert my paging grid to a read-only grid?

The easiest way to convert your paging grid to a read-only grid would be to recreate the grid. In most cases, this will be the fastest way. Since the read-only grid is a new paradigm, converting a paging grid to a read-only grid isn't just changing a few parameters; a lot of what used to exist outside of the grid to support it just isn't necessary anymore—a!pagingInfo(), a!gridSelection(). Trying to convert your existing grids by manipulating the underlying expression will likely result in a lot of unnecessary, leftover content, and possibly some unusual behaviors that result from trying to preserve your existing paging information.

The part that can be reused is any query that provides the data for your grid. If you stored the query in a local variable, you can place that query expression directly into the Data parameter of the grid, or into an expression rule (if you're reusing it), and update the paging info to use the grid's fv!pagingInfo instead.

Do I have to use a!localVariables with the new grid?

No, the new grid does not require local variables since you can pass the data directly to the grid and it will automatically refresh when the data changes. You no longer need to use a!localVariables(), load(), or with(). You can also define a!refreshVariable parameters, such as refreshInterval, directly in a!gridField.

The only case where you will need to use local variables is if you want to manually manage your paging. For this case, you'll define a!localVariables() outside of the grid's data parameter and then pass in the defined local variable to data.

See Also

Configuring the Read-Only Grid.

UX Design Guide: Grids: Includes UX best practices for designing grids.

Grid Tutorial: Fast walkthrough that covers creating a grid, embedding a query, enabling selection, and formatting columns.

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

Open in Github

On This Page

FEEDBACK