Nested Forms

Additional details about the Nested Form premium component.

Use Nested Forms to save time by constructing forms that will be re-utilized through the course of a project and application. The Nested Forms component can integrate Child Forms into all different kinds of parent forms within an application, all while collecting and housing submission data into one primary source.

Nested Forms with the "Save as Reference" option selected behave significantly differently. Refer to the appropriate section of this document for guidance and best practices.

Example

In the following example, consider a form and its set of fields, which have been standardized to be reused multiple times throughout a project, in various other Forms. Instead of recreating the same fields and settings, create a single form called Contact Info. This will become the Child Form:

Next, add this form to one of the existing forms inside the project. The screenshot below shows a Parent Form:

Instead of adding individual fields, drag and drop the Nested Form component onto the Parent Form and configure it to pull in the Contact Info form:

Nest Form configuration.

Note the "Save as reference" option. This is described in greated detail later in this document. The configured Nested Form component will appear in the Form Builder as follows:

The Parent Form with the Nested Form configuration.

When the form is rendered the fields from the Parent Form are visible, in addition to the fields included in the Child Form. All settings and configurations for the Child Form fields are retained:

Parent Form displaying the nested Child Form components, highlighted in blue.

Form JSON

Even though the form renderer will display the Child Form components as usual within the Parent Form, the Parent Form JSON will not directly contain the components of the Child Form. Instead, it will contain a pointer to the Child Form, in the form of the Child Form's reference ID. The reference ID can be found in the Form JSON of the Child Form, typically as the first line. The form JSON of a Nested Form component will look similar to the following snippet.

"components": [
    {
      "label": Nested Form display label,
      "tableView": true,
      "form": Form_ID_of_Child_Form,
      "useOriginalRevision": false,
      "reference": false, //refer to "Save as reference" section for guidance
      "key": nested_form_component_name,
      "type": "form",
      "input": true
    },

Submission Data

When a Parent Form is submitted, the submission data will merge the child and parent data together. On the Developer Portal Data tab, a submission against the Parent Form will display data contained within the Child Form in a column labeled with the name of the Nested Form component, and recorded as "[Complex Data]".

The Data Tab of the Parent Form recording a submission.

The JSON of a submission against a Parent Form will contain the data submitted against all components of the Child Form. It will look similar to the following:

data:
   parent_component1: submitted_value
   parent_component2: submitted_value
   <nested_form_component_name>: 
      data:
         child_componentA: submitted_value
         child_componentB: submitted_value

Editing a Child Form

Saving changes to a Child Form will cause the changes to that form to be reflected in all Parent Forms that have included it as a Nested Form when those Parent Forms rendered.

If a component is added to the Child Form, any submissions recorded before the addition of that field will not contain any references to it. If a component is deleted, any submissions recorded before the deletion will still contain that data. Ensure your data handling and business processes account for this when modifying a Child Form.

If the optional Form.io Security Module is purchased and deployed, the desired revision of the Child Form can be specified when configuring the Nested Form component on the Parent Form.

Select a specific revision of the Child Form.

Additionally, the option "Use Original Revision while Submissions Viewing" will ensure the same revision of the form that was used to generate a submission is used whenever that submission is viewed, regardless of what the revision is currently nested in the Parent Form.

The "Save as reference" Option

The "Save as reference" option in the Form tab of the Nested Form Component changes the behavior of the component and submission data in several ways.

The "Save as reference" option in the Nested Form component.

Form JSON with "Save as reference" enabled

The Form JSON of a Nested Form component changes slightly when "Save as referenced" is enabled:

{

"label": "Contact Info",

"tableView": true,

"form": "676ac85d54e952a35e7f307b",

"useOriginalRevision": false,

"key": "contactInfo",

"type": "form",

"input": true

},

Form JSON with "Save as reference" enabled.

{

"label": "Contact Info",

"tableView": true,

"form": "676ac85d54e952a35e7f307b",

"useOriginalRevision": false,

"reference": false,

"key": "contactInfo",

"type": "form",

"input": true

},

Form JSON without "Save as reference" enabled.

Submission Data with "Save as reference" enabled

When "Save as reference" is enabled, the form submission will be recorded against the Parent Form as well as the Child Form. On the Developer Portal Data tab, the Parent Form data will be recorded as seen earlier in this document:

The Data Tab of the Parent Form recording a submission will be the same when the Child Form is Saved As Reference.

Since the Child Form will record Parent Submissions as its own submission, and it may be included in other Forms across the project, the Data tab will record submissions from all Parent Forms that enable "Save as reference." In this example below, the highlighted submission came from the example Parent Form, and matches the submission seen above:

The Data Tab of a Child Form with submissions recorded from multiple Parent Forms.

When "Save as reference" is enabled, the submission JSON is slightly different:

data:

trip: "roundTrip"

vehicleType: "bus"

numberOfPassengers: 18

submit: true

contactInfo:

data:

firstName: "Richard"

lastName: "Reference"

email: "[e-mail]"

phoneNumber: "[phone]"

Submission JSON with "Save as reference" enabled.

data:

trip: "oneWay"

vehicleType: "van"

numberOfPassengers: 5

contactInfo:

data:

firstName: "Dereck"

lastName: "Direct"

email: "[e-mail]"

phoneNumber: "[phone]"

metadata: {}

submit: true

Submission JSON without "Save as reference" enabled.

Editing Submission Data with "Save as reference" enabled

Remember that when "Save as reference" is enabled, a form submission is recorded against both the Parent Form and Child Form.

When a submission recorded with "Save as reference" is edited, the update is applied to both the Parent Form and Child Form. Editing a submission of the Parent Form will change the corresponding values in the submission of the Child Form synchronously. Editing a Child Form submission that was created by a Parent Form submission will change the corresponding values in the Parent Form submission. If a Parent Form submission is edited without changing any fields recorded in the Child Form submission, the "Updated" time of the matching Child Form submission will reflect this edit, even though no fields were changed.

This synchronization across submissions has significant effects and should be considered when designing forms and workflows.

Editing Child Forms With "Save as reference" enabled

The "Save as reference" setting does not affect the way changes to Child Forms are rendered in Parent Forms. Remember that saving changes to a Child Form will cause the changes to that form to be reflected in all Parent Forms that have included it as a Nested Form.

If the Child Form is changed, such as the addition of a new component, future submissions will record values for that field, though submissions recorded prior to the addition will not have any value on the Data tab and will not refer to the field in the submission JSON:

Nested Forms For Remotely Deployed Projects

If a project is remotely deployed with subdirectories, set up the application to perform an API call like the following:

 Formio.setProjectUrl(<project_URL>). 

This will help Form.io understand where to fetch nested resources from and will set up base URLs properly.