Read-Only Grid 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.

About the read-only grid component

Accepts a set of data and displays it in a grid that supports searching, filtering, selecting, sorting, and paging. You can choose to display your data as text, links, images, rich text, buttons, tags, record actions, or progress bars. For example:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

To organize editable inputs in a tabular layout, use an editable grid.

See the Grid Tutorial to learn how to build a read-only grid with selection, conditional formatting, row filtering, and dynamically displaying content.

Where to use the read-only grid component

Use the read-only grid (a!gridField()) in the following components:

• a!formLayout(): contents parameter.
• a!headerContentLayout(): contents parameter, or in the header parameter (inside a!cardLayout()).
• a!pane(): contents parameter (inside a!paneLayout()).
• a!wizardStep(): contents parameter (inside a!wizardLayout()).
• a!boxLayout(): contents parameter.
• a!cardLayout(): contents parameter.
• a!columnLayout(): contents parameter (inside a!columnsLayout()).
• a!sectionLayout(): contents parameter.
• a!tabItem(): contents parameter (inside a!tabLayout()).
• a!sidebarTemplate(): additionalContents parameter (inside a!formLayout() or a!wizardLayout()).

You cannot use the read-only grid (a!gridField()) in the following components:

• a!sideBySideItem()
• a!barOverlay()
• a!columnOverlay()
• a!fullOverlay()

Supported components

The following the read-only grid (a!gridField()) parameters support certain components:

• The columns parameter supports a list of a!gridColumn(), which supports only the following components:
  • Plain text strings
  • a!imageField()
  • a!linkField()
  • a!richTextDisplayField()
  • a!buttonArrayLayout()
  • a!tagField()
  • a!recordActionField()
  • a!progressBarField()
  • a!sideBySideLayout()
• The recordActions parameter supports a list of a!recordActionItem().

The read-only grid (a!gridField()) does not use editable grid subcomponents like a!gridLayoutHeaderCell(), a!gridLayoutColumnConfig(), or a!gridRowLayout().

Parameters

a!gridField( label, labelPosition, instructions, helpTooltip, emptyGridMessage, data, columns, pageSize, initialSorts, secondarySorts, pagingSaveInto, selectable, selectionStyle, selectionValue, selectionSaveInto, selectionRequired, selectionRequiredMessage, disableRowSelectionWhen, validations, validationGroup, showWhen, spacing, height, borderStyle, shadeAlternateRows, rowHeader, accessibilityText, refreshAlways, refreshAfter, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange, userFilters, showSearchBox, showRefreshButton, showExportButton, recordActions, openActionsIn, actionsDisplay, actionsStyle, maxSelections, showSelectionCount, loadDataAsync, similarityScoreThreshold, pagingControls, showManageFiltersMenu, smartSearchType, searchFields )

Using the read-only grid component

The following sections cover important details about the read-only grid component.

Choosing the source of the grid

The fastest way to configure a read-only grid is from design mode. When you drag and drop the component into the live view and go to the Data tab of the Component Configuration pane, you can select one of the following options as the grid's data source:

Using records-powered grids

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.

Consider the following when configuring a records-powered grid.

Using records-powered grids in a portal

When you use a records-powered grid in a portal, there are a few things to keep in mind:

• Some record components don't work in portals: Certain record components, such as record links and record actions, are incompatible with portals. When you create a read-only grid using a record type, it may automatically use these components, so be sure to remove the incompatible components before publishing your portal.
• Users can't save their filters in a portal: The record list search, refresh button, export to Excel, and user filters will all function in a portal. However, users can't save their filters in a portal since they aren't signed in. The Manage filters button is replaced with a Clear Filters button in a published portal.
• Asynchronous loading is not compatible with portals.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

See Working with Data in Portals for more information about using records as the source for read-only grids in portals.

Specify which fields to query and when

By default, a grid will query and display all the data specified in the columns, pagingSaveInto, and selectionSaveInto parameters. This default behavior can potentially impact performance if your grid includes dynamic behavior since it may result in querying more data than necessary.

For example, let's say you configured the showWhen parameter on the columns in your grid so that certain columns only appear to managers. Even when columns are hidden from the grid, those fields will still be queried since they're specified in the columns parameter of the grid.

To alter this default behavior, you can specify when the grid should query the fields in your columns using the fields parameter in a!recordData(). Learn more about using the fields parameter in a!recordData().

