Read-Only Grid Component

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

Read-Only Grid

Function: a!gridField()

Displays read-only text, links, and images in a grid that 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.

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

Parameters

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

List of Dictionary, DataSubset, or PortalReportDataSubset

The data to display in the grid, configured using 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.

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 in the grid (same as batch size). 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 be 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

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. It works just like the showWhen parameter. You can reference fields from the source using fv!row.[fieldName]. For example, you can disableRowSelectionWhen: isnull(fv!row.status). Default: false. You can also reference the identifier of the row using fv!identifier.

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.

Configuration Notes

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

Examples

Below are some basic examples. You can find more examples from our library of Interface Patterns.

Copy and paste an example into the INTERFACE DEFINITION in EXPRESSION MODE to see it displayed.

Embedded Query

Embedding the query (or rule with query) is the simplest and most common way to configure the grid. Insert your query directly into the data parameter from the query editor. The resulting expression will look something like this:

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
a!gridField(
  data: a!queryEntity(
    entity: cons!EMPLOYEE_ENTITY,
    query: a!query(
      selection: a!querySelection(columns: {
        a!queryColumn(field: "firstName"),
        a!queryColumn(field: "lastName"),
        a!queryColumn(field: "department"),
        a!queryColumn(field: "title"),
      }),
      pagingInfo: fv!pagingInfo
    ),
    fetchTotalCount: true
  ),
  columns: {
    a!gridColumn(
      label: "First Name",
      sortField: "firstName",
      value: fv!row.firstName
    ),
    a!gridColumn(
      label: "Last Name",
      sortField: "lastName",
      value: fv!row.lastName
    ),
    a!gridColumn(
      label: "Department",
      sortField: "department",
      value: fv!row.department
    ),
    a!gridColumn(
      label: "Title",
      sortField: "title",
      value: fv!row.title
    )
  },
  pageSize: 20,
  initialSorts: a!sortInfo(
    field: "firstName",
    ascending: true
  ),
  rowHeader: 1
)

Displays the following:

images/Grid_simple_75.png

Embedded Rule with Query

You can embed a rule that contains a query and still leverage fv!pagingInfo for convenience.

Rule with Query OSM_GetProductsWithCategory

Add a rule input for the paging info to your rule that contains a query. In this example it's ri!pagingInfo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/* OSM_GetProductsWithCategory */
a!queryEntity(
  entity: cons!OSM_ITEM_ENTITY,
  query: a!query(
    selection: a!querySelection(
      columns: {
        a!queryColumn(field: "id"),
        a!queryColumn(field: "name"),
        a!queryColumn(field: "description"),
        a!queryColumn(field: "category"),
        a!queryColumn(field: "model"),
        a!queryColumn(field: "unitCost"),
        a!queryColumn(field: "manufacturer")
      }
    ),
    pagingInfo: `ri!pagingInfo`
  ),
  fetchTotalCount: true
)

Grid Calling OSM_GetProductsWithCategory

Call the query from the data parameter, passing fv!pagingInfo.

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
a!gridField(
  label: "Products",
  labelPosition: "ABOVE",
  data: rule!OSM_GetProductsWithCategory(fv!pagingInfo),
  columns: {
    a!gridColumn(
      label: "ID",
      sortField: "id",
      value: fv!row.id,
      align: "END"
    ),
    a!gridColumn(
      label: "Name",
      sortField: "name",
      value: fv!row.name
    ),
    a!gridColumn(
      label: "Description",
      sortField: "description",
      value: fv!row.description
    ),
    a!gridColumn(
      label: "Category",
      sortField: "category",
      value: fv!row.category
    ),
    a!gridColumn(
      label: "Model",
      sortField: "model",
      value: fv!row.model
    ),
    a!gridColumn(
      label: "Unit Cost",
      sortField: "unitCost",
      value: dollar(fv!row.unitCost,2),
      align: "END"
    ),
    a!gridColumn(
      label: "Manufacturer",
      sortField: "manufacturer",
      value: fv!row.manufacturer
    )
  }
)

Displays

