Skip to main content

Plugin fields

Plugin fields​

Plugin fields allow a widget to render a custom React field inside uip-form while still using the standard form state, validation, and submit flow.

Plugin implementations belong in widgets-service-admin as custom widget resources (see widgets-service-admin/field-plugins/). The widget-box runtime only provides the generic registerFieldRenderer API and PluginField host.

Configuration​

Use type: "plugin" and provide a renderer key with fieldRenderer (or settings.fieldRenderer).

{
  "fields": {
    "myHierarchy": {
      "label": "Hierarchy",
      "data": "hierarchy",
      "type": "plugin",
      "fieldRenderer": "HIERARCHY_FIELD",
      "settings": {
        "fieldRendererProps": {
          "height": 360
        }
      }
    }
  }
}

Registering a renderer (widgets-service-admin)​

Add a resource script under widgets-service-admin/src/main/resources/conf/ (company or common) and list it in the widget config resources array. On load, register with:

window.plugin.registerFieldRenderer('MY_FIELD', {
  getValue(rawValue) { /* optional */ },
  setValue(nextValue) { /* optional */ },
  render({ field, value, onChange, disabled, editMode, plugin }) {
    // return a React node
  },
});

For React field plugins with dependencies, use widgets-service-admin/field-plugins/ (esbuild bundle). Example: hierarchyField.js registers HIERARCHY_FIELD.

The widget runtime exposes globalThis.React for plugin resources. Field plugin builds must not bundle their own React (see field-plugins/shims/).

Renderer contract​

A plugin field renderer is registered on the widget plugin API under a key (e.g. HIERARCHY_FIELD) and must provide:

  • getValue(rawValue) (optional): normalize the stored form value for rendering
  • setValue(nextValue) (optional): serialize the value back into form state
  • render(params): return a React node

The render function receives:

  • field: full field config object
  • value: normalized value (output of getValue)
  • onChange(nextRawValue): call with the next value; it will be passed through setValue before being stored
  • disabled, editMode, fields, localize, plugin

settings.fieldRendererProps​

Opaque options passed to the registered renderer. The schema does not constrain these — each plugin documents its own props. Example for a graph-based hierarchy field:

"settings": {
  "fieldRendererProps": {
    "height": 360,
    "fitToContent": true,
    "graph": { "nodes": [], "edges": [], "assignments": {} }
  }
}

Build React plugins under widgets-service-admin/field-plugins/ and list the bundle in widget resources. Do not bundle React in the plugin — the widget runtime exposes globalThis.React (see field-plugins/shims/).