Exercise 03: Build an Editable Grid 

In order to complete the tutorial, you will need an Appian 19.3 (or
later) practice environment.

If you don't have a practice environment, you can request an

Appian trial site by going to ​https://appian.com/platform/free-trial/​.
Trial environments are available for 14 days.
Table of Contents 

What You Will Learn 3

Part 1 - Create the Getting Started Objects 4

Part 2 - Create the Layout and Add Variables 5

Add a Local Variable 6
Add a Rule Input 7

Part 3 - Configure the Editable Grid 7

Add the Editable Grid Component 8
Adjust the Widths of Columns 10
Configure the Components to Use in a Row 11
Use the forEach function to Display a Row for Each Item 13
Configure the Display and Save Into Fields for Each Row Component 14

Part 4 - Build the Add New Item Link 17

Part 5 - Build the In-Line Delete Button 19

Review New Concepts 22

This exercise is the fourth exercise in the ​Advanced Interfaces Exercise Series​.
The four exercises accompany our courses Interfaces 102 & Interfaces 103:

Interfaces 102: Build Interfaces Using Expressions

● Exercise: Build a Form Using Expressions

Interfaces 103: Build Dynamic Interfaces

● Exercise 01: Build a Dynamic List
● Exercise 02: Build a Dynamic Link
● Exercise 03: Build an Editable Grid

This is the last exercise in our ​Advanced Interfaces Exercise Series​. If you are
using the trial version of Appian and want to keep your sample interfaces as a

Build an Editable Grid Page 2

 reference, remember to export the ADV app before the expiration of your trial site.

What You Will Learn 

Editable Grids are a powerful tool in Appian. With it, you will be able to build tables that users
can edit directly from the interface. In this exercise, we will build a grid that will allow users to
add and remove the rows of information by simply clicking the ​Add New Item​ link or the ​red​ ​X
delete button:

To complete this exercise, we will create a couple of Getting Started objects. First, we will build
a CDT to provide a data structure for our office supply items. Second, we will create a constant
to hold the categories of office supply items. Third, we will build a simple interface containing a
rule input and a local variable that will hold the values for the office supply items (until we save
them into the rule input). After this prep work, we will add the Editable Grid component to the
interface, and we will configure its elements such as header cells, rows, and dynamic links. We
will build the grid using the Design Mode, and we will fine-tune it the Expression Mode.

While working with Editable Grids might seem taxing at first, this exercise will provide you with
the opportunity to learn more about the ​Hierarchy Interface​ feature that will help you locate
the appropriate screens and configurations quickly.

Let’s get started!

Build an Editable Grid Page 3

Part 1 - Create the Getting Started Objects 

Before we can build the Editable Grid component, we need to create a CDT that will provide a
structure for our office supply data. We will also need to create a constant that will hold the
categories for a dropdown field that we will have in the grid. Follow the steps below to create
these objects:

1. Log into your Appian environment, and open the ADV Interface Practice application.
Click ​New​, and select​ Data Type​. Select the radio button ​Create from scratch​. To
follow along with Appian’s best practices, edit the ​Namespace​ field to include the
application prefix​ ​ADV: ​urn:com:appian:types:ADV​. Type ​ADV_Items​ in the Name
field, and add a brief description (“Provides the structure for each item in the purchase
request”). Click ​Create​.

2. Add the CDT fields that will provide the structure for our editable Grid. Use the image
below to guide you through this process:

Check the ​Array​ box in the​ itemID​ row. Also, click the ​key icon​ for the itemID, and then
set it as the primary key and check the ​Auto-generate​ box:

Remember to click ​Save Changes​ after you add all fields to the CDT.

3. Now that you have created the ​ADV_Items​ CDT, let’s add it as a new entity to our
existing data store ​ADV DS​. Navigate to ​ADV DS​, and open it. Scroll down, and click

Build an Editable Grid Page 4

 Add Entity​. Click within the ​Type​ field, locate ​ADV_Item​, and click ​Select​. Enter ​items
into the Name field. Scroll down, click ​Verify​ and then ​Save & Publish​.

