In simple terms, a Sub List is a repeat table, which enables you to add multiple line items to an approval form. Your data are often inter-dependent. You may have the necessity to associate multiple items to a single record. In technical terms, we call these "line items". A sub list allows to add multiple line items to a single record.
For example, while ordering a mobile phone, a customer may place the order for accessories such as mobile charger, flip cover and a microphone - along with the main product. So, these become "sub-products". While customer A orders these three accessories, customer B may order another 5. Each accessory may require essential information such as amount, rate, quantity, discount and so on.
Below is how a sub list looks on a form:
When to use this Sub List field
The sub list field is best suited for enabling your users to enter data that has a master-detail relationship. Let us take an example of IT Asset Management (ITAM) to understand this.
Imagine that you are building an app to manage the devices - laptops, smartphones, and tablets, in your organization, and as part of it, want to capture the following for each device:
Its date of purchase
The purchase order number is was bought under
Vendor-related data like the name, email address, phone number, and address of the vendor from whom the purchase is made
Device-related data like the name, type, serial number, and price of the device
Well, accomplishing this isn't tough. You just need to create a form (say, Purchase Order Form), and share it with your asset manager. Imagine if your form allows the asset manager to submit the purchase details of one device per entry. Then, even if your asset manager purchases multiple devices from a vendor on the same date, he/she would have to submit that many entries through the Purchase Order Form. Consequently, the records stored in the Purchase Order Form will look (in its report) as if they represent separate purchases when they are not.
A sub list can help in this scenario. But let's first answer the question: Is a master-detail relationship present in this above scenario? Yes, it is. Here's how:
First, each devices is purchased from a vendor. This establishes that there is a relationship between a device and a vendor.
Second, does your IT manager purchase (from a vendor) one device at a time? Mostly, no.
As multiple devices may be purchased as part of the same order, the date of purchase, purchase order number and vendor-related data are the Master, with the device-related data being the Detail.
When you add a sub lit field in your form, such that it enables entering the details of devices being purchased, each time a purchase is made, your asset manager will be able to enter the details of all devices in one go. (Each purchase record can have multiple devices associated with it)
Add Sub List to the form
Firstly, find the Sub List control in the controls add panel. Then, drag and drop it into a section or container on the canvas.
Basic of the Sub List field
Open the Content > Basic block and set the Title's text of this Sub List control. For more information about Title for field control, please refer:
Set the Associated variable for this Sub List control. When you add a new Sub List control, a default variable will be generated automatically. You can click the Edit Button to change the ID and name, or click the Reset button to bind this Sub List control to other existing variables. For more information, please refer:
Set List Content
1. Choose layout of the sub list control
Move to the "List Content" section. Select the layout properly from the dropdown list.
There are 3 types of the layouts which you can select from:
Table View: Choose this option if you want to show the Sub List layout and items as a table. Each item the users added to this Sub List control will display as a row with pre-defined columns.
Card View: Choose this option will show the items one by one with separate area.
Dynamic: If the layout is set to Dynamic, the Sub List will be set to Table View on PC and Tablet device, and Card View on Mobile device.
Default: The default settings of the Layout is Dynamic.
The properties and styles of Table view and Card view can be set separately. So, if the Default/Dynamic layout is selected, you will be able to see all the related settings for both Table view and Card view. Otherwise, you will only see the table view related settings, or the card view related settings.
2. Allow users to switch layouts
If the layout of your sub list is set to Default / Dynamic, you will see an option with checkbox.
For Dynamic layout, the sub list will automatically use the Tabel View on PC and tablet, and switch to Card View on Mobile. If you want to provide a flexibility to allow users to switch between the table view and card view as they needed. You can check the checkbox. Once this option is checked. you will see 2 more icon buttons at the end of the Caption bar.
When users submit the form, view the submitted form, they will be able to use those to icon buttons to switch the layout:
2. Add fields and columns to Sub list control
To create and manage columns of this sub list control, go find the Fields settings after Layout. and click the "Settings" button to open the List column settings window.
Click the "Add Field" button to create new fields for this sub list. Each field here is similar like the associated variable for each field controls of the main form, which includes the Field ID, Field Name and Field Type.
You can change rename each field ID and Name, or select the type from the dropdown list. Click the checkbox for each field to show/hide in the Sub List as a column. For some cases, you might want to only show part of the fields on your Sub List, while hide others. Like on the submission form, only show the first 3 fields, while on the next task form, show another 2 fields for the task owner to see or fill in.
Click "OK" button to add those fields. The selected fields will be added to the Sub List as columns based on the sorting order.
You can drag to change the orders of each column, or click the Trash button to remove this column from the Sub List (this will NOT delete the related field, just like unselect the checkbox from the List Fields Settings window).
Next, click each column to expand the settings panel. You can change the Control type, like if the field type is Number, you can set the control type as Number, Percent, Currency, or Calculation. Then, click the "Settings" button after the Control Properties to set the properties and styles of each control.
In the Table View section, you can set the width of each column in PX or %. And from the Card View section, you can set the width of each control with percentage. For example, To show 4 controls in each row, you can set the width as 25% for each.
The Title Layout, Vertical Align, and Title Width settings help to set the positioning of the title for each control.
3. And summary fields
Using Summary settings to calculate the values of one column's all records. For example: calculate the total price of all products, or the average price of all orders etc.
To add a new summary field, click the "Settings" button in the Summary settings area. Then, click "Add" button to open the summary editor.
Field: Select which field you'd like to do the calculation.
Type: Select the operation type from the dropdown list regarding how would you like to calculate the values of this field. The available options depend on the type of this selected field. For numeric field, you can select Sum, Average, Min, or Max. while for non-numeric field, you can only select Concat.
Display: Choose whether show this summary field in the Sub List control.
Binding: If you want to have the result value of this Summary field to be reused, you can set the value to another field or variable on your main form. For example, If you use the summary field to calculate the total price of all purchase orders in the sub list. Then, use this sum value as the condition of the approval process (like if the total price is greater than 2,000, then go for CFO approval), you can bind this sum value to another variable and use in the following workflow design. Please refer this article to learn How to save the summary value of a sub list field to a separate variable.
Expand the Summary field's settings panel, under the Card View, set the container width.
4. Customize the Fallback Text
Next, from the Fallback settings section, set the text. This text will display when the Sub List do not have any items.
Appearance Settings
Display Caption: You can control if display or hide the caption by turn ON/OFF the Display Caption option settings.
Turn Collapse option ON to allow users to collapse and expend the grid content area.
Allow comment: Turn on this option will allow users to add comments on this control.
Dynamic Display Rules: When you set a dynamic display rules, It behaves differently based on specific conditions and rules. Learn how to create dynamic display rules for a control
.
Validation of the Sub List control
Open the Content > Validation block to set the properties of this Sub List control.
Readonly: Turn this ON will make this field control as view only status.
Required: Make it mandatory for your users to add at least one row of items.
Add Item: Turn this ON to allow users to add new row of items by clicking the "Add item" button. If this option is set to OFF, then users will not be able to see the "Add item" button.
Allow Import: If there are many items required to be added to this Sub List, you can turn this ON to allow users import data from excel file. When "Allow import" is enabled, the users have options to add item one by one, or bulk import to add a number of rows.
Pro Tip
To process bulk import, Each column header of your list should be unique, accordingly the upload file should have the same header name at the first row.
Delete Item: Turn this ON to allow users to delete existing rows of items by clicking the "Delete" button in front of or at the end of each item. If this option is set to OFF, then users will not be able to see the "Delete" button.
Custom Validation: Set the custom validation rules. An error message that will display under your field when specified conditions become true. It will allow you to add any number of rules for validating your field. Learn more about the Custom Validation
.
Styling the Sub List control
It is now time to define the appearance of the Sub List control. Go forward to the Style block, where you are able to make your table look more eye-candy.
General
Table View
Table Width: Set the width of the data table as fixed with px or percentage of the container with %.
Column Width: Set how the column width will be allocated for each column. Fixed means the column width will be exactly the value you set for each column in the column settings panel, while Auto means the column width will be scaled based on the total width of the Table Width set above, and allocated with the ratio of each column width.
Table Alignment: Choose between Right, Center, and Left.
Border Type: Select the type of border to use around the table.
Radius: Set the border radius to control corner roundness.
Shadow: Set options to apply a box shadow on the Data Table.
Card View
Margin: Set the Margin of the card view area in PX or %.
Padding: Set the Padding of the content insider in the card view area in PX or %.
Fallback
Set the Typography and Color of the text for Fallback.
Table Header
Padding: Change the padding settings of the content inside in each header cell.
Border Type: Select the type of border to use around the table header.
Align: Align the text of the table header to the left, center, or right.
Vertical Align: Vertical align of the table header text to top, middle, or bottom.
Typography: Change the default typography options for the text of table header.
Normal / Hover: Set different color and background color for the state of header.
Color: Select the color of the header’s text for both Normal and Hover states.
Background color: Select the header's background color for both Normal and Hover states. You may use a solid or gradient color.
Table Content
Row items
Set the styles of each row of item:Row Background Color: Select the background color of each row for both Normal and Hover states.
Padding: Change the padding settings of the content inside in each content cell.
Border Type: Select the type of border to use around the table content.
Summary
Set the styles of the Summary row:Row Background Color: Select the background color of the Summary row.
Padding: Change the padding settings of the content inside in each content cell.
Border Type: Select the type of border to use around the table Summary row.
Title: Set the Typography and Color for the Title text of each Summary field .
Value: Set the Typography and Color for the Value text of each Summary field .
Card Content
Margin: Set the Margin of each card item area in PX or %.
Padding: Set the Padding of the content insider in each card item in PX or %.
Background Color: Select the background color of each card item.
Border Type: Select the type of border to use around each card item.
Radius: Set the border radius to control corner roundness.
Shadow: Set options to apply a box shadow on each card item.
Content Padding: Set the padding of each control inside in the card item.
Card Summary
Margin: Set the Margin of the Summary card area in PX or %.
Padding: Set the Padding of the content insider in the Summary card area in PX or %.
Background Color: Select the background color of the Summary card area.
Border Type: Select the type of border to use around the Summary card area.
Radius: Set the border radius to control corner roundness.
Shadow: Set options to apply a box shadow on the Summary card area.
Content Padding: Set the padding of each summary field control inside in the Summary card area.
Content Alignment: Set the alignment of the content for each summary field control.
Title: Set the Typography and Color for the Title text of each Summary field .
Value: Set the Typography and Color for the Value text of each Summary field .
Delete Item Button
Set the styles of the delete item button for both table view and card view:
Normal / Hover: Set different color and background color for the state of delete item button.
Text Color: Select the color of the delete item button’s text for both Normal and Hover states.
Background color: Select the delete item button's background color for both Normal and Hover states.
Typography: Change the default typography options for the text of delete item button.
Margin: Set the Margin of the delete item button in PX or %.
Padding: Set the Padding of the delete item button in PX or %.
Border Type: Select the type of border to use around the delete item button.
Radius: Set the border radius to control corner roundness.
Shadow: Set options to apply a box shadow on the delete item button.
Position: Set the position to display the delete item button to be the start or end of the each row.
Add Item Button
Set the styles of Add new item button for both table view and card view:
Normal / Hover: Set different color and background color for the state of new item button.
Text Color: Select the color of the new item button’s text for both Normal and Hover states.
Background color: Select the new item button's background color for both Normal and Hover states.
Typography: Change the default typography options for the text of new item button.
Margin: Set the Margin of the new item button in PX or %.
Padding: Set the Padding of the new item button in PX or %.
Border Type: Select the type of border to use around the new item button.
Radius: Set the border radius to control corner roundness.
Shadow: Set options to apply a box shadow on the new item button.
Alignment: Align the button to the left, center, right, or justified.
Style of Caption
Margin: Set the Margin of the Caption in PX or %.
Padding: Set the Padding of the Caption in PX or %.
Background Type: Select the background color. You may use a solid or gradient color.
Border Type: Select the type of border, choosing from none, solid, double, dotted, dashed, or grooved.
Radius: Set the border radius to control corner roundness.
Shadow: Adjust box shadow options.
Title: Set the styles of the Title on Caption,
Typography: Set the typography options for the title text.
Color: Choose the color of the title text.
Icon: Set the styles of the right icon buttons (Layout Switch Icons and expand/Collapse icons)
Color: Choose the color of the Icon.
Active Color: Choose the color of the active icon button.
Size: Set the size of the Icon.
Advanced Settings
Set the Advanced options that are applicable to this control.