UI events - Docs

Available starting with FlowX.AI 5.3.0: UI Events enable real-time interaction handling directly within Reusable UI Templates, allowing you to capture user interactions and respond immediately without process execution.

Overview

UI events allow you to define JavaScript expressions that execute when users interact with UI components. Unlike UI actions that communicate with the backend, UI events operate entirely on the client side to update local data instantly. UI events were introduced to reduce UI load time and address related UX issues. The expressions are evaluated by the SDKs at runtime on the front-end side, leading to faster load times. They are intended for more complex business logic than what is handled by simple hide expressions or computed expressions.

No server roundtrip

Update data locally without waiting for backend responses

Instant feedback

Provide immediate UI updates as users interact with components

Simplified logic

Replace complex business rule chains with simple expressions

Computed expressions

Use JavaScript to calculate and transform data on the fly

Key characteristics

Characteristic	Description
Client-side evaluation	Expressions are executed on the client side by the SDKs, not on the server
Action timing	Evaluated right before executing a UI action (if one is configured), but not exclusive to actions
Local data updates	Updated variables are stored locally on the UI and not available on the process engine’s server data store until a submit action is executed
Data source requirements	Must rely only on properties already displayed on the screen; if a property used in the expression is not configured on the page to be sent from backend to frontend, the expression will fail
Component availability	Currently available only for form elements (see supported components)

Data availability: UI event expressions can only access data that is already being sent from the backend to the frontend for display on the current page. If you reference a property that isn’t configured to be sent to the UI, the expression will fail.

Traditional approach vs UI events

Previously, updating derived values required a multi-step process:

User changes input

User modifies a form field value

UI action triggers

A UI action sends data to the backend

Business rule executes

Server-side business rule calculates new values

Data returns to UI

“Send data to user interface” action pushes updated data back

With UI events, steps 2-4 are replaced by a single client-side expression that evaluates instantly.

Configuring UI events

UI events are configured in the UI Designer through a dedicated section located above the UI Actions panel.

Event configuration structure

Each event configuration consists of:

Event trigger: The user interaction that initiates the expression (e.g., onChange, onClick)
Expression: A JavaScript computed expression that calculates and returns new data

Platform configuration

UI events are stored in the component’s platformDisplayOptions under the events property:

{
  "platformDisplayOptions": {
    "platform": "generic",
    "flowxProps": {
      "events": [
        {
          "event": "onChange",
          "expression": "const prc = ${client.debt} / ${client.income};\nreturn {\n  \"client\": {\n    \"debtPrc\": prc\n  }\n}"
        }
      ]
    }
  }
}

UI events are available in both the Process UI Designer and the Reusable UI Templates Designer.

Writing event expressions

Event expressions use the same JavaScript syntax as computed values, with one key difference: instead of returning a single value, event expressions return an object that updates the local data store.

Expression syntax

// Access process parameters using ${} syntax
const calculatedValue = ${client.debt} / ${client.income};

// Return an object to update local data
return {
  "client": {
    "debtPercentage": calculatedValue
  }
}

Comparison with business rules

Aspect	Business Rule	UI Event Expression
Input access	`${}` syntax	`${}` syntax
Logic language	Python, JavaScript, MVEL	JavaScript only
Output syntax	`output.put(key, value)`	`return { }`
Execution	Server-side	Client-side (SDK)
Latency	Network roundtrip	Instant

Expression examples

Calculate percentage
Conditional formatting
String transformation
Array operations

Calculate debt-to-income ratio when income or debt changes:

const prc = ${client.debt} / ${client.income};
return {
  "client": {
    "debtPrc": prc
  }
}

Supported components and events

UI events are currently available for form elements. Each UI component type supports specific event triggers:

Component	Event	Trigger Description
Input	`onChange`	When the input value changes
Text area	`onChange`	When the text content changes
Select	`onChange`	When a selection is made
Multi select	`onChange`	When selections change
Date picker	`onChange`	When a date is selected
Slider	`onChange`	When the slider value changes
Radio	`onChange`	When a radio option is selected
Checkbox	`onChange`	When the checkbox state changes
Segmented button	`onChange`	When a segment is selected
Switch	`onChange`	When the switch is toggled

Future enhancement: An improvement being considered is the ability to reuse event expressions across multiple elements, as many behaviors depend on multiple elements that should share the same behavior.

UI events in Reusable UI Templates

UI events work within Reusable UI Templates. When using events in templates, ensure that any keys referenced in the expression are properly mapped through the template’s input parameters.

Input mapping requirements

For an expression like:

income = ${client.income}
debt = ${client.debt}

if (income && debt) {
    return {
    "client": {
        "ratio": ${client.debt} / ${client.income}
    }
    }  
} else {
    return {}
}

The template must have client.debt and client.income configured as input parameters to receive values from the parent process context.