ID Name Description Category Model Unit Cost Manufacturer
1 Mid-Back Black Mesh Swivel Task Chair This mesh task chair provides exceptional support to the hard-working professionals in your office.Transparent mesh across the back allows air to circulate, keeping you cool. Misc. Supplies 24115D $242.99 Career Transitions, Corp.
2 1949558 Color Burst Permanent Markers, Ultra Fine Point Crank up the color with limited Edition Sharpie color burst permanent markers! Intensely bright, the supercharged shades create energizing visuals that always stand out. Pens, Pencils & Markers 37600PP $13.75 K-Mart
3 Premier Colored Pencils, Soft Core, 150-Count Bring out the soft side of any illustration or art project with Premier Colored Pencils featuring soft cores. Pens, Pencils & Markers 5567F $27.55 Amazon
4 KDT 2-Line Engineering Calculator Dual power: one AA battery( not included) and solar panel helps make sure that the calculator will function even in a dim place. Misc. Supplies T189 $82.50 Staples
5 HP OfficeJet 3830 All-in-One Wireless Printer with Mobile Printing Main functions of this HP color inkjet compact printer: copy, scan, wireless printing, AirPrint, Instant Ink ready so you'll never run out of ink, and more Tech HP OfficeJet 3830 $82.34 HP
6 Texas Instruments TI-89 Titanium Graphing Calculator The TI-89 Titanium lets you perform basic math, algebra, calculus, graphs, matrices, and statistical functions and creating animations, graphing 3-D rotations, and plotting contours. Misc. Supplies TI 89 $130.98 Wal-Mart
7 BIC Brite Liner Highlighter, Chisel Tip, Assorted Colors, 5-Count Super bright fluorescent ink in yellow, pink, blue, orange, and green. Chisel tip for broad highlighting or fine underlining. Pens, Pencils & Markers 8873 $4.50 Office Max
8 #2 Pencils With Eraser Tops - HB Graphite/No 2 Yellow Wood Pencil COLORE Yellow Pencils are offered in an extremely affordable bulk pack containing a total of 12 Sets of 12 pencils each set (144 pencils in total). Pens, Pencils & Markers 12020-KSD $21.05 Staples
9 Tontion 2400 Lux Video Projector supporting 1080P -50,000 Hour Upgraded LEDs with 30% higher lumens output – brighter than other projectors on the market. Upgraded cooling fan – reduced fan noise, as low as laptop fan noise. Misc. Supplies TG800 $82.35 Wal-Mart
10 E-Z Ink (TM) Compatible Ink Cartridge Replacement for Canon E-Z Ink compatible ink cartridges replacement for Canon PGI-250XL CLI-251XL are manufactured in an ISO 9001 & ISO14001 certified facility. Printer Ink & Toner MG5520 $19.89 E-Z Ink

Display a 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
a!gridField(
  label: "Employees",
  data: todatasubset(
    {
      {name: "Elizabeth Ward",  dept: "Engineering",     role: "Senior Engineer"},
      {name: "Michael Johnson", dept: "Finance",         role: "Payroll Manager"},
      {name: "John Smith",      dept: "Engineering",     role: "Quality Engineer"},
      {name: "Diana Hellstrom", dept: "Engineering",     role: "UX Designer"},
      {name: "Francois Morin",  dept: "Sales",           role: "Account Executive"},
      {name: "Maya Kapoor",     dept: "Sales",           role: "Regional Director"},
      {name: "Anthony Wu",      dept: "Human Resources", role: "Benefits Coordinator"}
    },
    fv!pagingInfo
  ),
  columns: {
    a!gridColumn(
      label: "Name",
      sortField: "name",
      value: fv!row.name
    ),
    a!gridColumn(
      label: "Role",
      sortField: "role",
      value: fv!row.role,
    ),
    a!gridColumn(
      label: "Department",
      sortField: "dept",
      value: fv!row.dept
    )
  },
  pageSize: 5
)

Display an Array of Data

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
a!gridField(
  label: "Example: Display Data in a Read-Only Grid",
  data: {
    {id: 1, name: "John Smith",      department: "Engineering"},
    {id: 2, name: "Michael Johnson", department: "Finance"},
    {id: 3, name: "Mary Reed",       department: "Engineering"},
    {id: 4, name: "Angela Cooper",   department: "Sales"},
    {id: 5, name: "Elizabeth Ward",  department: "Sales"},
    {id: 6, name: "Daniel Lewis",    department: "Human Resources"}
  },
  columns: {
    a!gridColumn(
      label: "ID",
      sortField: "id",
      value: fv!row.id,
      align: "END"
    ),
    a!gridColumn(
      label: "Name",
      sortField: "name",
      value: fv!row.name
    ),
    a!gridColumn(
      label: "Department",
      sortField: "department",
      value: fv!row.department
    )
  },
  pageSize: 3,
  initialSorts: a!sortInfo(field: "name", ascending: true),
  rowHeader: 2
)

See Also

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.

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!gridSelection

The paging grid natively supports selection.

a!gridField_19r1

Now supports embedded queries, columns widths, and rich text.

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

FEEDBACK