Introduction

Last updated 20/02/2026

Overview

DimensionIQWidget

is a heavy, event-driven React component responsible for rendering and managing the DimensionIQ measurement experience. The widget does not persist or retrieve data itself. Instead, it delegates all data operations to the host application through a structured callback interface:

Function Signature

<DimensionIQWidget engineURL={'/'} callbacks={callbacks} />

The widget emits lifecycle events and responds to updates from the host response with success or failure of the associated event.

Integration Model

Unlike promise-based APIs,

DimensionIQWidget

uses a response callback pattern.

Each lifecycle event:

1. Is triggered by user interaction.
2. Calls a host-supplied callback.
3. Passes relevant domain data.
4. Provides an
   onResponse
   function.
5. Updates internal state based on the host's response via calling
   onResponse(result)
   .

This ensures that:

• Full host control over persistence
• Support for async workflows
• Support for confirmation dialogs
• Controlled error propagation
• Deterministic engine state updates

Callback Signature Pattern

All lifecycle callbacks follow this general shape:

Function Signature

(eventData, onResponse: (result: DIQ_Result) => void) => void

The host application must call

onResponse

when finished.

Example Project

onProjectNew

Function Signature

onProjectNew: (
    project: DIQ_Project,
    onResponse: (result: DIQ_Result) => void
) => void;

Triggered When

User creates a new project.

Engine Behavior

• Generates an initial
  DIQ_Project
  model
• Passes it to the host
• Updates internal state based on the call via
  onResponse

Host Responsibility

The host may:

• Serialize the project
• Persist to backend
• Prompt the user
• Apply business validation
• Cancel creation

When complete the host must call:

Function Signature

onResponse({ ok: true });

or

Function Signature

onResponse({ ok: false, message:"Project name already exists" });

Important

The widget does not proceed until

onResponse

is called.