Reference related data

If your record type has relationships configured, you can also reference related record fields in your grid.

Filter, limit, and sort related one-to-many data

If you reference a related record field from a one-to-many relationship as a column in the grid, the maximum number of related records returned for each base record is 100.

To filter, limit, and sort the related record set returned from the one-to-many relationship, you can leverage the relatedRecordData parameter in a!recordData().

Avoid using relationship references to display related one-to-many data. Instead, you should only reference the specific related record field you want to display. This avoids querying more data than necessary, which can impact the grid's performance and export behavior.

For example, to display a list of cases associated with each customer, you should use the related record field reference recordType!Customer.relationships.cases.fields.title in the grid column. You should not use the relationship reference recordType!Customer.relationships.cases.

Use records-specific components

You can use the following components on any records-powered grid:

• User filters
• Search
• Export to Excel button
• Record actions
• Smart search

Changes that affect user-saved filters

The following changes to parameters in a records-powered grid remove existing user-saved filters:

• A user filter is added or removed from the grid's userFilters parameter.
• The showSearchBox parameter value is changed.

For more information about user-saved filters, including record type changes that affect saved values, see User-saved filters.

Export data to Excel

When set to true, the showExportButton parameter allows users to export the grid data to Microsoft Excel. By default, any columns visible in the grid will export to Excel. You can specify which columns are exported by configuring the exportWhen parameter on individual grid columns.

The showExportButton parameter only applies to records-powered grids. If your grid doesn't use a record type as the source, you can use the Export Data Store Entity to Excel smart service to create a custom export button that exports your grid data to Excel.

Users should only export grid data from applications and sites. You should not export grid data from an interface in Appian Designer.

Review how much data can be exported from the grid, and how certain display elements are exported to Excel.

Display record actions

The recordActions parameter allows you to display record actions, like related actions or record list actions, on the grid. You can display actions from different record types.

See the record action component and the record action item component for other details to consider when adding record actions to a grid.

Style record actions

You can then use the actionsStyle parameter to determine whether all actions display as with standard styling, or if the first record action displays as a primary button style. Appian recommends using the "TOOLBAR_PRIMARY" option when you want the first action, typically the most common action, to stand out.

When actionsStyles is set to "TOOLBAR", the buttons display like this:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When actionsStyles is set to "TOOLBAR_PRIMARY", the buttons display like this:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Toolbar item positioning

The position of toolbar items in a records-powered grid, such as search, refresh, export, manage filters menu, and record actions, isn't configurable. These items always display in their default positions.

Record action security

Each action specified in the recordActions parameter has security that is checked to ensure only the right users can see the right actions. In most cases where you use security rules, Appian evaluates the security for the entire grid before it is shown to the user. Because security rules are verified in bulk, the overall grid loading time will be shorter than if security expressions are used.

Row limit for records-powered components

Interface components that use a record type as the data source are known as records-powered components.

Records-powered components can display a maximum of 5,000 rows. As a best practice, you should not display all 5,000 rows in a component since it may impact performance.

Query timeout for records-powered components

Queries to synced and unsynced record types will timeout after 65 seconds. If you are querying large volumes of data, this may cause the interface or expression to error.

To resolve timeout errors, reduce the amount of data in your query by:

• Reducing the batch size.
• Limiting the number of fields returned.
• Applying more specific filters.

Some complex queries may result in reduced performance. Ensure you're following query best practices.

Using the showManageFiltersMenu parameter

Setting the showManageFiltersMenu parameter to false hides the Manage Filters menu. Users can still access their existing user-saved filters, but they cannot save new filters or manage existing ones while the menu is hidden.

Use a!queryRecordType() as a data source

You can use a!queryRecordType() as the data source for your grid when you need manual control over paging or want to retain the user's current page after a data refresh. However, grids that use a!queryRecordType() are not considered records-powered and won't have access to features like user filters, search, and export to Excel.

Because a!queryRecordType() returns a Map rather than a DataSubset, you must construct a DataSubset from the query results using a!dataSubset().

