Pages and Conditional Rendering

Every form is comprised of one or more pages, with each page having a label, a description and one or more fields. A simple form only needs one page, but if you have a more complex flow, you may want to separate fields into multiple steps to be shown in succession.

Conditional rendering is a technique that allows pages to be shown or hidden based on the values of previous fields. This can be useful for creating complex and dynamic forms with a large number of fields and pages.

In our JSON definition, the pages array contains objects that represent each page in the form. Each page object has a label property that specifies the page's name, and a fields array that contains the fields that belong to the page.

To enable conditional rendering for a page, an additional property called conditions can be added to the page object. The conditions array represents a series of conditions which all have to be true for the page to be shown.

Each condition has two operands, and one operator. Possible operators are: IS, IS_NOT, CONTAINS, CONTAINS_NOT. The operands can either be keys of fields, or literal values to be compared. This allows for complex boolean operations. For example, consider this JSON definition:

{
  "title": "Order product",
  "description": "Description",
  "submitText": "Order",
  "pages": [
    {
      "label": "Base information",
      "description": "Description for the base information page",
      "fields": [
        {
          "name": "productName",
          "displayText": "Product name",
          "description": "The name of the product",
          "type": "Combobox",
          "items": [
            {
              "displayText": "A personalized t-shirt",
              "value": "personalized-tshirt"
            },
            {
              "displayText": "A pen",
              "value": "pen"
            },
            {
              "displayText": "A mug",
              "value": "mug"
            }
          ]
        }
      ]
    },
    {
      "label": "Additional Information",
      "fields": [
        {
          "name": "tshirtPrintText",
          "displayText": "What to print on the tshirt",
          "type": "Textbox"
        }
      ],
      "conditions": [
        {
          "operator": "IS",
          "operand1": "productName",
          "operand2": "personalized-tshirt"
        }
      ]
    }
  ]
}

The second page, “Additional Information”, will only be shown if a user chooses the personalized t-shirt in the first step. The order of evaluation works like this:

We check if the operand1 refers to any field in the form. If it does, it gets the value the user selected. If not, the value will be used as a literal value.
We do the same for operand2.
We compare both operands according to the operation that was defined.

An example for another page:

{
  "label": "Doggo's name",
  "fields": [
    // Fields for the "Doggo's name" page go here.
  ],
  "conditions": [
    {
      "operator": "IS",
      "operand1": "productName",
      "operand2": "personalized-tshirt"
    },
    {
      "operator": "CONTAINS",
      "operand1": "tshirtPrintText",
      "operand2": "Doggo"
    }
  ]
}

In this case the page will only be shown if the user chose the personalized-tshirt option in the productName input, and then entered a string into the tshirtPrintText that contains the word Doggo.