4. Create a constant to hold the categories for our Editable Grid. Click ​New​ > ​Constant​. In
the Create Constant dialog box, name the constant
ADV_PURCHASE_REQUEST_CATEGORIES​, and provide a brief description
(“Constant to hold the categories for the Purchase Request grid”). Select ​Text​ as the
type, check the ​Array​ box, and enter the categories (Office Supplies, Hardware,
Software, Miscellaneous) into the ​Values​ field. Do not use any punctuation, and enter
each item on a new line. In ​Save In​, select the ADV Constants folder. Click ​Create​. Your
entries will look as follows:

Part 2 - Create the Layout and Add Variables 

In this part, we will create a basic interface, and then we will add local variables and a rule input
to it. Local variables will help us handle the information entered by users. The rule input will map
the information about each office supply item to the corresponding columns of the database
table. Follow the steps below to set up the interface:

1. In the Appian Designer, click​ New​ > I​ nterface​. Name the interface ​ADV_EditableGrid​,
add a simple description, select the ​ADV Interfaces​ folder for the ​Save In​ field, and click
Create​.

2. From the ​Select a template​ pane on the right-hand side, select the one-column
template. Click the ​template​ to set up the form. After the form is displayed, delete one of

Build an Editable Grid Page 5

 the sections, and remove the title in the remaining section. Retitle the form: delete the
default ​Form​ in the title, and type​ Purchase Request​ (this can be done directly in the
interface).

Add a Local Variable

3. Now, let’s add the ​local!newGridRow​ variable to our interface. This local variable will
handle the addition of new items to the purchase request. As it is with local variables, It
will hold the information for each item temporarily, until it gets saved into the rule input.

4. Click the ​Expression Mode​ button on the toolbar. In the ​Interface Definition​ pane, fold
the blank section layout by clicking the ​arro​w next to line 1:

a. Place the cursor before a!formLayout, and press ​Enter​. On line 1, type
a!localVariables​. Delete the closing parenthesis at the end of line one, and
press the down arrow to move to the end of line 2. Press ​Enter​, and type the
closing parenthesis​ for the a!localVariables function. This wraps the interface
components within the local variable.

b. Return to the end of line 1. Press ​Enter​ to add another line, and type
local!newGridRow​ to create the local variable for the form. Type the colon, and
use the type constructor to map the local variable to the desired data type. In our
case, it will be the ​ADV_Items​ CDT. Type ​type!​, and use the autocomplete to
select the correct CDT. After the correct data is inserted, click at the end of the
line, and add a ​comma ​to separate the local variable from the rest of the
interface. Your expression will look as follows:

The rule input ​ADV_Items​ will help us map the information provided about each
item to the columns in the database table.

Build an Editable Grid Page 6

Add a Rule Input
5. Next, we will add the rule input to the interface. While local variables are responsible for
holding the information temporarily, rule inputs allow the data to flow from the interface to
its more permanent storage in the database.

a. Press ​CTRL + i​, or click the +

​ ​ button for the new rule input located on the top
right of the Interface Designer:

b. In the ​New Rule Input dialog​ box, enter the name ​items​. In the T ​ ype​ field,
remove the ​Text​ data type and start typing ​ADV_Items​ to select the data type
that we need for this exercise. Finally, select the ​Array​ checkbox. The Array
option for the rule input will allow users to add multiple items via this interface.

c. Click ​Create​.

Part 3 - Configure the Editable Grid 

Next, let’s add the Editable Grid to the interface. This step will involve working in the Design
Mode. We will drag the Editable Grid component to the canvas first, and then we will use the
options available via the Design Mode to configure the Headers and Rows for our Grid. Follow
the steps below to configure the grid.

Build an Editable Grid Page 7

Add the Editable Grid Component

1. Click ​Design Mode​ on the toolbar. In the ​Components Palette​, scroll down to the ​Grids
group.

2. Drag the ​Editable Grid​ component onto the canvas. Notice that its properties are now
displayed in the ​Component Configuration​ pane. Scroll down in this configuration pane
to configure the fields of the Editable Grid.

3. Change the label of the component to ​Items​.

4. Scroll down to ​Header Cells​, and click the link ​List of Any Type​. We will need six
headings for our grid. Five to describe the columns of data for each item, and we will

Build an Editable Grid Page 8

 leave one blank to include a delete button (if our users need to delete an item from their
Purchase Request). Click ​Add Item​ until you have six Header Cell items.

5. Press the ​Edit as Expression​ button on the top right of the component configuration:

6. You will notice that the Header Cells dialog box contains the list of header cell
components that we just created. In the Expression, change the Header Cell ​labels​ to:

● Description
● Category
● Qty
● Unit Price
● Amount
● Blank: use the open and close quotation marks to create a blank header (we will
use for the Delete an Item column.

Your expression will look like this:

Build an Editable Grid Page 9

 Once you are done editing the labels, click ​OK​. Use the ​Up Arrow​ button at the top of
the Component Configuration to step back into the Editable Grid Configuration options:

TIP: How Do I Navigate between Elements of a Grid?

Navigating between the elements of an Editable Grid might feel confusing at times, and it might
take time to get used to moving between the elements using the Up Arrow, especially if you
drilled deeply into the components of the grid. If at any point you need a reminder where you are
in the grid, pull out the Interface Hierarchy to quickly scan your interface. If you recall, we
learned to use this helpful tool in your previous exercise. To pull out the Interface Hierarchy, rest
the pointer on the left border of the ​Component Configuration​ pane. When you notice that it
turned into a slider, pull the full ​Component Configuration​ out to show the ​Interface
Hierarchy​.

Adjust the Widths of Columns

Next, let’s configure the widths of each column.

1. Under Column Configurations, click ​List of Column Configurations

Build an Editable Grid Page 10

 2. You will see the​ Add Item​ button. Click it 6 times to add a Column Configuration entry
for each column. We will adjust the width of each column, to provide more space for the
columns that will hold Description, Category, Unit Price, and Amount. Drill into each
Column Configuration, and set up the widths for all columns to ​Distribute​. For the last
column (with the blank header), the width should be set to ​Icon​. Set ​Weight​ for
Description​ and ​Category​ column at ​3,​ and for ​Unit Price​ and ​Amount​ to 2.

Examine the columns in the ​Edit​ pane, and notice that the widths of columns changed.
Click the ​Up Arrow​ button once to return to the Column Configurations, and click it again
to return to the ​Editable Grid​ Configuration (or simply use the Interface Hierarchy to
navigate there).

Configure the Components to Use in a Row

Now, we will need to configure the rows of the Editable Grid, i.e. add the row element and
configure the components of the row to match those set up in our header cells. Follow the steps
below to complete this configuration:

Build an Editable Grid Page 11

 1. In the ​Editable Grid​ pane, scroll down to the ​Rows​ configuration, and click ​List of Any
Type​:

2. Under ​Rows​, click the ​Add Item​ button. A row is added to the list. However, you will
notice that the live view of the grid is now giving an error message. This is because the
row must be configured with the number of components that match header cells. We will
set up the structure of our rows next.

3. Click the ​Row​ link. In the new screen, click ​List of Components​ under the ​Contents
heading:

4. You will see ​Add Component​. We need to add the components to our row to match the
number of components in the header row. Click ​Add Component​. You will notice that
the ​Add Componen​t dialog box contains an extensive list of options. Now we will need
to choose the right option for each row component. Add 6 components, configuring each
as follows:

Build an Editable Grid Page 12

 ● Component 1 (Description) - select ​Text
● Component 2 (Category) - select ​Dropdown
● Component 3 (Qty) - select ​Integer
● Component 4 (Unit Price) - select ​Decimal
● Component 5 (Amount) - select ​Text
● Component 6 (Blank) - select ​Rich Text (​ this formatting will allows us to fashion
a red X button for the deletion of selected items in the table)

Use the forEach function to Display a Row for Each Item

In the previous step, we set up the structure, or components, of our row. Now we need to
configure our Editable Grid to build a row for each item that a user might want to add to the
Purchase Request form. We will do so by adding the ​a!forEach​ looping function directly into the
expression. Follow the steps below to complete this configuration:

1. Click the ​Up Arrow​ to return to the Row configuration, and click the ​Edit as Expression
button:

2. Fold the grid row layout by clicking the ​arrow​ next to line 1. Press ​Enter​ to add a new
line at the start, and type ​a!forEach​. Allow the autocomplete to insert the function, and
then delete the closing parenthesis. Re-add it after the folded grid layout:

3. Press the ​Up Arrow​ to return to the end of the first line, and press ​Enter​ to add a line.
On line 2, type ​item​,​ ​and press ​Enter​ to accept the ​items​ keyword suggestion. After the
auto-filled colon, type ​ri!items (​ accept the autocomplete suggestion when prompted).

4. Add a comma after ​ri!items​, and press ​Enter​ to start a new line.

Build an Editable Grid Page 13

 5. On the next line, type ​expression, ​and​ ​press ​Enter​ to accept the autocomplete
suggestion. Click the format button on the toolbar to clean up the formatting, and click
OK​. At this point, your expression will look as follows:

Configure the Display and Save Into Fields for Each Row Component
Now we will need to drill deeper into the grid to configure the ​Display​ and ​Save Into ​fields for
each component. To do so, we will need to navigate to the configuration pane located under
Contents​ in the Editable Grid. To navigate to the correct screen quickly, open up the ​Interface
Hierarchy​, and click ​Contents​ under ​forEach​. Notice that the Contents pane with the list of
components will appear to the left from the Interface Hierarchy:

1. Click ​Text​ to access the configuration options for this component. Change the label to
Description​.

● Click the ​Edit as Expression​ button next to the ​Display Value​ field. We will
need to configure the display value for this field using the ​function variable

Build an Editable Grid Page 14

 item​, or ​fv!item​. This variable is used along with the a!forEach looping function,
and its purpose is to index the items within each looping iteration. If we need to
drill deeper into the elements of an item, we can do so by using the ​dot notation​.
For example, to index the description component, we will type the following:
fv!item.description​. So, in the Expression Editor, type ​fv!item.description​.

● Configure the ​Save Input To​ field using the same method. Click ​Edit as
Expression​, and type ​fv!item.description​.

● Scroll down, and check the ​Required​ box. It will make the description required
for each item users add to the list:

2. Click the ​Up Arrow​ to return to the list of components in our row.

Build an Editable Grid Page 15

 3. Click to access the ​Dropdown​ Component. Change the label to ​Category​. Using the
Edit as Expression​ button for each field, configure the fields as follow:

● Set ​Choice Labels​ and ​Choice Values​ using the constant

cons!ADV_PURCHASE_REQUEST_CATEGORIES​.

● Set ​Selected Value​ and ​Save Selection To​ to ​fv!item.category​.

● Check the ​Required​ box:

4. Click to access the ​Integer​ Component. Change the label to ​Qty​ Using the ​Edit as
Expression​ button for each field, configure the fields as follow:

● Set ​DisplayValue​ and ​Save Input To​ to ​fv!item.qty​.

● Check the ​Required​ box.

5. Click to access the ​Decimal​ Component. Change the label to ​Unit Price​. Using the ​Edit
as Expression​ button for each field, configure the fields as follow:

● Set ​Display Value​ and ​Save Input To​ to f​ v!item.unitPrice​.

● Check the ​Required​ box.

6. Click to access the ​Text ​Component. Change the label to ​Amount​. Using the ​Edit as
Expression​ button for each field, configure the fields as follow:

● Display Value​ for the Amount will be based on a calculation. We will use an
expression to calculate it. The expression will be quantity multiplied by unit price,
but the calculation will take place only if quantity and unit price values are
available.

Build an Editable Grid Page 16

 To write the expression, we will use the ​if(),​ ​or()​, and ​isnull () ​functions to check
for the null values first. Then we will provide the formula to calculate the amount if
both conditions are met. Your expression will look like the snippet below. Take a
few moments to examine it before you click the ​Edit as Expression​ for the
Display Value ​field:

if( 
or(isnull(fv!item.qty), isnull(fv!item.unitPrice)), 
0, 
tointeger(fv!item.qty) * todecimal(fv!item.unitPrice) 
) 

● Set ​Save Input To​ to ​fv!item.amount​.

● Check the ​Required​ box.

Part 4 - Build the Add New Item Link 

We have configured the components needed to display the rows of the editable grid. Next, we
will build a clickable link that will enable users to add new rows to the Purchase Request table.
Follow the steps below to build the link:

1. From the Interface Hierarchy, select the ​Items ​node​ ​in the Editable Grid to display the
properties of the grid:

Build an Editable Grid Page 17

 2. In the Editable Grid configuration pane, scroll down to the ​Add Row Link​. Click ​Insert
Link​:

3. You will see a Dynamic Link added to the interface. In the Configuration Pane, click the
Dynamic Link​ under the ​Add Row Link ​heading to access the configurations for this
item. Configure the link as follows:

● Type ​Add New Item ​in the Label field.

● For the ​Save Value To ​field, click the ​Edit as Expression​ button. Enter the
following expression: 

{a!save(ri!items, append(ri!items, local!newGridRow))} 

 
As you type this expression, make sure to pay attention to the ​Documentation
Wizard​. It will provide insight into what a!save () and append () functions do.
Essentially, with this expression we are telling Appian to update our existing
information (or rule input values ​ri!items​) by appending to it the newly added
item (​local!newGridRow​).

4. Double-check your interface. Now it should look like this:

Build an Editable Grid Page 18

Part 5 - Build the In-Line Delete Button 

So far, we have configured each row and allowed users to add items to the grid. Next, we will
build a button that will enable users to delete unwanted items. We have reserved the last
column in the grid for this purpose. Let’s configure this column to display a ​red X​ button. Follow
the steps below to build the button:

1. In the Interface Hierarchy, once again click the ​Contents​ node for the editable grid rows.
You will see the components of each row. We have configured the first five components.
Now we have to configure the last ​Rich Text​ component. Click ​Rich Text​ to access the
configurations for this component.

2. To configure the ​Delete​ button, scroll down to the ​Display Value​ in the configuration
Pane. Click the Icon button:

3. After you click ​Icon​, the ​Search ​field will display. Type ​Times​ into ​Search​, and select
the ​X​. Click ​Insert​.

Build an Editable Grid Page 19

 4. Select the ​black X ​in the Editor, and click the ​Color Picker​ Icon on the toolbar. Select
the ​red color​ (labeled ​Negative​).

5. Click the ​Configure Items​ radio button. The S

​ tyled Icon​ link will display. Click it to
display its properties:

6. In the Configuration Pane for the Styled Icon component, type ​Delete Row Button​. In
the ​Alternative Text​ field. Under the ​Link​ heading, click ​Select Link​:

7. After you click ​Select Link​, you will be presented with the list of options. Select
Dynamic Link​, and in the Configuration Pane click ​Dynamic Link​ to drill into the
configuration options.

Build an Editable Grid Page 20

 8. Configure the ​Save Value To​ field for the ​Dynamic Link​ by clicking ​Edit as Expression
and entering the following expression into the Editor:

{a!save(ri!items, remove(ri!items, fv!index))} 

As you type this expression, make sure to once again pay attention to the
Documentation Wizard​. It will provide insight into what a!save () and remove ()
functions do. Essentially, with this expression we are telling Appian to update our
existing information (or rule input values ​ri!items​) by removing a row (​fv!index​).

9. Test out the Delete button. Add a new item to the grid, and then remove it by clicking the
red X ​button!

Bite-Sized Editable Grid Challenge

Now that you’ve learned how to work with Editable Grids, how would you go about adding a
new row to the grid with the total sum for all office supply items? Use the tips below to add
and configure this additional row. We even provide the expression to calculate the sum value
below!

Hint:​ Use the Interface Hierarchy to locate the Editable Grid component, and use the ​Add
Item​ button to add a row. Within the row, add 6 items (each of the ​Text ​type). Configure the
Display Values for items 4 and 5 by clicking ​Edit as Expression​. For column 4, type “Total.”
For column 5, use the following expression:

dollar(sum(a!forEach( 
items: ri!purchaseRequest.items, 
expression: tointeger(fv!item.qty) * todecimal(fv!item.unitPrice) 
))) 
 
Use the Documentation Wizard to study this expression. Configure all cells in the row to be
Read-only​.

Build an Editable Grid Page 21

Review New Concepts 

At this point, you should have a better understanding of the steps required to build an Editable
Grid with the dynamic Add and Delete buttons. Before you advance any further, skim through
the topics below. If any of these topics still seem fuzzy, review the steps in the exercise, and
build the interface once again, paying attention to the a!forEach looping function, configuration
of nested elements using the fv!item, and the set-up of dynamic links.

In this exercise, we learned how to:

● Use ​rule inputs​ and ​local variables​ to accept values from the user
● Use the ​a!forEach​ looping function and ​fv!item ​variable to configure and reference the
components of a row in an Editable Grid
● Use the ​a!save​, ​append​, and ​remove ​functions to teach Appian how to update rule
input values by either adding or removing the rows of information
● Access the ​Interface Hierarchy​ pane for the panoramic view and quicker access to the
interface components
● Use expressions to define the values of calculated fields

Build an Editable Grid Page 22