The following example shows how to query record data with a!queryRecordType() and pass the results to the grid as a properly constructed DataSubset:

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
a!localVariables(
  local!pagingInfo: a!pagingInfo(
    startIndex: 1,
    batchSize: 10
  ),
  local!queryResult: a!queryRecordType(
    recordType: recordType!Case,
    fields: {
      recordType!Case.fields.id,
      recordType!Case.fields.title,
      recordType!Case.fields.status
    },
    pagingInfo: local!pagingInfo,
    fetchTotalCount: true
  ),
  a!gridField(
    label: "Cases",
    data: a!dataSubset(
      data: local!queryResult.data,
      startIndex: local!queryResult.startIndex,
      batchSize: local!queryResult.batchSize,
      sort: local!queryResult.sort,
      totalCount: local!queryResult.totalCount
    ),
    columns: {
      a!gridColumn(
        label: "Title",
        value: fv!row[recordType!Case.fields.title]
      ),
      a!gridColumn(
        label: "Status",
        value: fv!row[recordType!Case.fields.status]
      )
    },
    pageSize: 10
  )
)

To enable paging controls, set fetchTotalCount: true in the query. To let the grid manage page navigation, pass fv!pagingInfo to the pagingInfo parameter of a!queryRecordType().

Async loading considerations

Asynchronous (async) loading can provide a better user experience. When you configure a grid to load asynchronously, a placeholder will display in the grid's place, enabling users to interact with other parts of the interface while the grid's data loads in the background.

Using loadDataAsync vs a!asyncVariable()

There are two ways to enable async loading in a read-only grid:

• Using the loadDataAsync parameter: When you use a record type as the grid's data source, you can set the loadDataAsync parameter to true.
• Use an async local variable for the data parameter using the a!asyncVariable() function: If the grid's data is reused elsewhere in the interface, use a!asyncVariable() to create an async variable instead.

See Asynchronous Loading for detailed guidance on how async loading works and when to use it.

Offline and portal considerations

In offline mobile and portal interfaces, read-only grids that are configured to load asynchronously will load with the rest of the interface, instead of loading in the background.

Async loading placeholder

If the grid data uses async loading, a placeholder will be displayed for the entire grid until the async data is finished loading.

For grids with one or two columns that load slowly, you can wrap the column's value parameter in a rich text display component to display a placeholder for the column while the rest of the grid loads normally. The data for the column must be queried separately in an async local variable and be used directly in the read-only grid column component. See Async column example for an example expression.

See a!asyncVariable() for more information on how the placeholder behavior works.

Configuring grid display

• If the value for a column is empty or null, the grid still renders the column with just the label.
• Grid column header styling, such as background color or font size, isn't configurable.
• To display multiple components side by side in a single grid cell, use a!sideBySideLayout() in the value parameter of a!gridColumn(). See Display multiple components in a grid cell for details.
• 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 SAIL Design System for more information.

Choosing a selection style

When the selectable parameter is set to true, you can choose one of the following styles for the grid:

• "CHECKBOX": (Default style) Displays a selection column.
• "CHECKBOX_SUBTLE_HIGHLIGHT": Displays a selection column and applies a light blue highlight to the selected row.
• "SUBTLE_HIGHLIGHT": Applies a light blue highlight to the selected row without a selection column.
• "ROW_HIGHLIGHT": Applies a solid blue highlight to the selected row without a selection column.

When choosing your selection style, consider the following:

• The "SUBTLE_HIGHLIGHT" and "ROW_HIGHLIGHT" styles provide no visual feedback if you disable selection using the disableRowSelectionWhen parameter.
• On Appian Mobile, the grid always uses the "CHECKBOX" style, regardless of the value set for this parameter.

See the Grid with Selection Pattern for an example.

Configuring grid paging

To ensure a smooth user experience and optimal performance, consider the following when configuring grid paging:

• Performance and Paging Controls: By default, the grid does not display the total row count or paging controls to jump to the first or last page. This improves performance because the grid does not need to query the total number of records. To display the total count, set the pagingControl parameter to "ROW_COUNT".
• Dynamic Paging Adjustment: To reduce clutter, the grid automatically hides certain paging controls based on the data volume:
  • Paging controls are hidden if all rows fit on a single page.
  • First and last page jump controls are hidden if the grid has fewer than 3 pages.
• Fetch Total Count Requirement: When providing a query in the data parameter (either directly, or indirectly from a rule reference), the query must return the total count (fetchTotalCount: true).
• Manual Paging Constraints: If you are managing your own paging, you can't use a paging configuration with a batch size of -1 in your datasubset.
• Sorting with Composite Keys: If a records-powered grid uses a record type with a composite primary key, you'll need to configure a sort based on a single field.
• Offline Limitations: Paging and sorting are disabled when a grid is used offline, and images will not render.

