LogoLogo
Getting StartedDevelopersDeployment GuideGet Help
  • Quick Links
  • Welcome to Form.io
    • Getting Started With Form.io
    • Launch a Form
    • Overview of Form.io
  • Developer Tool Ecosystem
    • PDF Solution
    • Enterprise Form Builder
    • Form View Pro
    • The Security Module
    • Accessibility Compliance Module
    • Developer License
    • SQL Connector - Deprecated
    • Integration Libraries
    • Form.io CLI Tool
  • User Guide
    • Introduction
    • Form.io Developer Portal
    • Teams
    • Projects
      • Project UI
      • Project Settings
      • Stages
      • Multi-Tenancy
    • Resources
      • ResourceJS
    • Forms
      • Form Creation
      • Form Types
      • PDF Forms
      • Embedding a Form
      • Form Revisions
      • Form Settings
    • Form Building
      • Form Builder UI
      • Form Components
        • Component Settings
        • Basic Components
          • Resource as Select Component Data Source
        • Advanced Components
        • Layout Components
        • Data Components
        • Premium Components
          • Nested Forms
        • Custom Components
      • Logic & Conditions
      • Existing Resource Fields
      • Actions
    • Submissions
      • Accessing Submissions
      • Importing Submissions
    • Form.io eSignature - Coming Soon
    • Form.io Reporting Module
    • PDF Template Designer
    • Form View Pro
    • Form Manager
    • Enterprise Form Builder Module
      • Installation
      • User Guide
  • Developer Guide
    • Introduction
      • Application Development
      • API Documentation
    • Form Development
      • Form Renderer
      • Form Builder
      • Form Embedding
      • Form Evaluations
      • Form Templates
      • Custom Components
      • Translations
    • JavaScript Development
      • JavaScript SDK
      • JavaScript Frameworks
      • JavaScript Utilities
    • Authentication and Authorization
      • SAML
      • OAuth
      • LDAP
      • Resource Based Authentication
      • Email Authentication
      • Two-Factor Authentication
    • Roles and Permissions
      • Field Match-Based Access
      • Field-Based Resource Access
      • Group Permissions
    • Integrations
      • Email Integrations
      • File Storage
      • Google Developer Console
      • eSign Integrations
      • Relational Databases
    • Modules
    • Fetch Plugin API
    • CSS Frameworks
    • Offline Mode
    • Audit Logging
  • Deployments
    • Self-Hosted Deployment
      • Local Deployment
        • Local File Storage
      • Kubernetes
      • Cloud Deployment
        • AWS Deployment
          • AWS Lambda
          • Form.io/AWS Elastic Beanstalk End-To-End Encrypted Deployment
        • Azure Deployment
          • Azure App Service
            • Azure MSSQL Connector - Deprecated
          • Azure Virtual Machine
          • Azure Kubernetes Service
          • Set up the DB
        • GCP Deployment
          • GCP Cloud Run
      • On-Premise Deployment
      • Enterprise Server
      • PDF Server
    • Deployment Configurations
      • DNS Configuration
      • Load Balancer Configuration
    • Licenses
      • License Management
      • Library Licenses
    • Portal Base Project
      • Portal SSO
      • Portal Translations
    • Maintenance and Migration
      • Changes to Premium Libraries
  • FAQ
    • FAQ
    • Tutorials & Workflows
      • Password Reset
      • Dynamic Select Filtering
      • Approval Workflow
      • SSO Email Token
      • Embedding A Video
      • Data Source Validation
      • Select Data Source Options
      • Nested Form Workflows
        • Nested Wizard Forms
      • Save as Draft
      • Role-Based Conditions
      • Custom Component
      • Dynamic Radio and Select Box Values
      • Override CKEDITOR
    • Errors
    • Examples
    • License Utilization Checks
    • Glossary of Key Concepts
  • Contact Us
Powered by GitBook
On this page
  • Example
  • Form JSON
  • Submission Data
  • Editing a Child Form
  • The "Save as reference" Option
  • Form JSON with "Save as reference" enabled
  • Submission Data with "Save as reference" enabled
  • Editing Submission Data with "Save as reference" enabled
  • Editing Child Forms With "Save as reference" enabled
  • Nested Forms For Remotely Deployed Projects

Was this helpful?

  1. User Guide
  2. Form Building
  3. Form Components
  4. Premium Components

Nested Forms

Additional details about the Nested Form premium component.

PreviousPremium ComponentsNextLogic & Conditions

Last updated 5 months ago

Was this helpful?

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 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:

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:

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:

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 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.

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.

Form JSON with "Save as reference" enabled

The Form JSON of a Nested Form component changes slightly when "Save as referenced" is 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:

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:

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

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.

{

"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.

data:

trip: "roundTrip"

vehicleType: "bus"

numberOfPassengers: 18

submit: true

contactInfo:

data:

firstName: "Richard"

lastName: "Reference"

email: "referee@form.io"

phoneNumber: "(312) 106-1309"

Submission JSON with "Save as reference" enabled.

data:

trip: "oneWay"

vehicleType: "van"

numberOfPassengers: 5

contactInfo:

data:

firstName: "Dereck"

lastName: "Direct"

email: "noreference@form.io"

phoneNumber: "(512) 212-7474"

metadata: {}

submit: true

Submission JSON without "Save as reference" enabled.

section of this document
Nest Form configuration.
The Parent Form with the Nested Form configuration.
Parent Form displaying the nested Child Form components, highlighted in blue.
The Data Tab of the Parent Form recording a submission.
Select a specific revision of the Child Form.
The "Save as reference" option in the Nested Form component.
The Data Tab of the Parent Form recording a submission will be the same when the Child Form is Saved As Reference.
The Data Tab of a Child Form with submissions recorded from multiple Parent Forms.