Grid Tutorial

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

We've been asked to create a grid 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.

Time to complete: About 15 minutes

Experience level: Beginner

Tutorial requirements

To complete this tutorial, you need:

• Appian Tutorial application. Complete the Application Building Tutorial to store the interface used in this tutorial.
• AT Employee record type: Complete the Create the AT Employee record type section of the Record Type Tutorial, including the Generate a database table subsection.
• Appropriate group membership. You must be a member of the Designer system group. If you're unsure about your group membership, contact your system administrator.

Set up the read-only grid

Once you've completed the application and record type setup, we can start building our grid.

To set up the grid:

1. In the Appian Tutorial application, go to the Build view.
2. Click NEW > Interface.

3. Configure the following interface properties:

   Property	Action
   Name	Enter AT_raffleGrid
   Description	Enter Grid for selecting employees for the raffle.
   Folder	Keep the default AT Rules & Constants

4. From the COMPONENTS palette, drag the READ-ONLY GRID component onto your blank interface.

Select the data source

After dragging the grid onto your interface, you can select your record data using the Component Configuration panel on the right.

To select a data source for your grid:

1. In the Component Configuration pane, go to the Data tab.
2. Leave the default selection of RECORD TYPE.

3. In the Search record types field, enter AT and select AT Employee.

   Your grid is now populated with the employee data from the record type.

   

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 a record type as the data source of a grid, Appian automatically queries the record type and populates the grid with the record list configuration.

Set paging & sorting

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

To set paging and sorting on the grid:

1. In the Component Configuration pane, go to the Data tab.
2. For Rows to Display Per Page, enter 5.
3. Under Initial Sorts, click ADD SORT.
4. For Field, select lastName.
5. For Order, select Ascending.
6. Click Read-only Grid to navigate back up to the grid properties.

Configure columns

When you select a record type as the data source, the grid will automatically populate with the record list configuration. The grid's columns will match the columns selected in the record list, but you can modify them as required for the interface you're building.

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 Start Date column, the display value is fv!row[recordType!AT Employee.fields.startDate].

In this section, we'll remove a column from the grid and update the formatting on another columns.

Remove a column

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

1. In the component configuration pane, go to the Data tab.
2. Under Columns, hover over the Options menu ( ) for Title (Grid Column), and click X to delete the Title column.

Format a column

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

1. In the Data tab, under Columns, click Department (Grid Column).
2. Go to the Data tab.
3. Under Display Value, click DISPLAY OPTIONS.
4. In Display Options, select TEXT from the RICH TEXT TYPE row.
5. In the Display Value field for the grid column, click the Rich Text link.
6. In the Display Value field for the Rich Text, click the Text Item link under Configure items.
7. Go to the Styling tab.
8. 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. In the Styling tab, hover over the Color field until the Edit as Expression icon appears, then click it.

2. In the expression editor, enter:

   1
   2
   3
   4
   5
   if(
      fv!row[recordType!AT Employee.relationships.department.fields.value] = "Sales",
      "SECONDARY",
      null
   )
   

3. Change the record type reference to use the record type reference in your environment.

   Note:  Record type references are specific to each environment, which is why you need to change the references whenever you copy and paste a record type reference from outside the application.

4. Click OK.

   Now when the row evaluates, if the Department in that row is Sales, the text color will be set to "SECONDARY"; otherwise it'll be null (the default).

   

Add display zone

Since our grid has selection and paging, it's a 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 display component in the right column.
4. In that rich text display component, add two items:
   • Rich text icon (user-circle).
   • Rich text item (First Last).
5. Jump to Add local variables and selection.

Add columns

We'll add a columns layout so that our grid is in one column, and the grid rows appear in the other column.

To add a columns layout:

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

   

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

   

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.

   

Now that the column is selected, let's increase the width.

1. In the Component Configuration pane, go to the Styling tab.
2. For Width, select Set fixed width.
3. From the dropdown, select Wide.

Add a display field

Now, that the grid is in one column, we'll add a display field in the other column. The display field will show all of the selected grid rows.

To add a display field:

