Custom Components

The Imixs Form Specification defines a set of standard input types that every conforming implementation must support. Beyond these, any application built on Imixs-Workflow can define and register its own custom components — without modifying the BPMN model structure or the workflow engine itself.

This extensibility is by design. The specification defines two levels at which custom components can be introduced:

  • Custom Item — a single input field rendered by a custom component
  • Custom Section — an entire form section rendered by a custom component

In both cases the workflow engine stores the XML as-is and plays no role in rendering. The application resolves the custom component at runtime.

Custom Items

A custom item replaces a single <item> with an application-specific input component. It is defined by setting type="custom" and adding a path attribute that identifies the component:

<imixs-form-section label="Request">
  <item name="request.text" type="custom" path="markdowneditor" label="Request:" />
</imixs-form-section>

Attributes

Attribute Type Mandatory Description
type text ✓ Must be custom
path text ✓ Identifies the custom component to be rendered
name text ✓ The item name in the workitem (same as for standard types)
label text Optional visible label (same as for standard types)
readonly boolean Optional, renders the component as read-only
options text Optional configuration string, interpreted by the component

The path value is application-specific. How it is resolved — whether as a file path, a component name, a CDI bean identifier, or any other mechanism — depends entirely on the rendering implementation.

Responsibilities

A custom item component is responsible for:

  1. Rendering an appropriate UI element for the given name and path
  2. Reading the current value from the workitem item identified by name
  3. Writing the user's input back to the workitem item identified by name

The data type stored in the workitem is defined by the custom component itself, not by this specification.

Example: Markdown Editor

<item name="request.body" type="custom" path="markdowneditor" label="Request:" />

Example: Custom Component with Options

The options attribute can pass configuration to the component. Its format and interpretation are entirely up to the component:

<item name="product.image" type="custom" path="imageupload"
      label="Product Image:" options="maxsize=2MB;accept=image/png,image/jpeg" />

Custom Sections

A custom section replaces an entire <imixs-form-section> with an application-specific component. This is useful for complex form areas that go beyond what individual items can express — for example sections with conditional visibility, dynamic content, or multiple interacting fields.

A custom section is defined by adding a path attribute directly to the <imixs-form-section> element. It contains no <item> children:

<imixs-form-section label="References" path="sub_references_form" />

Attributes

Attribute Type Mandatory Description
path text ✓ Identifies the custom section component to be rendered
label text Optional visible heading for the section
readonly boolean Optional, signals to the component that it should render read-only

Responsibilities

A custom section component takes full control over its rendering area. It is responsible for:

  1. Rendering the complete section UI for the given path
  2. Reading and writing workitem data directly, using whatever item names it requires
  3. Respecting the readonly attribute when provided

A custom section may implement any interaction pattern supported by the host application, including dynamic updates and interdependent fields. The details of that interaction are outside the scope of this specification and are defined by the application.

Implementing Custom Components in Your Application

How custom components are implemented depends on the technology stack of the application. The following projects provide documented extension mechanisms:

  • Imixs-Office-Workflow — supports custom items and custom sections via Jakarta Faces composite components. See the Custom Input Parts documentation for a step-by-step guide.

  • Imixs-Forms (JavaScript) — custom types can be registered as JavaScript modules at application startup. See the Imixs-Forms repository for details.

If you are building your own application on top of Imixs-Workflow, you are free to define your own resolution mechanism for the path attribute. The only contract this specification defines is the XML structure of the <item> and <imixs-form-section> elements.

Portability Considerations

Because custom components are application-specific, form definitions that use type="custom" or a path on a section are not fully portable across different implementations. When sharing BPMN models between applications, keep the following in mind:

  • Standard types (text, date, currency, etc.) are always portable.
  • Custom items and sections are only rendered correctly by applications that have the referenced component registered under the same path name.
  • If a rendering application encounters an unknown path, it should degrade gracefully — for example by rendering a plain text input or skipping the section entirely.

This is not a limitation but a deliberate trade-off: it allows each application to build rich, domain-specific form components while keeping the core specification lean and stable.