Form Controls Dependencies

Note: Spartacus 2.x is no longer maintained. Please upgrade to the latest version.

Overview

This page will explain how to show/hide form controls that have a dependency on different form fields and how changes on “parent” fields will affect their visibility.

In order to specify dependencies for a certain field, JSON schema is enhanced by exposing the property called “dependsOn”. The property represents array of complex objects and it consists of two properties:

• controlName - reflects the name of parent form field
• conditions - The conditions of parent control that need to be fulfilled. Conditions are validation functions of the parent field. If conditions are met then form control will be visible

Parent control - form control from which the specific abstract control (with defined dependsOn property) is dependant.

This logic can be applied to both single form control or form group.

Interface representation

export interface DynamicFormGroup {
  ...;
  dependsOn?: ControlDependency[];
}
 
export interface FieldConfig {
  ...;
  dependsOn?: ControlDependency[];
}
 
export interface ControlDependency {
  controlName?: string;
  conditions?: ValidatorFunction[];
}

It is necessary to constantly track value and validity of parent form controls and based on it, show/hide some form controls (group or specific field). For tracking validity, dynamic forms uses already defined validator functions. See this page for more info.

Example and Explanation

• Form field with the name “dependantField” is dependant on the form control with name “controlField” and condition for its visibility is that minimum value of “controlField” is 1.

{
    "type": "input",
    "name": "dependantField",
    "required": true,
    "dependsOn": [
        {
        "controlName": "controlField",
        "conditions": [
            {
            "name": "minValue",
            "arguments": [
                {
                "value": [1]
                }
            ]
            }
        ]
        }
    ]
}

• FormGroup with the name “dependantGroup” and all of the form fields that are defined in that group won’t be visible if the form control with name “controlField” is not equal or higher than 2.

{
   "groupCode": "dependantGroup",
   "dependsOn": [
     {
       "controlName": "controlField",
       "conditions": [
         {
           "name": "minValue",
           "arguments": [
             {
               "value": [2]
             }
           ]
         }
       ]
     }
   ],
  "formFields": [........]
}

• FormGroup with the name “dependantGroup” and all of form fields that are defined in that group won’t be visible if form control with name “controlField” doesn’t match values “test” or “test2”

{
"groupCode": "dependantGroup",
"dependsOn": {
  "hide": true,
  "controls": [
    {
      "controlName": "controlField",
      "conditions": [
        {
          "name": "checkValue",
          "arguments": [
            {
              "value": [
                "test",
                "test2"
              ]
            }
          ]
        }
      ]
    }
  ]
}

If hiding dependant filed is not desired, it can be only disabled using this functionality by setting “hide” property to false.