When designing reusable templates with UI events, document which input parameters are required for the events to function correctly.

Runtime behavior

Execution flow

When a trigger event occurs:

Event triggered

User interaction fires the configured event (e.g., onChange)

Expression evaluated

The SDK evaluates the JavaScript expression synchronously

Local data updated

The returned object merges into the local data store

UI refreshed

Components bound to the updated data re-render automatically

Coexistence with UI actions

UI events and UI actions can be configured on the same component. When both are present:

The UI event expression evaluates first (right before the action)
The UI action executes after the event completes

This allows you to perform local calculations before sending data to the backend.

Local vs server data

Variables updated by UI events remain local to the UI until a submit action is executed. The process engine’s server data store does not receive these updates until data is explicitly submitted.

This means:

Immediate UI updates without server latency
Multiple calculations can be performed before submitting
Server-side data only updates when you trigger a data submission action

UI event expressions are synchronous computations. Avoid complex operations that could block the UI thread.

Best practices

Keep expressions simple

UI events are designed for lightweight transformations. For complex business logic, continue using server-side business rules.

// ✅ Good: Simple calculation
const total = ${cart.subtotal} * 1.1;
return { "cart": { "totalWithTax": total } }

// ❌ Avoid: Complex async operations or heavy computations

Ensure data is available on the page

UI event expressions can only access data that is already configured to be sent from the backend to the frontend. Before using a property in an expression:

Verify the property is bound to a UI component on the current page
Ensure the data is included in the page’s data context
Test with actual data to confirm availability

Handle missing data gracefully

Always account for potentially undefined values:

// ✅ Defensive coding
const income = ${client.income} || 0;
const debt = ${client.debt} || 0;
const ratio = income > 0 ? debt / income : 0;
return {
  "client": {
    "debtRatio": ratio
  }
}

Use meaningful return structures

Return objects should mirror your data model structure:

// ✅ Matches data model hierarchy
return {
  "application": {
    "calculations": {
      "monthlyPayment": payment,
      "totalInterest": interest
    }
  }
}

Test expressions thoroughly

Before deploying, verify your expressions handle:

Valid input values
Empty or null inputs
Edge cases (zero, negative numbers, empty strings)
Different data types

Troubleshooting

Expression not evaluating

Symptoms: Data doesn’t update when interacting with the component Solutions:

Verify the event type matches the component (e.g., onChange for inputs)
Check that process parameter syntax uses ${} correctly
Ensure the expression includes a return statement
Confirm the component has the event properly configured

Property not available error

Symptoms: Expression fails because a referenced property is undefined Solutions:

Ensure the property is configured on the current page to be sent from backend to frontend
Verify the property is bound to a UI component or included in the page’s data context
Only rely on properties that are already being displayed on the screen
Check that nested properties exist in the data model

Return value not applied

Symptoms: Expression runs but data doesn’t change Solutions:

Verify the return object structure matches your data model
Check for JavaScript syntax errors in the expression
Ensure you’re returning a valid object, not undefined or null

Performance issues

Symptoms: UI feels sluggish during interactions Solutions:

Simplify complex expressions
Avoid array operations on large datasets
Move heavy computations to server-side business rules

UI Actions

Configure backend interactions triggered by UI components

Dynamic & Computed Values

Learn about JavaScript expressions for dynamic UI properties

Reusable UI Templates

Create modular UI components with event support

Form Elements

Explore form components that support UI events

Getting Started

Platform overview

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

API reference

​Overview

No server roundtrip

Instant feedback

Simplified logic

Computed expressions

​Key characteristics

​Traditional approach vs UI events

​Configuring UI events

​Event configuration structure

​Platform configuration

​Writing event expressions

​Expression syntax

​Comparison with business rules

​Expression examples

​Supported components and events

​UI events in Reusable UI Templates

​Input mapping requirements

​Runtime behavior

​Execution flow

​Coexistence with UI actions

​Local vs server data

​Best practices

​Keep expressions simple

​Ensure data is available on the page

​Handle missing data gracefully

​Use meaningful return structures

​Test expressions thoroughly

​Troubleshooting

​Expression not evaluating

​Property not available error

​Return value not applied

​Performance issues

​Related resources

UI Actions

Dynamic & Computed Values

Reusable UI Templates

Form Elements

Overview

Key characteristics

Traditional approach vs UI events

Configuring UI events

Event configuration structure

Platform configuration

Writing event expressions

Expression syntax

Comparison with business rules

Expression examples

Supported components and events

UI events in Reusable UI Templates

Input mapping requirements

Runtime behavior

Execution flow

Coexistence with UI actions

Local vs server data

Best practices

Keep expressions simple

Ensure data is available on the page

Handle missing data gracefully

Use meaningful return structures

Test expressions thoroughly

Troubleshooting

Expression not evaluating

Property not available error

Return value not applied

Performance issues

Related resources