Grid height and column width

• Mobile Considerations: Grid heights behave as a fixed height on web but a maximum height on mobile.

• Auto column width: When you set a column width to "AUTO", each column's width is determined by the length of the longest value in that column. For more information on using and choosing column widths, see the read-only grid column component and Column Widths.

Design mode guidance

The following guidance applies when configuring a read-only grid in design mode:

• Generated columns:
  • When 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.
  • Grid columns are not automatically generated when you select VARIABLE as the data source and use a local variable to power the read-only grid.

  • The initial values for automatically-generated columns are:

    Parameter	Value	Description
    label	fv!row.<fieldname>	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 ellipses (...).
    value	fv!row.<fieldname>	The field value to display.
    sortField	<fieldname>	The field name of the primary key.
    align	"END" or fixed()	The alignment depends on the field's data type. 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).

• Updating columns:
  • After initial columns have been generated, the grid will automatically update with new columns to match any new fields added to the data source.
  • However, automatic updates do not occur when the data source is an RULE or EXPRESSION. To update the columns displayed in the grid, you must update the data source, and add or remove the columns manually.
• Selecting QUERY as the data source:
  • If you select QUERY as the data source, you'll use the query editor to configure the query that powers your grid.
  • Appian will automatically use the following query values in your grid:
    • The query's batchSize will be the value of the grid's pageSize parameter.
    • The query's sortInfo will be used as the grid's initialSort parameter.
• Batch size limitation:
  • The grid cannot use a query that has a paging info with a batch size of -1 in design mode.

Using smart search in a grid

By default, when the showSearchBox parameter is true, the search box in a read-only grid uses a keyword search to find exact and partial matches to a user's search terms. You can implement smart search in the default search box to apply semantic search or lexical search in addition to keyword search.

When smart search is implemented on the default search box, both keyword search and the selected smart search type are applied. Each search type targets different fields and returns different similarity scores:

• Semantic search applies to any Text field, Extra Long Text field, or document that is enabled for smart search and displayed as a column in the grid or specified in the searchFields parameter. Semantic search matches return a similarityScore less than 1.
• Lexical search applies to any Text field, Extra Long Text field, or document that is enabled for smart search and displayed as a column in the grid or specified in the searchFields parameter. Lexical search matches return a similarityScore greater than 1.
• Keyword search always applies to searchable field types (Text, Number, User, or Group) displayed in the grid or specified in the searchFields parameter. Keyword search matches return a similarityScore of 1.

If you want to customize the grid's search box and its styling, you must build a custom search box. To build a custom search box that uses smart search, use one or more a!queryFilter() expressions in a!recordData() instead of the grid's search parameters. For full implementation details and steps, see Use smart search in a custom search box.

Use smart search in the default grid search box

In the default search box of a read-only grid, you can apply semantic search or lexical search on top of keyword search. Compare the search methods to determine which search method is best for your use case.

To configure smart search in the default search box:

1. In a read-only grid, ensure the showSearchBox parameter is true.

2. Configure the smartSearchType and similarityScoreThreshold parameters to set your preferred smart search type:
   • Semantic search: Set smartSearchType to "SEMANTIC" and similarityScoreThreshold to a value less than 1. See Using the similarityScoreThreshold parameter for guidance on choosing a threshold value.
   • Lexical search: Set smartSearchType to "LEXICAL". Keep the default similarityScoreThreshold value of 1.

   Tip:  See How smartSearchType and similarityScoreThreshold interact for all parameter combinations and their resulting search behavior.

3. Add columns to the grid for each field enabled for smart search. If you need to search on documents or Extra Long Text fields, use the searchFields parameter to specify all fields to search on.

4. In the initialSorts parameter, sort by the primary similarity score in descending order so the most relevant results appear first. Add a secondary sort to determine the order when the search box is empty.

How smartSearchType and similarityScoreThreshold interact

The smartSearchType and similarityScoreThreshold parameters together determine what search types are applied in the default search box.

Use the following table as a reference when configuring your grid:

Using the similarityScoreThreshold parameter

The similarityScoreThreshold parameter controls how closely search results must match the search term to be returned in the grid. This parameter is only available when the showSearchBox parameter is true.

By default, the similarityScoreThreshold parameter is set to 1, which limits the search box to traditional keyword search only. You should only modify this value if you're using semantic search on the grid.

