Subform (child table)

Embed forms for adding zero or more rows to a different table. When dynamic is false (default), the number of rows is determined by the numRows formula. When dynamic is true, the user can add and remove rows, with numRows providing the minimum.

Ingredient Family: formIngredients

Outline Display: A subform for a related table connected to {{childTable}}.
{{dynamic:The user can add and remove rows, with at least {{numRows}} shown.}}{{!dynamic:It shows exactly {{numRows}} rows.}}
The column in the child that references the parent is {{childTableParentRef}}.
We sort the rows by {{childTableSortColumn}}.
{{shouldShow:Only shown when {{shouldShow}}.}}
Using {{counter}} as a counter, we will label each row {{rowLabel}}.
The subform is defined by:{{childForm}}
We can reference these rows from a setter button as {{setField}}.
{{getField:We can read these rows back as a list via {{getField}}.
}}{{summaryFields:Summarizations: {{summaryFields}}}}

Details

When dynamic is false (the default), numRows controls the exact number of child rows shown. When dynamic is true, numRows is the minimum and the user can freely add and remove rows beyond that minimum. Within the child form, references to parent form fields must be prefixed with parent_ (e.g., a parent field Employee becomes parent_Employee in the child). The setField knob provides a JSON-encoded string interface for programmatic row population. The getField knob exposes child rows as a typed list for use in subsequent parent form elements or summarizations.

Local scope

The parent slot binds these (look up the slot in the parent to see how):

• $parentTable – The table (if any) that this form is based on
• $formFieldsTable – A table of form fields that is built up through the sequence of form ingredients

Names introduced within this component’s knobs:

• parentTable – repeat of $parentTable
• childTable – table chosen from the app’s schema (via childTable knob)
• $formFieldsTable – renamed copy of $formFieldsTable
• $parentTable – repeat of childTable

Settings

Required

• childTable : table
  The table which we would like the form to be able to add rows to

• numRows : formula (returns integer; required, non-nullable)
  The number of rows. When dynamic is false, this formula determines the exact number of rows shown. When dynamic is true, this is the minimum number of rows; the user can add and remove rows beyond this minimum.
  Scope: all columns of $formFieldsTable (reference as [ColumnName], e.g., [Name], [Price])

• childTableParentRef : column of childTable (type filter: any type (must be required))
  The column in the child that references the parent

• childTableSortColumn : column of childTable (type filter: any type)
  The column on which to sort the child table rows

• counter : new column (type: integer; required, non-nullable)
  A name for a “counter” variable to represent which row of the other table we’re looking at. (Counter is a pretty good name unless it has already been used.)

• rowLabel : formula (returns text; required, non-nullable)
  How to label each foreign row form. (Using the previously defined counter field is a good idea if the rows should be ordered.)
  Scope: all columns of $formFieldsTable (reference as [ColumnName], e.g., [Name], [Price])

• setField : new column (type: text; required, non-nullable)
  A required name for a new field that allows one to set these rows via a json-encoded string of rows of this child table

• getField : new column (type: list of childTable’s full row type)
  A required name for a new field that allows one to get these rows as a list of rows of this child table

Optional

• shouldShow : formula (returns bool; required, non-nullable)
  Should we show this embedded form? If the formula yields True, it is shown and used. Otherwise, it is as if the user left the embedded forms blank.
  Scope: all columns of $formFieldsTable (reference as [ColumnName], e.g., [Name], [Price])

• childForm : ingredient slot of formIngredients($parentTable, $formFieldsTable) (many)
  Descriptions for widgets or other ways of asking the user for information to construct a row in the other table. Note that the order of the ingredients will be reflected in the order of the form and that there must be an ingredient to produce each column in the other table except for the columns: [childTableParentRef]. Key columns should use SequentialID. Within this child table, all references to form fields from the parent form should be prefixed with parent_. For instance, if there was a field Employee, then within the child form, it should be referenced as parent_Employee.

• dynamic : constant value (type: bool; required, non-nullable)
  Whether the user can dynamically add and remove rows. When false (default), the number of rows is controlled by numRows. When true, numRows is the minimum number of rows and the user can add or remove rows.

• summaryFields : ingredient slot of summarizationIngredients($formFieldsTable, childTable) (many)
  Summarizations of the child table rows that can be accessed by subsequent form elements.