Difference between revisions of "Subforms"

From AgileApps Support Wiki
imported>Aeric
 
(77 intermediate revisions by 2 users not shown)
Line 2: Line 2:
'''[[File:GearIcon.png]] > Objects > {object} > Forms > {form} > {subform section}'''
'''[[File:GearIcon.png]] > Objects > {object} > Forms > {form} > {subform section}'''


__TOC__
__TOC__</noinclude>
</noinclude>
====About Subforms====
===About Subforms===
Subforms give users a way to view, modify, and add related records. Subforms can be used in both [[Forms]] that run in the platform, and in [[Web Forms]] that run externally.
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.
 
For example, a subform might be used for:
:*Line items in an Order form
:*Expense line items in an Expense Report object
:*A list of available inventory items


In a [[Form]] that is displayed the platform, a subform does all of the above, plus:
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.  
:* A subform displays a grid of fields for a ''related object'' (an object that has a [[Lookup]] to the current object).
:* Those records can be modified by modifying fields in the grid.
:* Existing records that have a [[Lookup]] to the current record are automatically displayed.
:* Those records can be modified and sorted.
:* Column totals can be displayed for number and currency fields.
:* New related records are added by providing data for empty rows in the grid.  


For example, a subform might present this kind of information in a record:
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 Web Form that runs externally, everything operates the same, with the exception that existing records cannot be displayed, and there are no column totals.)
:*Line items in an order
:*Expense line items in an Expense Report object
:*List of available inventory items


;Considerations:
;Considerations:
:* The owner of the main record becomes the owner of the related records created by the subform.
:* 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.
:* Formula fields, Image fields, and File fields cannot be included in the subform.
:: {{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 totaling is performed on records that are added, changed, or deleted within the Sub Form section. If record is/are added outside of subform, column totaling won't come accurate
:* 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.)
:* For that reason, an Object used in subform should not be displayed in a Tab.
 
:: {{TBD|Is that the only reason??}}
:* Subforms are not supported in the mobile interface.<br>(If form contains a subform section, that section does not appear when the form is displayed on a mobile device.)
:* Subforms are supported for [[Custom Objects]] and for the [[Case Object]]. They are not supported for most other supporting [[System Objects]].
:* 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]].
 
{{Tip|Once an object is chosen for use in a subform, got to the [[Tab Preferences]] page and remove it from all roles. Then it will not be available for use as an Application Tab.}}
 
:* Subform within a subform is not supported.
 
:* The list of subform records inside the record view of the Parent object is visible only when the ‘Record View Action’ in the Custom Access Criteria is true.
{{Note| To view the subforms through the Parent Object record, the applicable Custom Access Criteria will be Record View Action and not List View Action.}}


===Using Subforms===
====Using Subforms====
To add a record to a subform:
'''To add a record to a subform:'''
# At the top right of the subform section, click '''[Add Record]'''.<br>A New Record dialog appears.
# If record details are not already displayed, click '''- View Details -'''.
#: {{TBD|What form is used for that dialog?}}
# If the subform tab is not currently selected, click the tab that contains it.
# At the top right of the subform section, click '''[Add Record]'''.<br>A dialog appears, displaying a data-entry [[Form]] for that object.
# Fill in values for the record.
# Fill in values for the record.
# In the dialog, click '''[Save]'''.
# In the dialog, click '''[Save]'''.


To edit existing records displayed in a subform:
'''To edit an existing record displayed in a subform:'''
# Click on the subform record.<br>The edit dialog opens.
# If record details are not already displayed, click '''- View Details -'''.
# If the subform tab is not currently selected, click the tab that contains it.
# In that tab, click on a subform record.<br>The edit dialog opens.
# Make your changes.
# Make your changes.
# In the dialog, click '''[Save]'''.
# In the dialog, click '''[Save]'''.


To delete a subform record:
'''To delete subform records:'''
# Select the check box next to records to be deleted.
# If record details are not already displayed, click '''- View Details -'''.
# In the main record window, click '''[Save]'''.<br>The records are deleted, and any other changes made in the main form are saved.
# If the subform tab is not currently selected, click the tab that contains it.
# Next to the record(s) to be deleted, click the check box under the trash can icon.
# Click '''[Save Changes]'''.<br>The records are deleted, and any other changes made in the form are saved.


