Subform form control

A form control that holds a group of form controls. Optionally, groups of form controls can be added or deleted by a runtime app user. This is referred to as a repeating subform.

Note: This form control improves the performance — especially form rendering time — and runtime app user experience for subforms. This version of the Subform control is recommended for all new eForms. The legacy Subform form control still exists for backward compatibility. For more information, refer to Subform (Legacy) form control.

Configure the Subform form control

To configure the Subform Subform V8 icon control, do the procedure in this topic.

Video: Common Configuration Settings in eForm Controls

Prerequisites

Examples

How to Start

  1. Open eForm Builder.

    For information about how to open this screen, refer to eForm Builder screen.


    Eform Builder screen
  2. On the eForm Builder screen, in the Tool Box, open the Commmon Controls tab.

    Common Controls tab
  3. On the Common Controls tab, drag a Subform Subform V8 icon form control onto your eForm.

    Subform Form Control

Procedure

  1. Complete the settings on the configuration screens.

    You can use the Data screen screen to specify a variable.

General

Specifies the basic configuration for the Subform form control.

Figure: General tab

General tab

Fields

Field NameDefinition

Label
Function:
Specifies the text label that shows on your form for the control.
Accepted Values:
One line of text that can have spaces.
Default Value:
Different for different controls.
Example:
This is a common configuration field that is used in many examples. Refer to:
  • Examples - Step-by-step use case examples, information about what types of examples are provided in the AgilePoint NX Product Documentation, and other resources where you can find more examples.

Internal Name
Function:
Specifies a unique, technical name for your control.
Accepted Values:
One line of text (a string) with no spaces.
Default Value:
Different for different controls.
Example:
This is a common configuration field that is used in many examples. Refer to:
  • Examples - Step-by-step use case examples, information about what types of examples are provided in the AgilePoint NX Product Documentation, and other resources where you can find more examples.

Configure

Configures advanced settings for your form control.

Figure: Configure tab

Configure tab

Fields

Field NameDefinition

Minimum Occurrence Message
Function:
Specifies the message to show if the participant does not enter the minimum number of items.
Accepted Values:
More than one line of text that can have letters, numbers, spaces, and special characters.
Default Value:
Please supply at least ${MIN} entries

{MIN} is a process data variable that shows the minimum number of occurrences for your form control.

Show Label
Function:
Specifies if the form panel shows a label at the top.
Accepted Values:
  • Deselected - Shows no label at the top.
  • Selected - Shows label at the top.
Default Value:
Selected
Example:
Refer to:

Display Style
Function:
Specifies if the form control shows the values in rows or columns.
Accepted Values:
  • Rows - Shows the form controls of the subform as columns in rows.
  • Columns - Shows the form controls of the subform as columns.
  • Summary Columns - Shows a summary of the form controls in the subform as columns. You can not use summary columns in a child subform within a group of nested subforms.
Default Value:
Rows
Example:
Refer to:

Expandable
Function:
Specifies if the process participant can expand the form control values.
To Open this Field:
  1. In the Display Style field, select Rows.
Accepted Values:
  • Deselected - The participant can not expand the form control values.
  • Selected - The participant can expand the form control values.
Default Value:
Deselected

Expand By Default
Function:
Specifies if the form control values are expanded by default.
To Open this Field:
  1. Select Expandable.
Accepted Values:
  • Deselected - The form control values are expanded by default.
  • Selected - The form control values are expanded by default.
Default Value:
Selected

Choose Summary Fields
Function:
Specifies the form controls to include and make it editable in the summary column in the subform.
To Open this Field:
In the Display Style field, select Summary Columns.

Choose Fields To Exclude In Column Layout
Function:
Specifies the form controls to hide in the subform.
To Open this Field:
In the Display Style field, select Columns.

List Options
Function:
Specifies the data source to get the options in the list.
Accepted Values:
  • None
  • Inline List - Completes the list with the values specified in the form control.
  • Lookup List - Completes the list with the values from an external data source.
Default Value:
None
Example:
Refer to:

Name
Function:
Specifies the name of the option shown in the drop-down list.
To Open this Field:
  1. In the List Options field, select Inline List.
Accepted Values:
One line of text that can have spaces.
Default Value:
Option 1

Value
Function:
Specifies the value of the name option that shows in the list.
To Open this Field:
  1. In the List Options field, select Inline List.
Accepted Values:
One line of text that can have spaces.
Default Value:
Option 1

Delete Delete icon

Function:
Deletes the selected row.
To Open this Field:
  1. In the List Type field, select Inline List.

Add Option

Function:
Adds more rows.

You can drag the rows to change the order.

To Open this Field:
  1. In the List Type field, select Inline List.

Lookup Source
Function:
Specifies a reusable lookup configuration. The lookup configuration includes the data source and other configuration values for the lookup.
To Open this Field:
  1. In the List Options field, select Lookup List.
Accepted Values:
A valid lookup source
Default Value:
None

Add Lookup Add Lookup icon
Function:
Opens the screen to configure a lookup.

There is more than one path to configure a lookup. Make sure you use the document that shows the path for your lookup.

