Paging Grid Component

Paging Grid

SAIL Function: a!gridField()

Displays read-only text, links, and images in a grid that supports selecting, sorting, and paging. To organize editable inputs in a tabular layout, use an editable grid.

Parameters

Name Keyword Type Description
Label label Text Optional text to display as the field label.
Label Position labelPosition Text Optional text to determine where the label appears. Valid values include
  • "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.
Instructions instructions Text Optional text that displays below the label.
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".
Total Count totalCount Integer Total number of rows of data for all pages in the grid.
Empty Grid Message emptyGridMessage Text Text to display in the grid when no data is available. Default is "No items available".
Columns columns Array of Text Columns or Image Columns Holds an array of Text or Image columns that configure and define the data or links to display for each column in the grid. Configured using a!gridTextColumn(label, field, data, alignment) or a!gridImageColumn(label, field, data, alignment).
Identifiers identifiers Text or Integer Array Accepts an array of text or integers that are used to determine which rows are selected.
Paging and Selection Value value PagingInfo or GridSelection Holds the paging and sorting configurations for the grid as well as which rows in the grid should be selected. When defined with the variable configured in Save Paging and Selection To, it allows users to change the sort column, view another grid page, or select and deselect rows. When the type is GridSelection, checkboxes appear for each row if selection is enabled. When the type is PagingInfo, no checkboxes appear.
Save Paging and Selection To saveInto Save Array One or more variables that are updated with the paging or grid selection configuration when the user pages, sorts, or changes the grid's selections. Use a!save() to save a modified or alternative value to a variable.
Selectable selection Boolean Determines if the rows in the grid are selectable. Default is false.
Selection required requireSelection Boolean Determines if a selection is required to submit the form. Default is false.
Required Message requiredMessage Text Custom message to be displayed when a selection is required and not provided.
Disabled disabled Boolean Determines if the user is prevented from changing which rows are selected. Default is false.
Validations validations Text Array Validation errors to be displayed below the field when the value is not null.
Validation Group validationGroup Text When present, this field is only validated when a button in the same validation group is clicked.
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.

Notes

  • If the Columns argument is null or empty, an error occurs when the SAIL is opened.
  • Each column’s width is determined by the length of the longest value in that column. If the sum of those widths surpasses the allotted space, a horizontal scroll bar displays for users to view the remaining data. The allotted space for the grid depends on its placement in a one-column layout or two-column layout within the SAIL.
  • The order of items in the array for Columns determines the order of the columns. The order of items in the Data array in each Columns item determines the default order of the data.
  • Spaces and line breaks are supported within a column’s Label and Data values.
  • A column’s Data values may come from Appian engines, relational databases, or other data sources.
  • If the Data value for a column is empty or null, the grid still renders the column with just the label.
  • If the length of any Data array in the Columns argument is null or less than the Total Count argument, an error occurs when the SAIL is opened.
  • If the Field argument for a column is null, it does not display a sort indicator even if the data is sorted by that column.
  • Each time a user interacts with the grid, it outputs a value of type PagingInfo that is then saved in your Save Paging and Selection To parameter which is used to refresh and render the grid accordingly.
  • If you pass a null value to the value parameter, an error occurs when the SAIL is opened.
  • If the batchSize value in Paging and Selection Value is less than the length of any Data array in columns, an error occurs when the SAIL interface is opened.
  • If the startIndex value in Paging and Selection Value is greater than the totalCount argument, an error occurs when the SAIL interface is opened.
  • Passing a local variable with the load() function to the value parameter and passing the same local variable to the Save Paging and Selection To parameter allows for re-evaluation of the expression when users click a column to change the sorting or navigate to another page of the grid.
  • Paging and sorting do not function when this component is used offline. Images in the grid do not render when offline.
  • Paging controls are not displayed when the grid has 5 or fewer rows and all rows are on one page.
  • Paging controls to jump to the first or last page are not displayed when a grid has 100 or fewer total items. This reduces clutter on smaller grids.

Examples

Copy and paste an example to the Interface Designer to see it displayed.

Grid Showing Static Columns

    =a!gridField(
      label: "Employees",
      totalCount: 5,
      columns: {
        a!gridTextColumn(
          label: "Name",
          data: {"John Smith", "Michael Johnson", "Mary Reed", "Angela Cooper", "Elizabeth Ward"},
          alignment: "LEFT"
        ),
        a!gridTextColumn(
          label: "Title",
          data: {"Director", "Analyst", "Software Engineer", "Sales", "Sales"},
          alignment: "LEFT"
        ),
        a!gridTextColumn(
          label: "Department",
          data: {"Engineering", "Finance", "Engineering", "Sales", "Sales"},
          alignment: "LEFT"
        )
      },
      value: a!pagingInfo(
        startIndex: 1,
        batchSize: 5,
        sort: a!sortInfo(
          field: "name",
          ascending: true
        )
      )
    )

