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 subform data, the new records are created, and the Lookup 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 by modifying fields in the grid.

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 should not be present in Form layout which is being used for subform add/Edit record.

• Subforms are not supported in the mobile interface.

__TBD: The spec says "mobile client". But we have the /m browser interface, iirc. What happens when a form is displayed on such a device? Does it fail, or does the form "degrade" so that it works, but the subform section is missing?__

• 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??__

• 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.)

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.

   __TBD: What form is used for that dialog?__

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

To edit existing records displayed in a subform:

1. Click on the subform record.
   The edit dialog opens.
2. Make your changes.
3. In the dialog, click [Save].

To delete a subform record:

1. Select the check box next to records to be deleted.
2. In the main record window, click [Save].
   The records are deleted, and any other changes made in the main form are saved.

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 list, and to specify their order.
   The selected fields are displayed in the Subform when the form is displayed.

   • Click [Next]

Sorting Rows, Totaling Columns

The second page of the subform definition lets you specify sorting and totaling options:

1. Sort Settings

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

   Column Totals

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

   Column-Total Adjustments

   __TBD: The spec doesn't mention this. Was it overlooked or removed?__

   This section appears when you are totaling currency fields. (Only currency fields are listed.)

   • Select the currency field that will have additional adjustments applied to it, and specify the adjustments to allow for. (See below)

2. Click [Save]

Column-Total Adjustments

If you total one more currency fields, you can elect to apply adjustments to one of them:

• Surcharge - Adds a surcharge percentage field to the form.
• Discount - Adds a discount percentage field to the form, as well as a discount amount.
  (Either can entered. If an amount is entered, it is saved as a percentage.)
• Tax - Adds a tax percentage field to the form.
• Shipping - Adds a field for a shipping charge.

Each selection adds the appropriate fields to the form, and does the appropriate calculations to produce a net total:

File:GridInForm.png

Note for Developers: Fields for Column Totals, Column-Total Adjustments, and the Net Total are added to the original object (the object the subform is defined on). The field names have the form grid_{name}_123456..., where the name might be "discount", "net_total", or "comptn" (for a column total), and where the number at the end is the ID of the object Field.