Widget UI definition

The widget UI definition contains field and group definitions in a JSON structure.

Defining UI fields

The minimal definition of a fields includes the id, type, title, and defaultValue.

Field model property	Type	Description
id	string	(required) - field id returned in the JSON data by onSingularValue()
type	string	(required) - type of data (infotext, text, textarea, number, checkbox, composition, button, selection, JSON, color, gradient, image, timecontrol)
title	string	Field title displayed in the widget UI
defaultValue	string	Default value

UI field definition

{
  "model": {
    "fields": [
      {
        "id": "textId",
        "type": "text",
        "title": "Single line text",
        "defaultValue": "enter text here ..."
      },
      {
        "id": "numberId",
        "type": "number",
        "title": "Number",
        "defaultValue": "50",
        "min": "0",
        "max": "100",
        "step": "0.1",
        "unit": "%",
        "format": "0.1"
      }
    ],
    "groups": [...]
  }
}

Grouping UI fields

Use groups to arrange UI fields in cards.

Group properties:

Field	Type	Description
id	string	(required) - group id
title	string	Group title
width	string	Width of card single (default) or double
toolTip	string	Tool tip trext
childIds	array of strings	Array of UI field ids

Group definition

{
  "model": {
    "fields": [...],
    "groups": [
      {
        "id": "groupId",
        "title": "Input Options",
        "width": "double",
        "toolTip": "Enter your values",
        "childIds": [
          "textId",
          "numberId"
        ]
      }
    ]
  }
}

Widget UI definition - full reference

{  
  "model": {
    "fields": [{
        "id": "infotextId",
        "type": "infotext",
        "title": "Info",
        "defaultValue": "this is a readonly text..."
      },
      {
        "id": "textId",
        "type": "text",
        "title": "Single line text",
        "defaultValue": "enter text here ..."
      },
      {
        "id": "textAreaId",
        "type": "textarea",
        "title": "Text Area",
        "defaultValue": "Enter text into this area...",
        "rows": "5",
        "cols": "15"
      },
      {
        "id": "numberId",
        "type": "number",
        "title": "Number",
        "defaultValue": "50",
        "min": "0",
        "max": "100",
        "step": "0.1",
        "unit": "%",
        "format": "0.1"
      },
      {
        "id": "checkboxId",
        "type": "checkbox",
        "title": "Enable",
        "defaultValue": false
      },
      {
        "id": "compositionId",
        "type": "composition",
        "title": "Composition",
        "defaultValue": ""
      },
      {
        "id": "buttonId",
        "type": "button",
        "title": "Click me",
        "defaultValue": ""
      },
      {
        "id": "selectionId",
        "type": "selection",
        "title": "Selection",
        "defaultValue": "0",
        "selections": [{
            "id": "0",
            "title": "Option 1"
          },
          {
            "id": "1",
            "title": "Option 2"
          },
          {
            "id": "2",
            "title": "Option 3"
          }
        ]
      },
      {
        "id": "jsonId",
        "type": "json",
        "title": "Json data",
        "defaultValue": "{}",
        "width": "350",
        "height": "200"
      },
      {
        "id": "useCustomParameterId",
        "type": "checkbox",
        "title": "Enable",
        "defaultValue": false
      },
      {
        "id": "colorId",
        "type": "color",
        "title": "Color",
        "defaultValue": "#9B9B9B"
      },
      {
        "id": "gradientId",
        "type": "gradient",
        "title": "Gradient",
        "defaultValue": "#9B9B9B"
      },
      {
        "id": "imageId",
        "type": "image",
        "title": "Image",
        "defaultValue": "https://app.singular.live/images/logo.png"
      }, {
        "id": "countdownControlId",
        "title": "TimeControl",
        "type": "timecontrol",
        "defaultValue": {
          "UTC": 0,
          "isRunning": false,
          "value": 0
        }
      }
    ],
    "groups": [{
        "id": "group1Id",
        "title": "Input Options",
        "width": "double",
        "toolTip": "Enter your values and define a custom widget composition",
        "childIds": ["infotextId", "textId", "textAreaId", "numberId", "checkboxId", "selectionId", "compositionId"]
      },
      {
        "id": "group2Id",
        "title": "Customize and Control Options",
        "width": "double",
        "toolTip": "Customize and control options",
        "activeId": "useCustomParameterId",
        "childIds": ["jsonId", "colorId", "gradientId", "imageId", "countdownControlId", "buttonId"]
      }
    ]
  }
}