Grid Tutorial

Introduction

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

In this tutorial, you'll learn all the major features and functions of the read-only grid by creating a grid with selection pattern in Design Mode (the best way).

Use Case

We've been asked to create a grid list that displays a complete list of all employees in the company. From the grid, we should be able to select any number of employees to be entered into a raffle and configure a secondary display zone that populates a list of selected employees by their first and last name. We've also been asked to prevent the selection of employees in the Sales department (since they're already drowning in additional compensation), but allow them to still show up in the grid list.

00_finished_version.png

The interface you'll create is a variation of the Grid with Selection pattern. Component patterns are a great way to get started quickly, or learn from expert designs.

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 in Design Mode
  • 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

This tutorial requires basic familiarity with the Appian platform. If you are brand new to Appian, head over to Appian Academy Online and explore the many, free courses available.

Before beginning this tutorial, you must first:

In this tutorial, we'll be working with the following design objects and components:

Set up the read-only grid

First, we're going to set up our grid in Design Mode by dragging the read-only grid component from the Components Palette.

  1. Log in to Appian Designer, navigate to your tutorial application, and open the 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

      01_setup_new_interface.png

  3. From the COMPONENTS PALETTE, drag the READ-ONLY GRID component onto your blank interface.

    01 drag grid

Select the data source

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

  1. From the DATA section, select QUERY and click CREATE QUERY.

    02_create_query.png

  2. Enter EMPLOYEE_ENTITY when prompted to select the data store entity constant.
  3. Click CONTINUE to launch the Query Editor.

Configure a query

The query editor makes creating queries easy.

For our query, we only need the following fields:

  • id
  • firstName
  • lastName
  • department
  • startDate

However, in the Fields section, you can see that all fields are selected by default.

To remove the fields you don't need from the Query Results Preview:

  1. Hover over the options menu ( ) for the title and phoneNumber columns, and click REMOVE.

    03_query_editor.png

  2. Click GENERATE QUERY.

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

    03_grid_preview.png

If you're just reading this tutorial, and you see the image above 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 the query results and automatically populates the grid columns, makes them sortable, and takes a good guess as to what your column names might be. In addition, when Appian detects a column with numbers or dates, it aligns the field data to the right for you.

Set paging & sorting

You can configure paging and sorting for the query, but the grid handles both natively. This allows you to change these settings from the COMPONENT CONFIGURATION panel.

  1. From the PAGING & SORTING section, enter 5 in Rows to Display Per Page.
  2. Under Initial Sorts, click ADD SORT.
    • Note that when you add an initial sorts parameter in Design Mode, the following error message will display. The error will resolve when you enter a field name:

      "Interface Definition: Expression evaluation error at function a!gridField [line 2]: Expression evaluation error at function a!queryEntity [line 5]: Cannot sort by a blank field."

  3. In Field, enter lastName.
  4. For Order, select Ascending.

    04_page_n_sort.png

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

Configure columns

Appian automatically passes the field data returned from the query into their respective columns. 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 and change the format of the Department column to italics and conditionally change the color of the text.

Remove a column

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

  1. From the Columns section, hover over the Options menu ( ) for Id (Grid Column), and click X to delete the ID column.

    05_remove_id.png

Format a column

Now, let's format the Department column by changing the text style.

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

    images/05_display_options_tags.png

  4. In the Display Value for the styled text, click the Rich Text link.
  5. With Configure items selected, click the Styled Text link.
  6. From the Style dropdown, select Emphasis.

Conditionally change the text color in a column

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 the row; otherwise it'll be null (the default).

    05_sales_grey.png

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 familiar with interface design, you can follow the higher-level steps below to add a display zone. If you're still somewhat new to interface design in Appian, skip to these directions.

  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:
    • Styled Icon (user-circle).
    • Styled Text (no changes).
  5. Jump to 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 increase the width.

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

Add a display field

Add a display field, there is a missing step to add the label "Selected Employees" to the Rich Text component. Probably a good step 2, "For the Label, enter Selected Employees." The label is in the screenshots.

Now, let's add a display field

  1. Drag a RICH TEXT component from the COMPONENT PALETTE into the second column.
  2. For the Label, enter Selected Employees.
  3. For the Display Value, with Use editor selected, click the Icon button ().
  4. Enter user-circle into the search box and select this icon (), and click INSERT.
  5. In the editor, after the icon, enter ` First Last`.

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

    06_rich_confirmation.png

Add selection and local variables

To set up grid selection, you need to create a local variable to save the selection value into. In our case, we also need to pass the selected row's data to a local variable so we can display the selected employees in the display zone. To accomplish this, 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 need to switch to Expression Mode.

  1. From the toolbar, click EXPRESSION MODE.
  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
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    
       a!localVariables(
       local!selection,
       local!selectedEmployees,
       {
         a!columnsLayout(
           columns: {
             a!columnLayout(
               contents: {
                 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
                     )
                   },
                   validations: {}
                 )
               },
               width: "WIDE"
             ),
             a!columnLayout(
               contents: {
                 a!richTextDisplayField(
                   label: "Rich Text",
                   labelPosition: "COLLAPSED",
                   value: {
                     a!richTextIcon(
                       icon: "user-circle"
                     ),
                     " First Last"
                   }
                 )
               }
             )
           }
         )
        }
       )
       
    

Don't forget to add the final close parenthesis on line 78.

Now, switch back to DESIGN MODE.

Configure selection values

  1. In Design Mode, select the Read-Only Grid component to get to the component configuration.
  2. From the SELECTION section, select Selectable.
    • This will enable selection for the grid, and provide some additional configurations below.
  3. From the Selection Value dropdown, select local!selection.
  4. Hover over Save Selection To until the Edit as Expression icon () appears, then click it.
  5. 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))
    }
    
  6. 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.

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
    
    {
      a!richTextIcon(
        icon: "user-circle"
      ),
      " First Last"
    }
    
  3. Replace that expression with this one:

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

Select Scott Bailey**, *Laura Bryant, and Janet Coleman in the grid to see that name appear on the right.

08_selected_names.png

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.

Be sure to unselect the employee records you selected in Populate display section before proceeding with the steps in this section.

  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

Filter ineligible rows

Now that you've had a good look at your grid, you realize not everyone will be interested in seeing those employees in Sales who aren't eligible for the raffle. So, we're going to add an option to hide those rows with a checkbox. For this, we're going to use the method described in the Configure a Boolean Checkbox pattern.

Set variable & default

Before we create the checkbox, let's first create a local variable to store the checkbox value, and set a default value on load.

  1. Click EXPRESSION MODE from the toolbar.
  2. Insert another local variable (local!showIneligible: true) on line 4.

    1
    2
    3
    4
    5
    
    a!localVariables(
      local!selection,
      local!selectedEmployees,
      local!showIneligible: true,
      {
    

Add a checkbox

Now that we have the local variable, we're ready to set up the checkbox to have only one option, and for that option to toggle true and null in the variable to act as a switch for the filter we will create in the next section.

  1. Click DESIGN MODE from the toolbar.
  2. Drag a Checkboxes component from the palette onto the canvas, just above the grid.

    10_checkboxes.png

  3. From the COMPONENT CONFIGURATION panel, under the Checkboxes section, select Hidden for Label Position.
  4. From Choice Labels, click the List of Text link.
  5. Delete the second item (hover over the options menu , and click the X).
    • Note that the interface will warn you that your options and values don't match; ignore the warning for now.
  6. Replace the text for the first item with: Show ineligible employees

    10_showbox

  7. Click Checkboxes to navigate up.

Set up the checkbox

  1. From Choice Values, click the List of Any Type link.
  2. Delete the second item and click on the number 1 link.
  3. In the expression editor, replace the value (1) with: true
  4. Click OK.

    10_choicevalues

  5. Click Checkboxes to navigate up.
  6. Hover over Selected Values until the Edit as Expression icon () appears, then click it.
  7. Enter this expression: if(local!showIneligible, true, null)
  8. Click OK.
  9. Hover over Save Selection To until the Edit as Expression icon () appears then click it.
  10. Enter this expression:

    1
    2
    3
    4
    5
    6
    7
    8
    
    a!save(
      local!showIneligible,
      if(
        isnull(save!value),
        false,
        true
        )
    )
    
  11. Click OK.

Now the checkbox is all set up, let's connect a query filter to it.

Edit the query

We're going to add a simple filter to the query to exclude employees in the Sales department. This filter exclusion will only run when the checkbox variable (local!showIneligible) is false.

  1. Click on the grid to select it, then from the COMPONENT CONFIGURATION, under Data, click EDIT QUERY to re-launch the Query Editor.
  2. From the Filters section, click the Add Filter link. This adds an empty row to the filters table.

    10_emptyfilter

  3. For Field, select department.
  4. For Condition, select <>.
  5. For Value, enter Sales.
  6. From Apply Filter, click the Always link.
  7. In the expression editor, enter: not(local!showIneligible)
  8. Click OK.
    • Your filter should look like this:

      10_fullfilter

  9. Click GENERATE QUERY.
  10. Click SAVE CHANGES to save the changes to your interface.

Now you can toggle the checkbox on and off to view or hide the Sales rows.

Finish up and celebrate

Now that it's all working, let's wrap up:

  1. Double-click on Read-only Grid and change that label to Employee Directory.
  2. Double-click on the Rich Text component in the display zone and change the rich text label to Selected Employees.
    • For Label Position, select Above.

That's it!

images/grid_tutorial/00_finished_version.png

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.

Open in Github

On This Page

FEEDBACK