====To Add or Edit a Subform====
====Working with Subforms====
To add or edit a subform:
#Go to '''[[File:GearIcon.png]] > Objects > {object} > Forms > {form}'''
#Go to '''[[File:GearIcon.png]] > Objects > {object} > Forms > {form}'''
#:a. To create a new subform:
#:a. To create a new subform:
Line 50: Line 68:
#:: In the subform section heading, click the Edit icon.
#:: In the subform section heading, click the Edit icon.
#Fill in the subform settings:
#Fill in the subform settings:
#*'''Title -''' The text to display in the GUI.
#:
#*'''Section Type -''' Pre-populated (do not change)
#* '''Basic Information'''
#*'''Object Name -''' The Object records to display in the Subform
#:*'''Title -''' The text to display in the GUI.
#*'''Linking Field -''' Select the field that does a [[Lookup]] to the current object. (A list is presented, in case there is more than one.)
#:*'''Section Type -''' Pre-populated (do not change)
#*'''Number of Rows -''' Specify the number of rows to display in the Subform
#:*'''Object Name -''' The Object records to display in the Subform
#::* This is the minimum number of number of rows to display.  
#:*'''Linking Field -''' Select the field that does a [[Lookup]] to the current object. (A list is presented, in case there is more than one.)
#::* It defaults to 5 rows. You can specify any value up to 100 rows.
#:*'''Number of Rows -''' Specify the number of rows to display in the Subform
#::* If data exists, then all available data is shown, plus an additional 3 empty rows.
#:::* This is the minimum number of number of rows to display.  
#*'''Layout -''' This field is present for a form that is displayed in the platform. It is not present for a [[Web Form]].
#:::* It defaults to 5 rows. You can specify any value up to 100 rows.
#:Use the [[Arrow Button]]s to move fields to the list of Selected Fields list, and to specify their order.<br>The selected fields are displayed in the Subform when the form is displayed.
#:::* If data exists, then all available data is shown, plus an additional 3 empty rows.
#* Click '''[Next]'''
#:
#*'''Layout'''  
#: This section is present for a form that is displayed in the platform. It is not present for a [[Web Form]].
#:* ''' Subform Position-'''
#:*: Choose to embed the subform at the bottom  of the previous form section, or have it appear as a tab-section in the form.
#:* ''' Form for New Records-''' Choose the related object form to be displayed in the popup that appears when the user clicks the button to add a new record. The form assignment is applicable only for the normal forms. For a subform, the form that you select in the '''Form for New Records''' field, overwrites the selections made in the Forms Assignment page.
#:* ''' Fields to Display in Subform-'''
#::* Choose the fields to display in the table of related records displayed in the subform.
#::* Use the [[Arrow Button]]s to move fields to the list of Selected Fields and to specify their order.<br>The selected fields are displayed in the Subform when the form is displayed.
# Click '''[Next]'''.<br>The second page of the subform definition appears.
# Specify the '''Sorting and Totaling options'''.
#:;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.<br>(Only numeric and currency fields are listed.)
#Click '''[Save]'''
 
{{DeveloperNote|<br>Column Total fields are added to the original object (the object the subform is defined on). The field names have the form <tt>grid_comptn_123456...</tt>, where the number at the end is the ID of the object field.}}
 
====Dynamic Sorting in Subforms====
 
AgileApps new user interface now supports dynamic sorting in Subforms. This functionality provides you with a means of header based sorting on table column headers.
 
:* You can sort the records by clicking on the column header.
::[[File:Dynamic sort 7.png|1024px]]
:* Sorting order is indicated by the sorting icon against the column header.
::[[File:Dynamic sort 2.png|1024px]]
:* Default sorting is as per the configuration in settings. Dynamic sorting functionality does not have any impact on the original sorting implementation.
::[[File:Dynamic sort 6.png|1024px]]
{{Note|Sort cycles through ascending and descending.}}
{{Note|Subform sorting takes place at user interface level, you may experience a few differences when compared against API driven sorting. Sorting is case insensitive.}}


====Sorting Rows, Totaling Columns ====
====Subform record operations ====