To Open this Field:
  1. In the List Type field, select Lookup List.
Example:
Refer to:

Allow Add
Function:
Specifies whether the form user can add new records.
Accepted Values:
  • Selected - Lets the form user add new records.
  • Deselected - Does not let the form user add new records.
Default Value:
Selected
Example:
Refer to:

Allow Delete
Function:
Specifies whether the form user can delete records.
Accepted Values:
  • Selected - Lets the form user delete records.
  • Deselected - Does not let the form user delete records.
Default Value:
Selected
Example:
Refer to:

Allow Copy
Function:
Specifies if the runtime app user can copy records.
Accepted Values:
  • Selected - Lets the runtime app user copy records.
  • Deselected - Records can not be copied on the eForm.
Default Value:
Selected
Example:
Refer to:

Confirm Deletion
Function:
Specifies if the form user must confirm before they delete the record.
Accepted Values:
  • Selected - The form user must confirm before they delete the record.
  • Deselected - The form user does not confirm before they delete the record.
Default Value:
Selected
Example:
Refer to:

Allow Expand All
Function:
Specifies whether the runtime app user can expand the records on the subform.
To Open this Field:
  1. Select Expandable.
Accepted Values:
  • Selected - The runtime app user can expand the records.
  • Deselected - The list of records is fixed on the eForm.
Default Value:
Deselected

Allow Collapse All
Function:
Specifies whether the runtime app user can collapse the records on the subform.
To Open this Field:
  1. Select Expandable.
Accepted Values:
  • Selected - The runtime app user can collapse the records.
  • Deselected - The list of records is fixed on the eForm.
Default Value:
Deselected

Show Row Number
Function:
Specifies whether the row numbers show on the subform.
Accepted Values:
  • Selected - The row numbers show.
  • Deselected - The row numbers do not show.
Default Value:
Deselected

Read-Only History
Function:
Specifies whether the runtime app user can change the records after the task is submitted.
Accepted Values:
  • Selected - The records are read-only after the task is submitted.
  • Deselected - The runtime app user can change the records after the task is submitted.
Default Value:
Deselected

Minimum Occurrences
Function:
Specifies the minimum number of times a record shows on a subform.
Accepted Values:
An integer up to 999.
Default Value:
1

Maximum Occurrences
Function:
Specifies the maximum number of times a record shows on a subform.
Accepted Values:
An integer up to 9999999.
Default Value:
5
Example:
Refer to:

Default Occurrences
Function:
Specifies if the default number of times a record shows on the subform.
Accepted Values:
An integer up to 999.
Default Value:
1

Page Results
Function:
Specifies if the results show on more than one page.
Accepted Values:
  • Yes - The results show on more than one page.
  • No - All results show on one page.
Default Value:
No

Number Of Records Per Page
Function:
Specifies the number of records per page.
To Open this Field:
  1. In the Page Results field, select Yes.
Accepted Values:
An integer.
Default Value:
5

Show Action Buttons As Image
Function:
Specifies if the action buttons use images or text labels.
Accepted Values:
  • Selected - The action buttons use images.
  • Deselected - The action buttons use text labels.
Default Value:
Selected

Add Button Text
Function:
Specifies the text to show on the Add button.
To Open this Field:
  1. Deselect Show Action Buttons As Image field.
Accepted Values:
One line of text (a string).
Default Value:
Add Record

Expand All Button Text
Function:
Specifies the text label to show on the Expand All button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Accepted Values:
One line of text that can have spaces.
Default Value:
Expand All

Collapse All Button Text
Function:
Specifies the text label to show on the Collapse All button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Accepted Values:
One line of text that can have spaces.
Default Value:
Collapse All

Copy Button Text
Function:
Specifies the text to show on the Copy button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Accepted Values:
One line of text (a string).
Default Value:
Copy Record

Delete Button Text
Function:
Specifies the text to show on the Delete button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Accepted Values:
One line of text that can have spaces.
Default Value:
Delete Record

Mobile Display Style
Function:
Specifies if the subform shows one form controls per row on a mobile device. Showing form controls in rows saves space on a small screen.
Accepted Values:
  • Inherit - Shows the form controls on the subform in the format you specify.
  • Rows - Shows one form control per row on the subform.
Default Value:
Inherit

Appearance

Specifies the look and feel for your form control.

Figure: Appearance tab

Appearance tab

Fields

Field NameDefinition

Font Family
Function:
Specifies the font family of the input text and label.
Accepted Values:
A font name from the list.
Default Value:
None
Example:
Refer to:

Font Size (px)
Function:
Specifies the size of the input text and label for your form control.
Accepted Values:
A positive integer.
Default Value:
None
Example:
Refer to:

Font Style
Function:
Specifies the style of the font for the input text and label.
Accepted Values:
  • Bold - Shows the input text and label in bold.
  • Underline - Shows the label underlined.
  • Italic - Shows the label in italic.
Default Value:
None
Example:
Refer to:

Foreground Color
Function:
Specifies the foreground color for your control.
Accepted Values:
A color value using a hex code, RGB code, or RGBA code.

You can enter a color code, or select a color from the palette.

