create_subform_interface

Create a new Subform Interface in a Formulize form.

Newly created elements appear on the pages of form screens where all other elements in the form already appear. To add a newly created element to a form screen page which only has some existing elements, use the update_form_screen tool.

Overview:

• Subform Interfaces are used to provide an interface in one form, that shows the entries in another form. They are designed to work with forms that are connected in a one to many relationship, such as Each Province has many Cities, or Each Budget has many Budget Line Items, etc.

Important notes:

• Subform Interfaces do not store user data. They are a collection of settings that control how the entries in the ‘many’ form are to be displayed and managed, when viewed from the ‘one’ form.
• Subform Interfaces are very powerful tools for supporting complex data management scenarios. They allow users to manage entire sets of data through one screen, instead of having to manage each individual entry separately.

Properties common to all Subform Interfaces:

• sourceForm (int, the form ID of the form to be displayed in this Subform Interface. If the source form is not already connected to this form, a new Linked Dropdown List will be created in the source form, and it will be linked to the Principal Identifer in this form. For example, if a Cities form is embedded in a Provinces form, and there is no existing connection between them, then a Linked Dropdown List will be added to the Cities form that links to the Province form’s principal identifier.)
• sortingElement (int, the element ID of an element in the source form to sort the entries by. If not specified, entries will be shown in creation order.)
• sortingDirection (string, either ‘ASC’ or ‘DESC’, indicating if the entries should be sorted in ascending or descending order. Default is ‘ASC’.)
• showAddButton (int, either 1 or 0, indicating if an Add Entry button should be shown to users, if they have permission to add entries in the source form. Default is 1. Set to 0 if this Subform Interface should never include an Add Entry button.)
• showDeleteButton (int, either 1 or 0, indicating if a Delete Entry button should be shown to users, if they have permission to delete entries in the source form. Default is 1. Set to 0 if this Subform Interface should never include a Delete Entry button.)

Subform Interface Type: Editable Row (subformEditableRow).

Description: This kind of Subform Interface allows users to view and edit the connected entries. Each connected entry shows up as a row of form elements, which can be edited in place. This is best for situations when only a few elements in the source form need to be edited at once (generally less than 5) and where users need to be able to edit multiple entries quickly, without necessarily having to open up each entry in a separate full form or modal popup.

Properties:

• all the common properties for Subform Interfaces, plus:
• elementsInRow (Required. An array of element ids, indicating which elements from the source form should be shown in each row.)
• disabledElementsInRow (Optional. An array of element ids, indicating which elements in the row should be disabled (not editable). Default is an empty array, meaning all elements in the row are editable.)
• entryViewingMode (Optional. A string, either ‘off’, ‘form_screen’ or ‘modal’. Default is ‘off’, which means there are no clickable icons for opening up each source form entry for viewing/editing. If ‘full_screen’ then there are clickable icons, and they will cause the page to reload with the correct Form Screen for showing the source form entry. If ‘modal’ then there are clickable icons, and they will open a modal popup box for showing the source form entry. For small forms, ‘modal’ is usually best. For large forms, ‘full_screen’ is usually best. If a user should not be able to view/edit the source form entries, or does not need to, then set this to ‘off’.

Examples:

• An ‘Editable Row’ Subform Interface that shows elements 52, 66 and 71 from connected entries in form 7. Sort the entries by the value of element 52. Do not show a Delete button. Open entries in a modal popup for viewing/editing: { sourceForm: 7, elementsInRow: [52, 66, 71], sortingElement: 52, showDeleteButton: 0, entryViewingMode: ‘modal’ }
• An ‘Editable Row’ Subform Interface that shows elements 52, 66 and 71 from connected entries in form 3. Open entries in the full form for viewing/editing. Disable elements 12 and 13 in the row: { sourceForm: 3, elementsInRow: [12, 13, 14, 15, 16, 17], disabledElementsInRow: [12, 13], entryViewingMode: ‘form_screen’ }

Subform Interface Type: Full Form (subformFullForm).

Description: This Subform Interface embeds a full version of the connected form, inside this form (ie: inside the form that the Subform Interface belongs to). The connected entries are shown as full forms, one after the other, inside the interface. They can be organized into collapsable accordions (generally the preferred option), or simply embedded right into the page (generally best for small forms, so as not to overwhelm the user). ‘Full Form’ Subform Interfaces are good for situations where users need to be able to edit the entire connected entry quickly, without necessarily having to open up each entry in a separate interface via a clickable icon.

Properties:

• all the common properties for Subform Interfaces, plus:
• elementsInHeading (Required. An array of element ids, indicating which elements from the source form should be shown as the headings that introduce each connected entry.)
• fullFormMode (Optional. A string, either ‘collapsable’ or ‘not_collapsable’. Default is ‘collapsable’. If ‘collapsable’, then the connected entries will be shown in collapsable accordions, labelled with the values of the element specified in the elementsInHeading property. If ‘not_collapsable’, then the connected entries will be embedded in the page one after the other, with the elements specified in the elementsInHeading property used as headers above each form.)

Examples:

• A ‘Full Form’ Subform Interface that shows connected entries in form 198. Show the values of elements 201 and 202 as the heading for each connected entry. Do not show the Add Entry button: { sourceForm: 198, elementsInHeading: [201, 202],showAddButton: 0 }
• A ‘Full Form’ Subform Interface that shows connected entries in form 31. Show the value of element 69 as the heading for each connected entry. Sort the connected entries by the value of element 69. Show the connected entries as embedded forms one after the other, not in collapsable accordions: { sourceForm: 31, elementsInHeading: [69], sortingElement: 69, fullFormMode: ‘not_collapsable’ }

Subform Interface Type: Listings (subformListings).

Description: This Subform Interface provides a list view of connected entries. Each entry shows up as a row in a table, with a clickable icon to open up the full entry for viewing or editing. This is best for situations when users simply need to see a listing of entries, and/or when forms have a too many elements for comfortably showing in editable rows (generally more than 5).

Properties:

• all the common properties for Subform Interfaces, plus:
• elementsInRow (Required. An array of element ids, indicating which elements from the source form should be shown in the list view. The values of these elements will be shown in each row. The values will not be editable, they will be shown as plain text.)
• entryViewingMode (Optional. A string, either ‘off’, ‘form_screen’ or ‘modal’. If ‘off’, then there are no clickable icons for opening up each connected entry for viewing/editing. If ‘full_screen’ then there are clickable icons, and they will cause the page to reload with the correct Form Screen for showing the connected entry. If ‘modal’ then there are clickable icons, and they will open a modal popup box for showing the connected entry. Default is ‘full_screen’. For small forms, ‘modal’ is usually best. For large forms, ‘full_screen’ is usually best. If a user should not be able to view/edit the embedded entries, or does not need to, then set this to ‘off’.

Example:

• A ‘Listings’ Subform Interface that shows the values of elements 101, 102, 103, and 104, from connected entries in form 97. Sort the entries by the value of element 101. Open entries in a modal popup for viewing/editing: { sourceForm: 97, elementsInRow: [101, 102, 103, 104], sortingElement: 101, entryViewingMode: ‘modal’ }