Displays the following:

Single-Column Grid with Paging/Sorting

    =load(
      local!pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 5, sort: a!sortInfo(field: "label", ascending: true)),
      local!sampleData: {
        type!LabelValue(label: "John Smith"),
        type!LabelValue(label: "Michael Johnson"),
        type!LabelValue(label: "Mary Reed"),
        type!LabelValue(label: "Angela Cooper"),
        type!LabelValue(label: "Elizabeth Ward"),
        type!LabelValue(label: "Daniel Lewis"),
        type!LabelValue(label: "Paul Martin"),
        type!LabelValue(label: "Jessica Peterson"),
        type!LabelValue(label: "Mark Hall"),
        type!LabelValue(label: "Rebecca Wood")
      },
      with(
        local!datasubset: todatasubset(local!sampleData, local!pagingInfo),
        local!dataForCurrentPage: local!datasubset.data,
        a!gridField(
          label: "Employees",
          instructions: local!pagingInfo,
          totalCount: local!datasubset.totalCount,
          columns: {
            a!gridTextColumn(
              label: "Name",
              field: "label",
              data: index(local!dataForCurrentPage, "label", null),
              alignment: "LEFT"
            )
          },
          value: local!pagingInfo,
          saveInto: local!pagingInfo
        )
      )
    )

Displays the following:

NOTE: If you sort or page through this example, you’ll notice the instructions change. We’ve configured this value as local!pagingInfo to show how the pagingInfo value changes each time the expression is re-evaluated.

Single-Column Grid with Static Links

    =a!gridField(
      totalCount: 4,
      columns: {
        a!gridTextColumn(
          label: "Company Information",
          data:{
            "Company Website",
            "LinkedIn",
            "Twitter",
            "Facebook"
          },
          links: {
            a!safeLink(uri: "http://www.appian.com"),
            a!safeLink(uri: "http://www.linkedin.com/company/appian-corporation"),
            a!safeLink(uri: "https://twitter.com/appian"),
            a!safeLink(uri: "https://www.facebook.com/AppianCorporation")
          },
          alignment: "LEFT"
        )
      },
      value: a!pagingInfo(
        startIndex: 1,
        batchSize: 4,
        sort: a!sortInfo(
          field: "name",
          ascending: true
        )
      )
    )

Displays the following:

Two-Column Grid with Process Task Links

    =load(
      local!pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 4, sort: a!sortInfo(field: "label", ascending: true)),
      local!sampleData: {
        type!LabelValue(label: "Smith, John"),
        type!LabelValue(label: "Johnson, Michael"),
        type!LabelValue(label: "Reed, Mary"),
        type!LabelValue(label: "Cooper, Angela")
      },
      with(
        local!dataForCurrentPage: todatasubset(local!sampleData, local!pagingInfo).data,
        a!gridField(
          totalCount: length(local!sampleData),
          columns: {
            a!gridTextColumn(
              label: "Name",
              field: "label",
              data: local!dataForCurrentPage.label,
              alignment: "LEFT"
            ),
            a!gridTextColumn(
              label: "Open Task",
              data: {
                "Expense Approval",
                "Expense Approval",
                "Timesheet Approval",
                "Timesheet Approval"
              },
              links:{
                a!processTaskLink(task: 1382),
                a!processTaskLink(task: 1377),
                a!processTaskLink(task: 536870918),
                a!processTaskLink(task: 268436948)
              },
              alignment: "LEFT"
            )
          },
          value: local!pagingInfo,
          saveInto: local!pagingInfo
        )
      )
    )

Displays the following:

See Also

Tempo Report Design Best Practices: Includes best practices for configuring a grid on a Tempo report for optimal performance and usability.

Grid Tutorial: Details the steps for creating a Tempo report using a grid component that shows data queried from an external database and allows for sorting and paging.

SAIL Recipe: Filter the Data in a Grid: Filter the data in a grid using a dropdown.

SAIL Recipe: Select Rows in a Grid: Display checkboxes on a grid to allow users to select multiple rows of data.

SAIL Recipe: Limit the Number of Rows in a Grid That Can Be Selected: Constrain the number of selections by using validation.

SAIL Recipe: Delete Rows in a Grid: Delete one or more rows of data in a grid.

SAIL Recipe: Use Links in a Grid to Show More Details About an Object: Display more of an object's data than can fit in a single row in a grid.

SAIL Recipe: Use Links in a Grid to Show More Details and Edit Data: Allow users to click a link in a grid to view the details for the row and make changes to the data.

SAIL Recipe: Use Links in a Grid to Show More Details and Edit Data in an External System: Allow users to click a link in a grid to view the details for the row and make changes to the data that are immediately persisted to the external system where the data resides.

FEEDBACK