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.
Function: a!gridField()
Displays a read-only grid where you can display data as rich text, links, images, buttons, tags, and record actions. The grid supports selecting, sorting, and paging. The read-only grid is designed to be fast and easy to setup from Design Mode, and features a natural integration with the Query Editor.
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 |
|
Text |
Text to display as the grid label. |
Label Position |
|
Text |
Determines where the label appears. Valid values:
|
Instructions |
|
Text |
Supplemental text about this grid. |
Help Tooltip |
|
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 |
Empty Grid Message |
|
Text |
Text to display in the grid when no data is available. Default is |
Data |
|
List of Dictionary, DataSubset, or PortalReportDataSubset |
The data to display in the grid. Can be configured using |
Columns |
|
List of |
The columns to display in the grid, configured using |
Rows to Display Per Page |
|
Number (Integer) |
The maximum number of rows to display at a time. Default: 10 |
Initial Sorts |
|
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 |
|
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 |
|
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 |
Selectable |
|
Boolean |
Determines if grid rows are selectable. When selection style is |
Selection Style |
|
Text |
Determines the style when a row is selected. Valid values: |
Selection Value |
|
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 |
|
List of Save |
One or more variables that are updated with the selected identifiers when the user changes selections. Use |
Selection required |
|
Boolean |
Determines if a selection is required to submit the form. Default: |
Selection Required Message |
|
Text |
Custom message to display when a selection is required and not provided. |
Disable Row Selection |
|
Boolean |
'Enter an expression that evaluates to true or false. The expression is run for each row. When the expression evaluates to true, that row is disabled. You can reference fields from the source using |
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 |
|
Text |
When present, this field is only validated when a button in the same validation group is pressed. |
Visibility |
|
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 |
|
Text |
Determines the spacing within grid cells. Valid values: |
Height |
|
Text |
Determines height of the grid. Valid values: |
Border Style |
|
Text |
Determines the style of the grid border. Valid values: |
Shade alternate rows |
|
Boolean |
Determines whether alternate rows are shaded. Default: true. |
Row Header |
|
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 |
|
Text |
Additional text to be announced by screen readers. Used only for accessibility; produces no visible change. |
"AUTO"
width, each column's width is determined by the length of the longest value in that column.ROW_HIGHLIGHT
does not have any visual indicator when selection is disabled through the Disable Row Selection (disablerowselectionwhen) parameter.-1
.fetchTotalCount: true
).When you use the query editor in Design Mode to generate a query for the grid, from the Data parameter, the grid will automatically configure certain elements for you.
-1
from Design Mode.fv!row.<fieldname>
, where the field name is converted to title case.
...
).fv!row.<fieldname>
<fieldname>
"END"
.fixed()
function to two decimal places. Ex. value: fixed(fv!row.cost, 2)
.You can find example configurations of the grid at Configuring the 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:
fv!pagingInfo
.fv!selectedRows
, fv!deselectedRows
) that can be used to avoid requerying data.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.
No, you don't. The new grid doesn't require local variables since you can pass the data directly to the grid and it will automatically refresh on data change; you don't need to use a!localVariables()
, load()
, or with()
.
The only two cases where you will need to use local variables are (1) if you want to manually manage your paging, or (2) if you want to take advantage of additional capabilities of a!refreshVariable
, such as configuring a refresh interval. For either of these cases, you should define a!localVariables()
outside of the grid's data parameter and then pass in the defined local variable to data.
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.
Aggregate Data from a Data Store Entity and Conditionally Display in a Chart or Grid (Reports, Charts, Query Data, Grids): Aggregate data from a data store entity, specifically the total number of employees in each department, to display in a pie chart.
Aggregate Data from a Data Store Entity on a Date or Date and Time Field (Reports, Query Data, Grids): Aggregate data from a data store entity, specifically the total number of employees by datet.
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): Display a pie chart with aggregate data from a data store entity that the user can interact with to display related chart data.
Configure a Chart to Grid Toggle (Charts, Grids): Display a column chart with a toggle to display an alternate grid view of the data.
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): 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 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 the Data in a Grid (Grids, Filtering): Filter the data in a read-only grid using a dropdown. When the user selects a value to filter by, update the grid to show the result.
Filter the Data in a Grid Using a Chart (Charts, Grids, Filtering): Display an interactive pie chart with selectable sections so that a user may filter the results in a grid.
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.
Limit the Number of Rows in a Grid That Can Be Selected (Validation, Grids): Limit the number of rows that can be selected to one.
Master Detail Pattern (Grids): The master-detail pattern allows users to select an item from a grid to see more details next to the grid.
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 Fields (Grids, Filtering, Reports): Display a grid populated based on search criteria specified by end users.
Show Calculated Columns in a Grid (Formatting, Grids): Display calculated values in columns in a grid.
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.