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

General tab - Subform

Specifies the basic configuration for the Subform form control.

Figure: General tab

General tab

Fields

Field NameDefinition

Label
Description:
Specifies the text label that shows on your form for the control.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • 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
Description:
Specifies a unique, technical name for your control.
Allowed Values:
One line of text (a string).

Not Accepted:

  • 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 tab - Subform

Configures the settings that are specific to the Subform control.

Figure: Configure tab

Configure tab

Fields

Field NameDefinition

Minimum Occurrence Message
Description:
Specifies the message to show if the participant does not enter the minimum number of items.
Allowed Values:
More than one line of text.
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
Description:
Specifies if the form panel shows a label at the top.
Allowed Values:
  • Deselected - Shows no label at the top.
  • Selected - Shows label at the top.
Default Value:
Selected
Example:
Refer to:

Display Style
Description:
Specifies if the form control shows the values in rows or columns.
Allowed 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
Description:
Specifies if the process participant can expand the form control values.
To Open this Field:
  1. In the Display Style field, select Rows.
Allowed 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
Description:
Specifies if the form control values are expanded by default.
To Open this Field:
  1. Select Expandable.
Allowed 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
Description:
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
Description:
Specifies the form controls to hide in the subform.
To Open this Field:
In the Display Style field, select Columns.

List Options
Description:
Specifies the data source to get the options in the list.
Allowed 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
Description:
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.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • Spaces
Default Value:
Option 1

Value
Description:
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.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • 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
Description:
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.
Allowed 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
Description:
Specifies whether the form user can add new records.
Allowed 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
Description:
Specifies whether the form user can delete records.
Allowed 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
Description:
Specifies if the runtime app user can copy records.
Allowed 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
Description:
Specifies if the form user must confirm before they delete the record.
Allowed 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
Description:
Specifies whether the runtime app user can expand the records on the subform.
To Open this Field:
  1. Select Expandable.
Allowed 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
Description:
Specifies whether the runtime app user can collapse the records on the subform.
To Open this Field:
  1. Select Expandable.
Allowed 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
Description:
Specifies whether the row numbers show on the subform.
Allowed Values:
  • Selected - The row numbers show.
  • Deselected - The row numbers do not show.
Default Value:
Deselected

Read-Only History
Description:
Specifies whether the runtime app user can change the records after the task is submitted.
Allowed 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
Description:
Specifies the minimum number of times a record shows on a subform.
Allowed Values:
An integer.

Range

  • 1-999
Default Value:
1

Maximum Occurrences
Description:
Specifies the maximum number of times a record shows on a subform.
Allowed Values:
An integer.

Range

  • 1-9999999
Default Value:
5
Example:
Refer to:

Default Occurrences
Description:
Specifies if the default number of times a record shows on the subform.
Allowed Values:
An integer.

Range

  • 1-999
Default Value:
1

Page Results
Description:
Specifies if the results show on more than one page.
Allowed 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
Description:
Specifies the number of records per page.
To Open this Field:
  1. In the Page Results field, select Yes.
Allowed Values:
An integer.
Default Value:
5

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

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

Expand All Button Text
Description:
Specifies the text label to show on the Expand All button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • Spaces
Default Value:
Expand All

Collapse All Button Text
Description:
Specifies the text label to show on the Collapse All button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • Spaces
Default Value:
Collapse All

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

Delete Button Text
Description:
Specifies the text to show on the Delete button.
To Open this Field:
  1. Deselect Show Action Buttons As Image.
Allowed Values:
One line of text (a string).

Accepted:

  • Letters
  • Numbers
  • Spaces
Default Value:
Delete Record

Mobile Display Style
Description:
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.
Allowed 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 tab - Subform

Specifies the look and feel for the Subform control.

Figure: Appearance tab

Appearance tab

Fields

Field NameDefinition

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

Font Size (px)
Description:
Specifies the size of the input text and label for your form control.
Allowed Values:
An integer.

Range

  • Greater than 0
Default Value:
None
Example:
Refer to:

Font Style
Description:
Specifies the style of the font for the input text and label.
Allowed 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
Description:
Specifies the foreground color for your control.
Allowed 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
Description:
Specifies the background color for a row in your control.
To Open this Field:
  1. In the Display Style list, select Rows or Columns.
Allowed 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
Description:
Specifies the alternative background color for row in your control.
To Open this Field:
  1. In the Display Style list, select Rows or Columns.
Allowed 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
Description:
Specifies a CSS class for the container of your control.
Allowed 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 tab - Subform

Specifies how the Subform control shows on your form.

Figure: Behavior tab

Behavior tab

Fields

Field NameDefinition

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

Visible
Description:
Specifies if the runtime app user sees the field.
Allowed Values:
  • Selected - The runtime app user sees the field.
  • Deselected - The runtime app user does not see the field.
Default Value:
Selected
Example:
Refer to:

Advanced tab - Subform

Specifies the advanced settings for the Subform control.

Figure: Advanced tab

Advanced tab

Fields

Field NameDefinition

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

Maximum Height (px)
Description:
Specifies the maximum height for your control in pixels.
Allowed Values:
An integer.

Range

  • 1-9999
Default Value:
400

Sub Total
Description:
Shows the total number of rows.

This is not available for nested subforms.

Auto-Lookups To Exclude On Form Load Or Edit
Description:
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
Description:
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.
Allowed 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
Description:
Specifies to export the subform data in .csv format. For a nested subform, it may not be possible to give correctly formatted values.
Allowed 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
Description:
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.
Allowed 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
Description:
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.
Allowed 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
Description:
Specifies if the form field shows on a tablet.
Allowed 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
Description:
Specifies if the form field shows on a mobile device.
Allowed 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: