Core Concepts and Data Lifecycle

Last updated 4/05/2026

Overview

The DimensionIQ Widget is an embeddable measurement and drawing analysis engine that integrates into a host application via an iframe or React component.

The host application is responsible for:

• Persisting all data (projects, revisions, drawings, dimensions, etc)
• Responding to widget events via callbacks
• Maintaining data integrity and lifecycle workflows

Core Concepts

Project

A project is the top-level container.

DIQ_Project {
    key, name, code, measurementSystem, notes
}

• Represents a job, estimate, or workspace
• Must contain at least one revision to be usable

Revision

A revision represents a version/state of a project.

DIQ_Revision {
    key, projectKey, number, name, notes
}

Key Requirement:

A project must have an initial revision created immediately after project creation.

Without a revision:

• Drawings cannot be uploaded
• Dimensions cannot be created
• The widget cannot function meaningfully

Drawings and Layouts

Drawings are tied to revisions and contain layouts.

• Drawing revision
• Layouts (pages, sheets, model spaces, etc)

These form the basis for measurement.

Dimension Structure

Hierarchy:

 └── Revision
      ├── Drawings
      │    └── Layouts
      └── Dimension Group Folders
           └── Dimension Group Revisions
                └── Dimensions

Required Lifecycle Flow

Creating a New Project

When the widget triggers:

onProjectNew(project, onResponse)

Host application must:

Step 1 - Create Project

Persist project in database.

Step 2 - Automatically Create Initial Revision

Immediately create:

Revision {
    projectKey: project.key,
    number: 1,
    name: "Initial Revision"
}

Step 3 - Return Success

onResponse({
    ok: true,
    message: "Project and initial revision created"
})

Why This Matters

The widget assumes:

• A project is always revision-enabled
• Revision = working context

Failing to create an initial revision will break:

• Drawing uploads
• Dimension creation
• Grouping logic

Event Callback Responsibilities

The widget is event-driven. The host must implement callbacks as needed.

Project Events

Callback	Responsibility
onProjectNew	Create project and initial revision
onProjectUpdate	Update project metadata
onProjectOpen	Load active project
onProjectClose	Close session

Revision Events

Callback	Responsibility
onRevisionNew	Create additional revision
onRevisionUpdate	Update revision
onRevisionGet	Get revision

Drawing Events

Callback	Responsibility
onDrawingNew	Store drawings and layouts
onDrawingUpdate	Update drawing
onDrawingDelete	Delete drawing
onDrawingNewRevision	Handle drawing versioning

Dimension Events

Callback	Responsibility
onDimensionsNew	Store new dimensions
onDimensionUpdate	Update single dimension
onDimensionsUpdate	Bulk update
onDimensionsDelete	Delete dimensions

Grouping Events

Callback	Responsibility
onDimensionGroupFolderNew	Create folder
onDimensionGroupRevisionNew	Create group
onDimensionGroupRevisionUpdate	Update group
onDimensionGroupRevisionDelete	Delete group

Query/List Events (Read Operations)

These power the UI:

• onListRevisions
• onListDrawings
• onListDrawingLayouts
• onListDimensions
• onListDimensionGroupFolders
• onListDimensionGroupRevisions

Widget Integration Options

Iframe Integration

Use:

DIQWidgetHost

or

DIQWidgetBridge

Communication Model

The widget communicates via

postMessage

:

DIQMessage {
    source,
    direction: "command" | "event" | "response",
    action,
    payload,
    requestID
}

Data Handling Responsibilities

The host application must:

• Persist all entities:
• Projects
• Revisions
• Drawings
• Layouts
• Dimensions

• Maintain relationships between entities
• Ensure referential integrity

Error Handling

All callbacks must return:

DIQ_Result {
    ok: boolean,
    message: string
}

Best Practices

Always:

• Create initial revision on project creation
• Keep revision numbers sequential
• Validate relationships (project -> revision -> drawing)

Avoid:

• Creating projects without revisions
• Deleting active revisions
• Returning partial data in list callbacks

Minimal Example Flow

User creates project:

1. Widget ->
   onProjectNew
2. Host:
   • Create project
   • Create revision #1
3. Host -> success response
4. Widget:
   • Requests revisions via
     onListRevisions
   • Loads working context

DIQWidgetHost vs DIQWidgetBridge

Choose the integration approach that best matches your application structure, use

DIQWidgetHost

for React applications, or

DIQWidgetBridge

for vanilla JavaScript and framework-agnostic integrations.

Feature	DIQWidgetHost	DIQWidgetBridge
Framework	React	Vanilla JS / TS
Usage	JSX Component	Imperative Class
Commands	ref.sendCommand()	bridge.sendCommand()
Cleanup	Automatic	Manual
Status UI	Built-in	Custom
StrictMode Safe	Yes	N/A