a!gridField_26r2 Component

Function

a!gridField_26r2( 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 )

Displays a grid of data as rich text, links, images, buttons, tags, record actions, or progress bars. This grid component also supports searching, filtering, selecting, sorting, and paging. 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 also:

• Grid Tutorial: Learn how to build a read-only grid with selection, conditional formatting, row filtering, and dynamically displaying content.
• Configuring the Read-Only Grid: Understand different configuration and data options for read-only grids.

Parameters

Usage considerations

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

Consider the following when creating 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.

Autopopulate a grid with a record list

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.

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

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.

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 and style 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.

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

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

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.

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.
• The selectionStyle of ROW_HIGHLIGHT does not have any visual indicator when selection is disabled through the disableRowSelectionWhen parameter.
• 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.

Configuring grid paging

• 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.
• When a read-only grid is used offline, paging and sorting don't function and images won't render.
• If you are managing your own paging, you cannot pass a datasubset which has a paging configuration that uses a batch size of -1.
• 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).

Grid height and column width

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

• For columns using the "AUTO" width, each column's width is determined by the length of the longest value in that column.

  • See the read-only grid column component for more information on using the "AUTO" width.
  • For complete guidance on when and how to use column widths, see 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

By default, the search box in a read-only grid uses a keyword search to find exact matches to a user's search terms. You can implement semantic search in this default search box, or by building a custom search box for the grid.

Depending on which search box you’re using, the way you implement semantic search and how it behaves will differ:

• In the default search box:
  • When implemented, both smart search and keyword search are applied to the grid. Smart search will apply to all columns that reference fields with smart search enabled, and keyword search will apply to all columns with text and number (integer) fields.
  • Learn how to implement smart search in the default search box.
• In a custom search box:
  • When implemented, smart search is only applied to fields that are filtered by a "search" operator.
  • Learn how to implement smart search in a custom search box.

Using the Similarity Score Threshold parameter

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

Using higher values in this parameter will set a stricter similarity requirement, returning fewer and more relevant results. Lower values will return more results with a broader range of relevance.

By default, this parameter is 1 to return only exact or partial keyword matches. To use both keyword search and smart search in the grid, lower this value.

Appian recommends starting with a lower threshold to test the types of results returned. You can then raise the threshold based on your observations to find the best score for your specific data and use case. See general guidelines for interpreting similarity scores to help pick your threshold.

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 smart search

• Setup:
  • Verify that the fields you want to search are enabled for smart search.
  • Confirm that the smart search indexing status for your record type is Completed.
  • Ensure the fields with smart search enabled are displayed as columns 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. You should also 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.
• Display:
  • Add a column to the grid to illustrate the search result quality, so users understand why certain results are higher than others. See the Display Smart Search Match Quality in a Read-Only Grid recipe for an example.
• Performance:
  • Search time increases as the number of rows and searchable fields grows. To improve performance, limit the number of fields and rows being searched when possible. For example, searching 10,000 rows is faster than searching 1 million rows.

Examples

You can find example configurations of the grid at Configuring the Read-Only Grid and Grid Tutorial. These examples only use keyword search to search through the grid.

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

Record type object references are specific to each environment. If you copy and paste these examples into your interface, they will not evaluate. Use them as a reference only.

Async column example

This example shows how to use async loading for a specific column while the rest of the grid loads normally. The status column uses an async local variable to query data separately and displays a placeholder until the data loads.

This works great in an interface that is primarily made up of a grid and you know that one or two columns in particular will take longer than the rest of the grid to load.

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: "-"
              )
            }
          )
        )
      }
    )
  }
)

Feature compatibility

Feedback