The threshold you choose depends on your specific data set. What qualifies as a strong or weak match is variable, but generally:

• Higher values (closer to 1) set a stricter similarity requirement, returning fewer and more relevant results.
• Lower values (closer to 0) set a broader requirement, returning more results with a wider range of relevance.

When the similarityScoreThreshold parameter is null, a threshold of 0 is applied. If you specify a smartSearchType and similarityScoreThreshold is null, then keyword search and the specified smart search type are applied with no threshold.

Using the searchFields parameter

The searchFields parameter allows you to specify which record fields are searched in a grid. These search fields apply across all search types—keyword search, semantic search, and lexical search. The searchFields parameter is only available when the showSearchBox parameter is set to true.

Use the searchFields parameter when you want to:

• Search over unsupported field types: Extra Long Text fields can't display as columns in a read-only grid. Use the searchFields parameter to search these fields without displaying them in the grid.
• Tailor search for a specific grid: The customized record list search configuration applies to all grids that use the same record type. Use searchFields to customize which fields a particular grid searches without affecting other grids.
• Improve search performance: Limit the search to only the fields that are relevant to the grid's purpose, rather than searching all columns.

Supported field types

The searchFields parameter accepts record fields of the following types:

• Text
• Number (Integer)
• Group
• User
• Documents (must have smart search enabled)
• Extra Long Text (must have smart search enabled)

To search on documents and Extra Long Text fields, you must configure the smartSearchType parameter. If smartSearchType is null and similarityScoreThreshold is 1, document and Extra Long Text fields are not valid in searchFields since a keyword search is only applied.

Sort by similarity score

You can sort a read-only grid by similarity score to show the most relevant search matches first.

When you sort by similarity score, you must also configure a secondary sort. The secondary sort determines the grid's order when a user has not entered a search term, which means the similarity score is null.

To sort the grid by the highest similarity score:

1. In the initialSorts parameter of the read-only grid, define an array {} containing two a!sortInfo() functions.
2. In the first a!sortInfo() function, configure the following:
   • For field, enter recordType!<Record Type Name>.searchResults.allSearchFields.similarityScore. This will sort by the primary similarity score.
   • For ascending, enter false. This will sort from highest to lowest similarity score, placing more relevant results first in the list.

3. In the second a!sortInfo() function, choose a field to sort by when the grid first loads or when the search box is empty.

   For example:

1
2
3
4
5
6
7
8
9
10
11
12
  initialSorts: {
    /* Sorts by similarity score in descending order if there is a search */
    a!sortInfo(
      field: recordType!SSTA Case.searchResults.allSearchFields.similarityScore,
      ascending: false()
    ),
    /* Defaults to sorting by id field when there is no search */
    a!sortInfo(
     field: recordType!SSTA Case.fields.id,
     ascending: true
    )
  },

Tips for using smart search

• Search persistence:
  • Smart search and keyword search apply to their respective fields even if the columns are hidden in the grid (via the showWhen parameter) or if the fields are only referenced in the searchFields parameter and not displayed as columns.
• Performance:
  • Search time increases as the number of rows and searchable fields grows. To improve performance, limit the number of fields enabled for smart search, or use the searchFields parameter to restrict which fields are searched in the grid.
• Sorting and filtering:
  • In the initialSorts parameter, add a sort on the similarity score to show the most relevant results first by default.
  • Add a secondary sort to determine how to sort the grid when the search box is empty.
  • Use recordType!<Record Type Name>.searchResults.allSearchFields.similarityScore whenever possible to sort and filter since it will use the primary similarity score.
  • Only use recordType!<Record Type Name>.searchResults.<Field Name>.similarityScore to sort or filter by a similarity score for a specific field if your use case requires it.

Examples

The following example demonstrates the read-only grid component. The examples reference record types from another environment and will error if you try to use them in yours. Use them as a reference only.

Use async loading

This example shows how to use async loading for a specific column while the rest of the grid loads normally.

In the following expression, the status column uses an async local variable to query data separately and displays a placeholder until the data loads.

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
a!localVariables(
  local!statusId: a!asyncVariable(
    a!queryRecordType(
      recordType: recordType!IT Task,
      fields: {
        recordType!IT Task.fields.statusId
      },
      pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 10)
    ).data
  ),
  {
    a!gridField(
      label: "Record List",
      data: recordType!IT Task,
      columns: {
        a!gridColumn(
          label: "Tasks",
          value: fv!row[recordType!IT Task.fields.task]
        ),
        a!gridColumn(
          label: "Grid Column",
          value: a!richTextDisplayField(
            value: {
              a!match(
                value: index(
                  local!statusId,
                  fv!identifier,
                  recordType!IT Task.fields.statusId,
                  null
                ),
                equals: 1,
                then: {
                  a!richTextIcon(icon: "circle-o-notch", color: "SECONDARY"),
                  " Not Started"
                },
                equals: 2,
                then: {
                  a!richTextIcon(icon: "spinner", color: "ACCENT"),
                  " In Progress"
                },
                equals: 3,
                then: {
                  a!richTextIcon(icon: "check-circle", color: "POSITIVE"),
                  " Done"
                },
                default: "-"
              )
            }
          )
        )
      }
    )
  }
)

Apply smart search to the default search box

This example shows how to apply semantic search to a grid using the default search box.

In the following expression, the grid searches on the support case title (shown as a column in the grid) and the case description (an extra long text field not displayed in the grid).

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
{
  a!gridField(
    label: "Support Cases",
    labelPosition: "ABOVE",
    data: recordType!RE Case,
    showRefreshButton: true,
    /* Enables default search box */
    showSearchBox: true,
    /* Specifies the fields to search on */
    searchFields: {
      recordType!RE Case.fields.title,
      recordType!RE Case.fields.description
    },
    /* Sets the type of smart search to apply */
    smartSearchType: "SEMANTIC",
    /* This similarity score range is for example purposes only */
    /* The similarity scores you choose will depend on your data and search criteria */
    similarityScoreThreshold: 0.4,
    columns: {
      a!gridColumn(
        label: "Title",
        value: a!defaultValue(
          fv!row[recordType!RE Case.fields.title],
          "–"
        ),
        sortField: recordType!RE Case.fields.title
      ),
      a!gridColumn(
        label: "Status",
        value: if(
          isnull(
            fv!row[recordType!RE Case.fields.isOpen]
          ),
          "–",
          a!richTextDisplayField(
            value: if(
              fv!row[recordType!RE Case.fields.isOpen],
              a!richTextIcon(
                icon: "pencil",
                altText: "In progress",
                color: "SECONDARY"
              ),
              a!richTextIcon(
                icon: "check",
                altText: "Closed",
                color: "#138901"
              )
            )
          )
        ),
        sortField: recordType!RE Case.fields.isOpen,
        align: "CENTER"
      ),
      a!gridColumn(
        label: "Created On",
        value: if(
          isnull(
            fv!row[recordType!RE Case.fields.createdOn]
          ),
          fv!row[recordType!RE Case.fields.createdOn],
          datetext(
            fv!row[recordType!RE Case.fields.createdOn],
            "default"
          )
        ),
        sortField: recordType!RE Case.fields.createdOn,
        align: "END"
      ),
      a!gridColumn(
        label: "Modified On",
        value: if(
          isnull(
            fv!row[recordType!RE Case.fields.modifiedOn]
          ),
          fv!row[recordType!RE Case.fields.modifiedOn],
          datetext(
            fv!row[recordType!RE Case.fields.modifiedOn],
            "default"
          )
        ),
        sortField: recordType!RE Case.fields.modifiedOn,
        align: "END"
      )
    },
    initialSorts: {
    /* Sorts by similarity score in descending order if applicable */
      a!sortInfo(
        field: recordType!RE Case.searchResults.allSearchFields.similarityScore,
        ascending: false
      ),
      a!sortInfo(
        field: recordType!RE Case.fields.title,
        ascending: true
      )
    },
    refreshAfter: "RECORD_ACTION",
  )
}

See the Display Semantic Search Match Quality in a Read-Only Grid recipe to learn how to display a column in a read-only grid that illustrates if the semantic search results are strong, moderate, fair, or weak.

Image next to text in a grid column

The following example shows how to display a user image next to their name in a single grid column using a!sideBySideLayout().

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
a!gridField(
  label: "Employees",
  data: recordType!Employee,
  columns: {
    a!gridColumn(
      label: "Employee",
      sortField: recordType!Employee.fields.name,
      value: a!sideBySideLayout(
        items: {
          a!sideBySideItem(
            width: "MINIMIZE",
            item: a!imageField(
              images: a!userImage(user: fv!row[recordType!Employee.fields.username]),
            )
          ),
          a!sideBySideItem(
            item: a!richTextDisplayField(
              value: a!richTextItem(
                text: fv!row[recordType!Employee.fields.name],
                style: "STRONG"
              )
            )
          )
        }
      )
    ),
    a!gridColumn(
      label: "Department",
      sortField: recordType!Employee.fields.department,
      value: fv!row[recordType!Employee.fields.department]
    )
  }
)

Plain text in a side by side item

Plain text strings aren't compatible with a!sideBySideItem(). To display text alongside another component, wrap it in a!richTextDisplayField().

The following expression shows the correct way to combine text with a tag:

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
a!gridField(
  label: "Employees",
  data: recordType!Employee,
  columns: {
    a!gridColumn(
      label: "Employee",
      sortField: recordType!Employee.fields.name,
      value: a!sideBySideLayout(
        items: {
          a!sideBySideItem(
            width: "MINIMIZE",
            item: a!imageField(
              images: a!userImage(user: fv!row[recordType!Employee.fields.username]),
            )
          ),
          a!sideBySideItem(
            item: a!richTextDisplayField(
              value: fv!row[recordType!Employee.fields.name]
            )
          )
        }
      )
    ),
    a!gridColumn(
      label: "Department",
      sortField: recordType!Employee.fields.department,
      value: fv!row[recordType!Employee.fields.department]
    )
  }
)

Feature compatibility

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.

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

Related recipes

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

• Aggregate Data and Conditionally Display in a Chart or Grid (Reports, Charts, Query Data, Grids, Records):

  Aggregate data and conditionally display it in a pie chart or grid. In this pattern, we will calculate the total number of employees in each department and display it in a pie chart and a read-only grid. Then, we'll use a link field to conditionally display each component.

• 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.

• Configure a Chart Drilldown to a Grid (Charts, Grids, Query Data, Records):

  Displays a column chart with aggregate data from a record type and conditionally shows a grid with filtered records when a user selects a column on the chart.

• Configure a Chart to Grid Toggle (Charts, Grids):

  Display a column chart with a toggle to display an alternate grid view of the data.

• Configure a Custom Search Box with Smart Search (Grids, Query Data, Records):

  Implement smart search in a custom search box for a read-only grid.

• Delete Rows in a Grid (Grids):

  Delete one or more rows of data in a read-only grid.

• Display Last Refresh Time (Auto-Refresh, Grids, Records):

  Display the last time the interface was updated, either based on a user interaction or a timer.

• Display Processes by Process Model with Status Icons (Grids, Images, Reports):

  Use an interface to display information about instances of a specific process model.

• Display Semantic Search Match Quality in a Read-Only Grid (Grids, Query Data, Records):

  Display a column in a read-only grid that illustrates if the semantic search results are strong, moderate, fair, or weak.

• Display a User's Tasks in a Grid With Task Links (Grids, Reports, Looping):

  Display the tasks for a user in a Read-Only Grid and allow them to click on a task to navigate to the task itself.

• 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.

• Filter a Grid Using a Dropdown (Grids, Filtering, Records):

  Configure a dropdown for users to filter data in a read-only grid.

• Filter the Data in a Grid Using a Chart (Charts, Grids, Filtering, Records):

  Display an interactive pie chart with selectable sections so that a user may filter the results in a grid.

• Grid With Detail Pattern (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, Heading component):

  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.

• 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.

• More-Less Link (Grids, Rich Text):

  Use this pattern to keep grids with rows containing varying text lengths looking clean and uniform. This design also improves readability and the user experience by limiting the amount of text in the interface.

• Offline Task Report (Grids, Filtering, Process Task Links, Task Reports, Looping):

  Display a task report for a user that will work in Appian Mobile, even when the user is offline.

• Refresh Data Using a Refresh Button (Auto-Refresh)
• 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.

• Show Calculated Columns in a Grid (Formatting, Grids, Records):

  Display calculated values in columns in a grid.

• Task Report Pattern (Grids, Filters, Process Task Links, Task Reports):

  Provides a simple way to create and display an Appian task report.

• 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 Write to Data Store Entity Smart Service Function on an Interface (Smart Services, Grids, Looping):

  Allow the user to publish several rows of data to a table through the a!writeToDataStoreEntity() smart service function.

Feedback