Grid Tutorial

Objectives

Learn how to create a read-only grid with the most common configurations in about 15 minutes. After completing this tutorial, you will know how to:

  • Create a read-only grid from Design Mode.
  • Launch and use the query editor from the context of a read-only grid.
  • Use the grid's function variables.
  • Format the display value of column data.
  • Configure selection for a grid.
  • Capture and share row data from a grid.
  • Conditionally disable row selection.

Requirements

Introduction to the Read-Only Grid

Grids are how we display data in a tabular format (AKA a table). A table in a database has a set of fields that, when populated, become the records. A grid displays those fields as columns, and the records as rows. The Appian read-only grid understands this relationship, and is designed to handle your data in intelligent ways.

In this tutorial, we're going to create a basic grid in Design Mode that will let the user see employees and select any number of them to enter into a company raffle (expect for employees in the Sales department, because they get plenty of additional compensation).

The interface you'll create is a variation of the Grid with Selection pattern.

1. Basic Setup of the Interface with a Grid

  1. Log in to Appian Designer, and navigate to your tutorial application
  2. From that application, create a NEW > Interface with the following attributes:
    • Name: AT_raffleGrid
    • Description: Grid for selecting employees for the raffle.
    • Folder: AT Examples (if it doesn't exist, create it by clicking the Create New Rule Folder link).

    01_setup_new_interface.png

Now, from the COMPONENTS palette, drag the READ-ONLY GRID component onto your blank interface.

2. Add Data

After dragging the grid into your interface, you can add data from the COMPONENT CONFIGURATION panel on the right.

  1. From the DATA section, with Use query editor selected, click CREATE QUERY.

    02_create_query.png

  2. When prompted for the Data Store Entity, enter EMPLOYEE_ENTITY.
  3. Click CONTINUE.

3. Configure Query

This is the query editor, which makes creating queries easy.

All you need to do here is select a few fields.

  1. In the Fields section, click REMOVE ALL, then select the following fields:
    • id
    • firstName
    • lastName
    • department
    • startDate
  2. Click GENERATE QUERY.

Your grid is now populated with the employee data from the query.

If you're just reading this tutorial, and you see the above screenshot and think, "Wait, that was too easy. I must have missed a bunch of steps somewhere." You can relax; you didn't miss anything. When you use the query editor from the context of a grid, Appian takes your query results and populates columns for you, makes them sortable, and takes a good guess as to what your column names might be. If it sees numbers or dates, it aligns them to the right for you.

4. Set Paging & Sorting

Paging and sorting is something you can configure for the query, but the grid handles both natively, allowing you to change them from the COMPONENT CONFIGURATION panel.

  1. From the Paging & Sorting section, in the Rows to Display Per Page field, enter 5.
  2. Under Initial Sorts, click ADD SORT.
    1. In Field, enter lastName.
    2. For Order, select Ascending.

      04_page_n_sort.png

    3. Click Read-only Grid to navigate back up to the grid properties.

5. Configure Columns

The field data from the query are passed into their respective columns automatically. The display value of every column is set with the function variable, fv!row. This variable contains all the data for the entire row. For example, in the First Name column, the display value is fv!row.firstName.

In this section we will remove the ID column, format the department column in italics, and conditionally change the color of the department text.

Remove ID Column

Since we don't need to see the employee's ID, let's remove it.

  1. From the Columns section, hover over the more-actions menu ( ) for Id (Grid Column), and click the X icon to Delete the column.

    05_remove_id.png

Format Department Column

  1. From the Columns section, click Department (Grid Column).
  2. From Display Value, click DISPLAY OPTIONS.
  3. From RICH TEXT, click STYLED TEXT.

  1. In the Display Value for the styled text, click the Rich Text link.
  2. With Configure items selected, click the Styled Text link.
  3. From the Style dropdown, select Emphasis.

Conditionally Change the Color of the Department Text

Since we don't want anyone from the Sales department entered into the raffle, let's remind the user by changing the color of "Sales" in that column.

  1. Hover over Color until the Edit as Expression icon () appears, then click it.
  2. In the expression editor, enter: if(fv!row.department="Sales", "SECONDARY", null)
  3. Click OK.

Now, when the row evaluates, if the department in that row (fv!row.department) is Sales, the color will be set to "SECONDARY" for that row, otherwise it'll be null (the default).

05_sales_grey.png

6. Add Display Zone

When grids have selection and paging, it's good UX practice to provide a secondary display so the user can see the totality of their selection no matter what page they're on.

If you're still somewhat new to interface design in Appian, follow these directions.

Shortcut If you're familiar with interface design, here are some higher-level steps you can follow, after which you can skip to section 7:

  1. Add a Columns Layout with two columns.
  2. Put the grid in the left column, and set the column width to WIDE.
  3. Put a Rich Text component in the right column.
  4. In that Rich Text component, add two items:
    1. Styled Icon (user-circle).
    2. Styled Text (no changes).
  5. Jump to 7. Add Selection.

Add Columns

  1. Drag a COLUMNS component from the palette to just below the grid.

    06_columns_drag.png

  2. Delete one of the columns by clicking on the Delete column icon ().

    06_delete_column.png

  3. Drag the grid into the first column.
  4. Hover over the Read-only Grid selector until the component hierarchy displays, then click Column Layout.

    06_grid_selector.png

Now that the column is selected, let's make it wider.

  1. For Width, select Set fixed width.
  2. From the dropdown, select Wide.

Add Display Field

  1. Drag a RICH TEXT component from the palette into the second column.
  2. Click the plus button () to Add a rich text component.
  3. Click STYLED ICON.

    06_styled_icon.png

  4. From the COMPONENT CONFIGURATION for the Rich Text component, for Display Value, select Configure items.
  5. Click Styled Icon.
  6. From the Icon dropdown, enter user-circle and select the icon ().
  7. Click Rich Text to navigate up.
  8. From Display Value, click ADD RICH TEXT, and choose STYLED TEXT.

And this is where we're going to leave it for now:

06_rich_confirmation.png

7. Add Selection

To setup grid selection, you only need to create a local variable to save the selection value to. In our case, we also need to pass the selected row's data to a local variable so we can display the selected employees somewhere. So, we're going to add two local variables, (1) local!selection for the grid's current selection, and (2) local!selectedEmployees for the row data of those selections.

To add these local variables, you finally get to switch to expression mode.

  1. Click EXPRESSION MODE from the tool bar.
  2. Wrap the expression with the a!localVariables() function, and add two local variables:
    • local!selection
    • local!selectedEmployees
    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
    
    !  a!localVariables(
    !    local!selection,
    !    local!selectedEmployees,
        {
          a!gridField(
            label: "Read-only Grid",
            labelPosition: "ABOVE",
            data: a!queryEntity(
              entity: cons!EMPLOYEE_ENTITY,
              query: a!query(
                selection: a!querySelection(
                  columns: {
                    a!queryColumn(
                      field: "id"
                    ),
                    a!queryColumn(
                      field: "firstName"
                    ),
                    a!queryColumn(
                      field: "lastName"
                    ),
                    a!queryColumn(
                      field: "department"
                    ),
                    a!queryColumn(
                      field: "startDate"
                    )
                  }
                ),
                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: a!richTextDisplayField(
                  value: {
                    a!richTextItem(
                      text: {fv!row.department},
                      color: if(fv!row.department="Sales", "SECONDARY", null),
                      style: {
                        "EMPHASIS"
                      }
                    )
                  }
                )
              ),
              a!gridColumn(
                label: "Start Date",
                sortField: "startDate",
                value: fv!row.startDate,
                align: "END"
              )
            },
            pagesize: 5,
            initialsorts: {
              a!sortInfo(
                field: "lastName",
                ascending: true
              )
            },
            selectable: true,
            validations: {}
          )
        }
    !  )
    

Make sure you got that final, close parenthesis on line 118.

Now, switch back to DESIGN MODE.

Configure Selection Values

Select the Read-only Grid to get to the component configuration.

  1. From the SELECTION section, select Selectable. (don't read that out loud)
    • This will enable selection for the grid, and provide some additional configurations below.
  2. From the Selection Value dropdown, select local!selection.
  3. Hover over Save Selection To until the Edit as Expression icon () appears, then click it.
  4. In the expression editor, enter this expression:

    1
    2
    3
    4
    5
    6
    7
    
    {
      local!selection,
      /* This save adds the full rows of data for items selected in the most recent user interaction to local!selectedEmployees. */
      a!save(local!selectedEmployees, append(local!selectedEmployees, fv!selectedRows)),
      /* This save removes the full rows of data for items deselected in the most recent user interaction to local!selectedEmployees. */
      a!save(local!selectedEmployees, difference(local!selectedEmployees, fv!deselectedRows))
    }
    
  5. Click OK.

You can now persist your selection. Try it out by selecting and deselecting rows. The selection index is saved to local!selection, and the row data for those selections is saved to local!selectedEmployees; you can't see that yet, but we'll set that up in the next section.

The grid is actually smart enough to use a single selection variable for both the selection index and the row data when you embed a query that returns a primary key, as the query will create a datasubset with the primary key as the identifiers. You can test it out by setting the Selection Value to local!selectedEmployees.id. If you only pass the data, the grid won't know which field is the primary key, so you'll need to create a second variable for the selection index; we show the two-variable method in this tutorial because it works in both cases.

8. Populate Display Section

It's time to configure the second column of our interface to show the employee names of the selected rows. With the components we want already setup, we're going to wrap them in a looping function (a!forEach()) to reuse them for every employee in local!selectedEmployees.

  1. Click on the Rich Text component to show its COMPONENT CONFIGURATION.
  2. Hover over Display Value until the Edit as Expression icon () appears, then click it.
    • You will see the following expression in the editor:

      1
      2
      3
      4
      5
      6
      7
      8
      
      {
        a!richTextIcon(
          icon: "user-circle"
        ),
        a!richTextItem(
          text: {"Styled Text"}
        )
      }
      
  3. Replace that expression with this one:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    {
      a!forEach(
        items: local!selectedEmployees,
        expression:{
          a!richTextIcon(
            icon: "user-circle"
          ),
          a!richTextItem(
            text: {" "&fv!item.firstName &" "&fv!item.lastName}
          ),
          char(10)
          }
      )
    }
    
  4. Click OK.

Select one of the rows in the grid to see that name appear on the right.

08_selected_names.png

9. Disable Selection for Sales

Changing the color of "Sales" isn't enough; to prevent users from selecting anyone in the Sales department, we're going to tell the grid to disable selection for rows when the department in that row is "Sales."

  1. Select the Read-only Grid to show the COMPONENT CONFIGURATION.
  2. Scroll down to Disable Row Selection and select Only disable when….
  3. Click Edit Condition.
  4. In the expression editor, enter: fv!row.department="Sales"
  5. Click OK.

Now employees in Sales can't even be selected from the grid. Try it out for yourself.

09_disabled.png

10. Tidy Up and Celebrate!

Now that it's all working, double-click on Read-only Grid and change that label to Employee Directory, and change the rich text label to Selected Employees. Aaaaand, yay!

We know that was pretty easy, but you should feel proud anyway.

What you do next, is up to you.

Learn more about the Read-Only Grid, and find more patterns and examples here.

FEEDBACK