Subforms

> Objects > {object} > Forms > {form} > {subform section}

About Subforms

In a Web Form, a subform displays a grid of fields for a related object (an object that has a Lookup to the current object). New related records are added by providing data for empty rows in the grid. When the platform processes the data in the subform, the new related records are created. The Lookup field in those records (also known as the Linking field) is automatically populated.

In a Form that is displayed the platform, a subform does all of the above, plus:

• The subform grid displays any existing records that have a Lookup to the current record.
• Those records can be modified or deleted.
• Column totals can be displayed for number and currency fields.

For example, a subform might present this kind of information in a record:

• Line items in an order
• Expense line items in an Expense Report object
• List of available inventory items

Considerations

• The owner of the main record becomes the owner of the related records created by the subform.

• The Linking Field (the Lookup field defined in the subform object) should not be selected for inclusion the list of subform fields. (That field is included automatically when the subform is displayed. It should not be present in the subform, so that it cannot be changed accidentally.)

__TBD: Is that the reason? Is it the only reason?__

• Subforms are not supported in the mobile interface.
  (A single-record subform section will appear on the mobile device, if one is defined. So it is necessary to ensure that any form which contains a subform is not available for mobile use.)
• Subforms are supported for objects you create, and for the Cases Object. They are not available for most other (mostly hidden) supporting System Objects. (In particular, they are not available for the Tasks object.)
• Column total calculations are performed on records that are added, changed, or deleted within the subform section. If a record is added outside of the subform, column totals will not be accurate.
• For that reason, an Object used in a subform should not be displayed in an Application Tab.

__TBD: Are there other reasons??__

Tip: Once an object is chosen for use in a subform, got to the Tab Preferences page and remove it from all roles. That will make it unavailable for use as an Application Tab.

Using Subforms

To add a record to a subform:

1. At the top right of the subform section, click [Add Record].
   A New Record dialog appears, displaying the fields specified for the subform.

   Note:
   In the main object window, it is also possible to click [New {objectName} Record].

2. Fill in values for the record.
3. In the dialog, click [Save].

To edit an existing record displayed in a subform:

1. If record details are not already displayed, click - View Details -.
2. If the subform tab is not currently selected, select it.
3. In that tab, click on a subform record.
   The edit dialog opens.
4. Make your changes.
5. In the dialog, click [Save].

Important: If you click a related record in the main record view, an Application Tab opens to display the selected record. You generally do not want to make changes in that tab, because such changes are not reflected in column totals. To get back to the original record from that tab: Click - View Details - in the Related record. Find the Lookup field that identifies the original record. Click the link in that field. You are now back to the record you were on originally.

To delete subform records:

1. Next to the record(s) to be deleted, click the check box under the trash can icon.
2. Click [Save Changes].
   The records are deleted, and any other changes made in the form are saved.

Working with Subforms

To add or edit a subform:

1. Go to > Objects > {object} > Forms > {form}

   a. To create a new subform:

   In the Elements sidebar, click New Subform.

   b. To edit an existing subform:

   In the subform section heading, click the Edit icon.

2. Fill in the subform settings:
   • Title - The text to display in the GUI.
   • Section Type - Pre-populated (do not change)
   • Object Name - The Object records to display in the Subform
   • Linking Field - Select the field that does a Lookup to the current object. (A list is presented, in case there is more than one.)
   • Number of Rows - Specify the number of rows to display in the Subform

   • This is the minimum number of number of rows to display.
   • It defaults to 5 rows. You can specify any value up to 100 rows.
   • If data exists, then all available data is shown, plus an additional 3 empty rows.

   • Layout - This field is present for a form that is displayed in the platform. It is not present for a Web Form.

   • Use the Arrow Buttons to move fields to the list of Selected Fields and to specify their order.
     The selected fields are displayed in the Subform when the form is displayed.

3. Click [Next].
   The second page of the subform definition appears.
4. Specify sorting and totaling options.

   Note:
   These options take effect in the Record Details section of the main record, in the tab that displays the related records.

   Sort Settings

   Choose the column to sort on, and specify an ascending or descending sort.

   Column Totals

   Select the numeric and currency fields that will be automatically totaled.
   (Only numeric and currency fields are listed.)

5. Click [Save]

Note for Developers: Column Total fields are added to the original object (the object the subform is defined on). The field names have the form grid_comptn_123456..., where the number at the end is the ID of the object field.