1. Drag a RICH TEXT component from the Component Palette into the second column.
2. In the Component Configuration pane, for Label, enter Selected Employees.
3. For Label Position, select Above.
4. For the Display Value, with Use editor selected, click the Icon button .
5. Enter user-circle into the search box and select this icon , and click INSERT.

6. In the editor, after the icon, enter First Last.

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

   

Add local variables and selection

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:

1. From the Local Variables panel toolbar, click the New Local Variable icon.
2. For Name, enter selection.
3. Click CREATE AND ADD ANOTHER.
4. For Name, enter selectedEmployees.
5. Click CREATE.

Configure selection values

1. In design mode, select the Read-Only Grid.
2. In the Component Configuration pane, go to the Behavior tab.
3. Turn on Selectable. This will enable selection for the grid, and provide some additional configurations below it.
4. From the Selection Value dropdown, select local!selection.
5. Hover over Save Selection To until the Edit as Expression icon appears, then click it.

6. 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))
   }
   

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

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.

2. In the Component Configuration pane, 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[recordType!AT Employees.fields.firstName] & " " & fv!item[recordType!AT Employees.fields.lastName]&char(10)
     }
   )
   

4. Change the record type reference to use the record type reference in your environment.
5. Click OK.

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

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.
2. In the Component Configuration pane, go to the Behavior tab.
3. For Disable Row Selection, select Only disable when… .
4. Click Edit Condition.

5. In the expression editor, replace the existing value with the following expression:

   1
   fv!row[recordType!AT Employee.relationships.department.fields.value] = "Sales"
   

6. Change the record type reference to use the record type reference in your environment.
7. Click OK.

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

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.

To add a local variable:

1. From the Local Variables panel toolbar, click the New Local Variable icon.
2. For Name, enter showIneligible.
3. For value, enter false().
4. Click CREATE.

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.

To add a checkbox:

1. Drag a Checkboxes component from the palette onto the canvas, just above the columns layout.
2. In the Component Configuration pane, for Label Position, select Hidden.
3. Go to the Data tab.

4. Under Choice Labels, hover over the options menu on the second item and click and click X to delete it.

   Note:  The interface will warn you that your options and values don't match; ignore the warning for now.

5. Replace the text for the first item with: Show ineligible employees
6. Under Choice Values, hover over the options menu on the second item and click and click X to delete it.
7. Click on the number 1 link.
8. In the expression editor, replace the value 1 with true.
9. Click OK.
10. Hover over Selected Values until the Edit as Expression icon appears, then click it.
11. Enter this expression: if(local!showIneligible, true, null)
12. Click OK.
13. Hover over Save Selection To until the Edit as Expression icon appears then click it.

14. Enter this expression:

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

15. Click OK.

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

Filter the grid

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

To filter the grid when the checkbox is selected:

1. Select the Read-only Grid.
2. In the Component Configuration pane, go to the Data tab.
3. Click FILTER RECORDS.
4. On the Filter Records dialog, click the Add Filter link. This adds an empty row to the filters table.
5. For Field, select department > value.
6. For Condition, select not equal to.
7. For Value, enter Sales.
8. From Apply Filter, click the Always link.
9. In the expression editor, enter local!showIneligible = false and click OK.
10. Click OK, then click SAVE to save the changes to your interface.

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

Rename the grid

Now that it's all working, let's wrap up by renaming our grid:

• Double-click on Read-only Grid and change that label to Employee Directory.

That's it!

Success!

You've created a read-only grid where you:

• Connected a record type as the data source.
• Set paging and initial sorting.
• Removed and formatted columns, including conditional text color.
• Added a secondary display zone using a columns layout and rich text.
• Configured grid selection with local variables to capture row data.
• Disabled row selection for specific rows based on a condition.
• Added a checkbox filter to show or hide ineligible rows.

Next steps

What you do next is up to you.

• You might want to limit the number of rows that can be selected to the number of raffle tickets you have. In which case, check out Limit the Number of Rows in a Grid That Can Be Selected.
• It probably makes sense to only enter people into the raffle who haven't been entered recently. Check out Show Calculated Columns in a Grid.

Learn more about the Read-Only Grid, and find more patterns and examples on the Read-Only Grid Component page.

Feedback