Default Value:
#ff0000
Example:
Refer to:

Row Background Color
Function:
Specifies the background color for a row in your control.
To Open this Field:
  1. In the Display Style list, select Rows or Columns.
Accepted Values:
A color value using a hex code, RGB code, or RGBA code.

You can enter a color code, or select a color from the palette.

Default Value:
#ff0000

Alternate Row Background Color
Function:
Specifies the alternative background color for row in your control.
To Open this Field:
  1. In the Display Style list, select Rows or Columns.
Accepted Values:
A color value using a hex code, RGB code, or RGBA code.

You can enter a color code, or select a color from the palette.

Default Value:
#ff0000

Container CSS Class
Function:
Specifies a CSS class for the container of your control.
Accepted Values:
A valid CSS class.
Default Value:
None

If you specify your CSS CSS icon on the top menu, the CSS is populated.

Example:
Refer to:

Behavior

Specifies how the control shows on your form.

Figure: Behavior tab

Behavior tab

Fields

Field NameDefinition

Enable
Function:
Specifies if the form user can change the value of a field.
Accepted Values:
  • Selected - The form user can change the value.
  • Deselected - The form user cannot change the value.
Default Value:
Selected
Example:
Refer to:

Visible
Function:
Specifies if the form user sees the field.
Accepted Values:
  • Selected - The form user sees the field.
  • Deselected - The form user does not see the field.
Default Value:
Selected
Example:
Refer to:

Advanced

Specifies advanced settings for your form control.

Figure: Advanced tab

Advanced tab

Fields

Field NameDefinition

Field ID
Function:
Shows an ID of the control.
Accepted Values:
Read only.
Default Value:
Different for different controls.
Example:
Refer to:

Maximum Height (px)
Function:
Specifies the maximum height for your control in pixels.
Accepted Values:
An integer less than 10000.
Default Value:
400

Sub Total
Function:
Shows the total number of rows.

This is not available for nested subforms.

Auto-Lookups To Exclude On Form Load Or Edit
Function:
Specifies the form controls to exclude from a lookup in the subform when the eForm loads in the browser, or the user changes the value in the form control.

Excluding Auto-Lookups is recommended in these conditions:

  • You do not want to overwrite user input when a form loads in the browser.
  • Under some conditions, such as Summary View, form controls open for editing in a pop-up screen. A user may input data in a form control, and then the control opens again in a pop-up, such as in Summary View. In this case, you may not want to execute the Auto-Lookup again because it will overwrite the user's input.

    There are some exceptions to this recommendation. For more information, refer to Limitations.

Limitations:
Excluding Auto-Lookups is not recommended for lists or other form controls whose options populate using an Auto-Lookup. If you exclude the Auto-Lookup, the values do not populate. That includes a value the user has selected. This limitation applies on both form load and form control edit events.

This is an exception to the recommended case where the form control opens for editing in a pop-up screen.

To Open this Field:
On the Configure tab, in the Display Style field, select Summary Columns.

Allow Import From Excel or CSV
Function:
Specifies whether to show the Import option on the subform so the runtime app user can import data from a Microsoft Excel or CSV file.
Accepted Values:
  • Selected - Shows the Import button on the subform, and runtime app users can import data.
  • Deselected - Hides the Import option on the subform, and runtime app users can not import data.
Default Value:
Deselected
Example:
Refer to:
Limitations:

This field is available in these releases:

Export As CSV
Function:
Specifies to export the subform data in .csv format. For a nested subform, it may not be possible to give correctly formatted values.
Accepted Values:
  • Selected - The subform data is exported in .csv format.
  • Deselected - The subform data is not exported in .csv format.
Default Value:
Deselected

Filter Columns To Export
Function:
Specifies whether the Columns To Export screen lets the runtime app user select columns to include or exclude when they export the data from the subform in .csv format.
To Open this Field:
  1. In the Advanced tab, select Export As CSV.
Accepted Values:
  • Selected - Shows the Columns To Export screen to select the columns when the runtime app user exports the data from the subform.
  • Deselected - Exports the data in .csv format from all columns in the subform, and does not show the Columns To Export screen.
Default Value:
Deselected
Limitations:

This field is available in these releases:

Data Security Settings
Function:
Specifies whether to store information from the field in the process schema, so the app can use it again, or to simply pass on the information after the form is submitted without storing the information. This option helps to protect sensitive user information.
Accepted Values:
  • Persist - Stores the data from the field in the process schema, so the app can use it again.
  • Do Not Persist - Does not store the data from the field in the process schema. This option provides greater security for sensitive user information.
Default Value:
Persist
Example:
Refer to:

Show On Tablet Devices
Function:
Specifies if the form field shows on a tablet.
Accepted Values:
  • Selected - The form field shows on a tablet.
  • Deselected - The form field does not show on a tablet.
Default Value:
Selected
Example:
Refer to:

Show On Mobile Phone Devices
Function:
Specifies if the form field shows on a mobile device.
Accepted Values:
  • Selected - The form field shows on a mobile device.
  • Deselected - The form field does not show on a mobile device.
Default Value:
Selected
Example:
Refer to: