Form Effects Reference

This page is the compact persisted-schema reference. Open the topic page for execution details and worked examples.

Need	Page
Trigger forms and when	Triggers and conditions
set, copy, dispatch	Actions
clear modes and arrayBehavior	Clearing and resetting
script, runEffect, action ordering	Scripts and execution order
Paths, context, data sources	Paths and expressions
$row and nested widgets	Arrays and nested forms
Validation and runtime errors	Diagnostics and troubleshooting

Schema Location

Effects are stored in the root schema's effects array:

{
  "type": "object",
  "properties": {
    "firstName": {"type": "string"},
    "lastName": {"type": "string"},
    "fullName": {"type": "string"}
  },
  "layout": ["firstName", "lastName", "fullName"],
  "effects": [
    {
      "id": "combine-names",
      "listen": ["$value.firstName", "$value.lastName"],
      "when": "${$value.firstName != null || $value.lastName != null}",
      "do": [
        {
          "type": "set",
          "field": "fullName",
          "value": "${[$value.firstName, $value.lastName].filter(x => x).join(' ')}"
        }
      ]
    }
  ]
}

Effect Object

Property	Required	Type	Description
id	Conditional	string	Identifier used for diagnostics and references. Required and unique for an invoked effect. Unique IDs are recommended for every effect.
name	No	string	Human-readable label used only for display and documentation.
description	No	string	Longer human-readable explanation. It does not affect execution.
listen	Conditional	string[]	Paths watched by a value-change effect. Mutually exclusive with trigger.
trigger	Conditional	EffectTrigger	A widgetEvent or invoked trigger. Mutually exclusive with listen.
when	No	string	JEXL condition. The effect runs only when it evaluates to boolean true.
do	Yes	EffectAction[]	Actions executed in array order when the condition passes.
disabled	No	boolean	Keep the effect in the schema but skip it at runtime.
runOnInitialization	No	boolean	Run a value-change effect once after initialization settles. Default: false.

When when is omitted, the condition is treated as satisfied and do runs after the trigger fires.

An effect is one of three forms:

// Value change
{listen: string[], when?: string, do: EffectAction[]}

// Widget event
{trigger: {type: 'widgetEvent', objectPointer: string, event: string}, do: EffectAction[]}

// Explicit invocation
{id: string, trigger: {type: 'invoked'}, do: EffectAction[]}

Widget Event Catalog

Representative built-in widget events include:

Widget	Events	Known payload
dtl-button, dtl-create-entity-button, dtl-submit-request-button	success, error	Operation-specific response
dtl-fluent-inplace	saveSuccess, saveError, scriptSuccess, scriptError	Save or script outcome
dtl-attachments-widget	uploadSuccess, uploadError, uploadScriptSuccess, uploadScriptError, deleteAttachmentSuccess, deleteAttachmentError, deleteAttachmentScriptSuccess, deleteAttachmentScriptError	Upload, deletion, or script response
dtl-fluent-accordion	panelOpened, panelClosed	index, header
dtl-fluent-tab	activeTabChanged	previousIndex, activeIndex, previousId, activeId
dtl-fluent-steps	activeStepChanged, stepsViewStateChanged	Transition IDs/indexes or visited-step counts
dtl-fluent-accordion-array	activeItemChanged	Nullable previousIndex, activeIndex
dtl-form-input-text	leftIconClicked, rightIconClicked	No payload
dtl-clipboard-button	copySuccess, copyError	Error reason when copying fails
LOV widgets with create support	itemCreated	id, value

This table is intentionally representative. The selected widget's event list in the Form Designer is the source of truth for the installed widget version.

Legacy widget actions

Older schemas can contain successDo, errorDo, saveSuccessDo, or similar arrays inside widget configuration. They remain runtime-compatible. When the schema is edited, the Form Designer migrates them to root widget-event effects and removes the legacy arrays from the widget configuration.

Legacy ${$response.total} expressions may become ${$event.payload.total}. This is equivalent to the preferred ${$payload.total} form.

Configuration Effects

Plugins and base-form configurations can supply predefined effects for an entity type. These effects:

• use the same runtime contract as schema effects;
• are visible but read-only in the Form Designer;
• are applied automatically to forms using that configuration;
• can be deactivated for one schema by ID.

The designer persists deactivation as a minimal disabled stub:

{
  "id": "configuration-effect-id",
  "disabled": true,
  "listen": [],
  "do": []
}

At runtime, configuration and schema effects are matched by id. A disabled schema stub suppresses the matching configuration effect. Other form-owned effects remain unchanged.

To deactivate a configuration effect:

1. Open the form in the Form Designer.
2. Open Effects.
3. Expand the effect in Configuration Effects.
4. Enable Deactivate this effect in schema.