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 arrow 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 Component 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
