Forms

A form definition configures which columns (verticals), datasets, and services power a form component. Each vertical maps to a rendered column in the form layout and can contain sections (collapsible groups) or a flat list of field references.

Field names referenced inside verticals/sections must match keys defined in the Fields configuration.

"createIssueForm": {
  "verticals": [
    {
      "name": "column1",
      "sections": [
        {
          "id": "basicInfo",
          "title": "Basic Information",
          "fields": [
            "issue_title",
            "issue_desc"
          ]
        }
      ]
    },
    {
      "name": "column2",
      "fields": [
        "issue_priority",
        "issue_state"
      ]
    }
  ],
  "datasets": [
    "contextNode"
  ],
  "services": [
    "fetchIssueTypes"
  ],
  "edit": {
    "services": [
      { "name": "updateIssue" }
    ]
  }
}

Form properties

Property	Type	Required	Description
`verticals`	`array`	yes	Ordered list of column definitions rendered left-to-right in the form. Each entry is a Vertical.
`datasets`	`array<string>`	yes	Dataset definition name references that provide the graph/node data context. Field values are resolved against these datasets.
`services`	`array<string>`	no	Service definition names called eagerly on form load to fetch initial data into the graph before fields are resolved.
`deferredServices`	`array<string>`	no	Service definition names called lazily after initial load. Useful when a service depends on a value only available after the form has first rendered.
`toolbars`	`string`	no	Toolbar definition name reference for actions above the form. Uses the same top-level `toolbars` and `commands` maps as tables.
`mode`	`string`	no	`create`, `edit`, or `view`. `create` uses the create submit handler and does not require a selected table row.
`defaultEdit`	`boolean`	no	When `true`, the form opens in edit mode by default.
`isRowSelectionRequired`	`boolean`	no	When `true`, the form is not shown until at least one table row is selected.
`edit`	`object`	no	Configuration applied when the form is saved in edit mode. See Edit.

Forms support the same declarative toolbar pattern as tables. Reference a toolbar by name from the form definition; commands are defined in the top-level commands map.

"forms": {
  "droppedEditForm": {
    "toolbars": "droppedEditFormToolbar",
    "verticals": ["..."]
  }
},
"toolbars": {
  "droppedEditFormToolbar": {
    "commands": [{ "name": "openCreateForm" }, { "name": "openEditForm" }]
  }
},
"commands": {
  "openCreateForm": {
    "type": "panel",
    "label": "Create Asset",
    "settings": {
      "panelId": "assetSidePanel",
      "formId": "createForm"
    }
  },
  "openEditForm": {
    "type": "panel",
    "label": "Edit Asset",
    "settings": {
      "panelId": "assetSidePanel",
      "formId": "editForm"
    }
  }
}

The same command names can be reused on a table toolbar. Add useSelectedRow: true there only — see Commands — Panel commands.

uip-xui binds command handlers before rendering; uip-form only displays pre-bound buttons (same split as genericApiCallback on button fields).

Form toolbar panel commands always bind the target form from the source form's context, in this order:

selectedRows on the source form (single row)
contextIds / environment context on the source form (single object)
The current bean row on the source form

Do not use useSelectedRow on form toolbars — it is ignored and applies to table toolbars only.

Supported command types on forms:

Type	Description
`panel`	Open a layout panel and mount a form (see Commands)
`edit`	Toggle edit mode on the host form (form toolbar only)
`genericService`	Call a service on the form context row
`launchFormAsModal`	Open another form in a modal

Table-only types (search, export, expandAll) are not bound on form toolbars. The built-in edit command is form-only and is ignored on table toolbars.

The built-in edit command toggles the host form between read and edit mode. No type is required — the runtime binds it by command name on form toolbars only. Define the command once under commands, then reference it from a form toolbar.

Set defaultEdit: false on forms that should start read-only.

"commands": {
  "edit": {
    "label": "Edit",
    "icon": "Pencil"
  }
},
"droppedEditFormToolbar": {
  "commands": {
    "edit": { "name": "edit" }
  }
}

Create mode

Set mode: "create" on a form that creates new objects (no existing row context). The runtime wires createNewObject as the submit handler and keeps that handler even when linked tables refresh their bean (refreshOnBeanCreation).

"createForm": {
  "mode": "create",
  "datasets": {},
  "verticals": [{ "fields": ["title", "description"] }],
  "edit": {
    "services": [{ "name": "createAsset" }],
    "successResponseMsg": "Asset created."
  },
  "additionalFormParams": {
    "submitLabel": "Create",
    "showEdit": false
  }
}

Use edit.services for the create API as well — the same edit block configures persistence for both create and edit forms.

Panel lifecycle

Forms shown inside a panel do not close automatically by default. Configure which form button actions close the panel with settings.closePanelOn:

"createForm": {
  "settings": {
    "closePanelOn": ["submit", "cancel"]
  }
}

Value	When the panel closes
`submit`	After a successful form submit
`cancel`	When the user cancels or switches back to view mode

Omit closePanelOn or set it to [] to keep the panel open after all button actions. collapsePanelOn and submitSuccess are supported as aliases.

Vertical properties

Each entry in verticals defines one column in the form layout.

Property	Type	Required	Description
`name`	`string`	yes	Unique name for this column, used to reference it from the `verticals` list.
`title`	`string`	no	Optional display title for the column.
`sections`	`array`	no	List of Section objects that group related fields under collapsible headers. Use either `sections` or `fields`, not both.
`fields`	`array`	no	Flat list of field references rendered directly in the column without grouping. Use either `fields` or `sections`, not both.

Section properties

Sections group fields within a column under a collapsible header.

Property	Type	Required	Description
`id`	`string`	yes	Unique identifier for the section within the form.
`title`	`string`	no	Header label displayed in the section's toggle bar.
`collapsed`	`boolean`	no	When `true`, the section starts collapsed. Defaults to `false` (expanded).
`hidden`	`boolean`	no	When `true`, the section and all its fields are hidden. Can be driven dynamically via `visibility`.
`visibility`	`object`	no	Controls section visibility based on another field's value. See Visibility.
`fields`	`array`	no	Ordered list of field references to render inside this section.

Section visibility

Property	Type	Description
`dependsOn`	`string`	The `name` or `id` of the field whose value controls this section's visibility.
`dependsOnValue`	`string` or `array<string>`	The value(s) the `dependsOn` field must match for the section to be shown. Any other value hides the section.

Field reference

Each item in a vertical's fields array or a section's fields array is a string reference to a field definition key.

Value	Type	Required	Description
field key	`string`	yes	The key of the field definition as declared in the `fields` configuration.

Edit properties

Property	Type	Description
`services`	`array<object>`	List of services called when the form is saved in edit mode. Each object has a `name` property with the service definition name to invoke (typically a PATCH or POST service).

Edit services example

"edit": {
  "services": [
    { "name": "updateIssue" }
  ]
}

Forms

Form properties​

Toolbar​

Create mode​

Panel lifecycle​

Vertical properties​

Section properties​

Section visibility​

Field reference​

Edit properties​

Edit services example​