update_subform_interface

Update an existing Subform Interface in a Formulize form.

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:

• 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.)
• sourceEntryFilter (optional, conditions that limit which of the connected entries are shown. See the sourceEntryFilter property in the schema.)
• keepFilteredValuesInSync (int, either 1 or 0. Defaults to 1. Only set to 0 in unusual circumstances. See the keepFilteredValuesInSync property in the schema.)

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 the full screen or the drawer.

Properties:

• all the common properties for Subform Interfaces, plus:
• elementsInRow (Optional. Leave out to keep the current elements. 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’, ‘full_screen’, ‘drawer’, ‘full_screen_for_new_entries_only’, or ‘drawer_for_new_entries_only’. Default is ‘off’, which means there are no clickable icons for opening up each source form entry for viewing/editing, and new entries show up as rows. 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 ‘drawer’ then there are clickable icons, and they will open the entry in a drawer that slides out from the right, over the page. For small forms, ‘drawer’ 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’. The ‘full_screen_for_new_entries_only’ and ‘drawer_for_new_entries_only’ are intended for situations where there should be no clickable icons, but new entries should open up in the full screen or the drawer for users to fill in.)

Examples:

• Add element 74 to the end of each row, and make element 66 read-only: { elementsInRow: [52, 66, 71, 74], disabledElementsInRow: [66] }
• Stop showing a Delete button, and add clickable icons that open each entry in the drawer: { showDeleteButton: 0, entryViewingMode: 'drawer' }
• Keep editing entries in the rows only, without clickable icons, but open new entries in the drawer so all their elements can be filled in: { entryViewingMode: 'drawer_for_new_entries_only' }

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 (Optional. Leave out to keep the current elements. 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:

• Show the value of element 203 as the heading for each connected entry, instead of the current heading elements: { elementsInHeading: [203] }
• Show the connected entries as embedded forms one after the other, instead of in collapsable accordions, and hide the Add Entry button: { fullFormMode: 'not_collapsable', showAddButton: 0 }

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 (Optional. Leave out to keep the current elements. 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 ‘full_screen’, ‘drawer’, ‘off’, ‘full_screen_for_new_entries_only’ or ‘drawer_for_new_entries_only’. Default is ‘full_screen’, which means there are clickable icons, and they will cause the page to reload with the correct Form Screen for showing the connected entry. New entries open the same way. If ‘drawer’ then there are clickable icons, and they will open the entry in a drawer that slides out from the right, over the page. New entries open the same way. If ‘off’, then there are no clickable icons for opening up each connected entry for viewing/editing, and new entries show up as rows. For small forms, ‘drawer’ is usually best. For large forms, ‘full_screen’ is usually best. If a user should not be able to view/edit the connected entries, or does not need to, then set this to ‘off’. The ‘full_screen_for_new_entries_only’ and ‘drawer_for_new_entries_only’ values are intended for situations where there should be no clickable icons, but new entries should open up in the full screen or the drawer for users to fill in. Since the rows in this Subform Interface are not editable, use one of these instead of ‘off’ if users need to add new entries.)

Examples:

• Change which elements from the source form are shown, to elements 101, 102 and 105, and sort the entries by the value of element 105: { elementsInRow: [101, 102, 105], sortingElement: 105 }
• Open entries in the drawer for viewing/editing, instead of in the full screen: { entryViewingMode: 'drawer' }
• Remove the clickable icons for viewing/editing entries, but still open new entries in the drawer so users can fill them in: { entryViewingMode: 'drawer_for_new_entries_only' }