The second page of the subform definition lets you specify sorting and totaling options:
In the new user interface, Edit and Delete options are available under Actions column of the subform section in the main record. Click  [[Image:Faq horizontal dots.png]] to see View details and Delete options. View details has two options, Read and Update. These options are usable only if the user has the required access to the object used in the subform.
#;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.<br>(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)
#Click '''[Save]'''


====Column-Total Adjustments====
[[File:Subforms NewUI.png]]
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.<br> (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:
<noinclude>
:[[File:GridInForm.png|border]]


{{DeveloperNote|<br>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 <tt>grid_{name}_123456...</tt>, 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]].}}
[[Category:Design]]
</noinclude>

Latest revision as of 05:18, 14 July 2022

GearIcon.png > Objects > {object} > Forms > {form} > {subform section}

About Subforms

Subforms give users a way to view, modify, and add related records. Subforms can be used in both Forms that run in the platform, and in Web Forms that run externally.

For example, a subform might be used for:

  • Line items in an Order form
  • Expense line items in an Expense Report object
  • A list of available inventory items

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

  • A subform displays a grid of fields for a related object (an object that has a Lookup to the current object).
  • Existing records that have a Lookup to the current record are automatically displayed.
  • Those records can be modified and sorted.
  • Column totals can be displayed for number and currency fields.
  • 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 Web Form that runs externally, everything operates the same, with the exception that existing records cannot be displayed, and there are no column totals.)

Considerations
  • The owner of the main record becomes the owner of the related records created by the subform.
  • Formula fields, Image fields, and File fields cannot be included in 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.)
  • Subforms are not supported in the mobile interface.
    (If form contains a subform section, that section does not appear when the form is displayed on a mobile device.)
  • 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.

Thumbsup.gif

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

  • Subform within a subform is not supported.
  • The list of subform records inside the record view of the Parent object is visible only when the ‘Record View Action’ in the Custom Access Criteria is true.

Notepad.png

Note: To view the subforms through the Parent Object record, the applicable Custom Access Criteria will be Record View Action and not List View Action.

Using Subforms

To add a record to a subform:

  1. If record details are not already displayed, click - View Details -.
  2. If the subform tab is not currently selected, click the tab that contains it.
  3. At the top right of the subform section, click [Add Record].
    A dialog appears, displaying a data-entry Form for that object.
  4. Fill in values for the record.
  5. 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, click the tab that contains it.
  3. In that tab, click on a subform record.
    The edit dialog opens.
  4. Make your changes.
  5. In the dialog, click [Save].

To delete subform records:

  1. If record details are not already displayed, click - View Details -.
  2. If the subform tab is not currently selected, click the tab that contains it.
  3. Next to the record(s) to be deleted, click the check box under the trash can icon.
  4. 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 GearIcon.png > 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:
    • Basic Information
    • 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 section is present for a form that is displayed in the platform. It is not present for a Web Form.
    • Subform Position-
      Choose to embed the subform at the bottom of the previous form section, or have it appear as a tab-section in the form.
    • Form for New Records- Choose the related object form to be displayed in the popup that appears when the user clicks the button to add a new record. The form assignment is applicable only for the normal forms. For a subform, the form that you select in the Form for New Records field, overwrites the selections made in the Forms Assignment page.
    • Fields to Display in Subform-
    • Choose the fields to display in the table of related records displayed in the subform.
    • 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 the Sorting and Totaling options.
    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]

Notepad.png

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.

Dynamic Sorting in Subforms

AgileApps new user interface now supports dynamic sorting in Subforms. This functionality provides you with a means of header based sorting on table column headers.

  • You can sort the records by clicking on the column header.
Dynamic sort 7.png
  • Sorting order is indicated by the sorting icon against the column header.
Dynamic sort 2.png
  • Default sorting is as per the configuration in settings. Dynamic sorting functionality does not have any impact on the original sorting implementation.
Dynamic sort 6.png

Notepad.png

Note: Sort cycles through ascending and descending.

Notepad.png

Note: Subform sorting takes place at user interface level, you may experience a few differences when compared against API driven sorting. Sorting is case insensitive.

Subform record operations

In the new user interface, Edit and Delete options are available under Actions column of the subform section in the main record. Click Faq horizontal dots.png to see View details and Delete options. View details has two options, Read and Update. These options are usable only if the user has the required access to the object used in the subform.

Subforms NewUI.png