Embedded UI: Understanding the EmbeddedModule Interface

The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript.

Overview                                            

The Embedded Module interface provides Creators with methods to interact with an Unqork module in real time. Creators can use the interface to execute actions, send and retrieve data, or respond to events in the module.

Embedded UI is currently in open beta. Please contact your Unqork representative for more details and access.

Understanding the EmbeddedModule Interface

The EmbeddedModule interface consists of the following:                                            

interface EmbeddedModule {
  moduleId: string
  ready(callback: () => void): Promise<void>
  on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void
  send(event: "submission_data" | "operation", data: unknown, context?: any): Promise<void>
  get(data: RuntimeDataType): any
  validate(): Promise<void>
  swapModule(module: AnyModuleDefinition, submissionData?: SubmissionData): Promise<void>
  registerSubmissionHandler(handler: ModuleSubmissionHandler): void
  unregisterSubmissionHandler(): void
  registerValidationHandler(handler: ModuleValidationHandler): void
  unregisterValidationHandler(): void
  removeSubscriptions(): void
  destroy(): Promise<void>
}

Methods of the EmbeddedModule Interface

All examples of module.<method> assume the module is a declared variable assigned to the value of runtime.mountModule. If a different variable name is used, like unqorkModule, then the reference becomes unqorkModule.<method>.

Line 3: ready(callback: () => void): Promise<void>

Registers a callback function to execute when the module is fully initialized and ready for interaction.

Args

• callback: The function to be invoked once the module is ready.

For example:                                            

module.ready(() => {
console.log("The module is ready! You can now interact with it.");
});

Line: 4: on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void

Subscribes to events occurring in the runtime, and responds with a provided callback.

Args

• 'system.submission.saved': Triggered when the module is submitted and saved.

• 'components.myActionBtn.click': Triggered when a component with the key myActionBtn is clicked.

For example:                                          

// Respond to a successful submission
module.on('system.submission.saved', (values) => {
  console.log('Submission saved with values:', values);
});

// Respond to a button click within the module
module.on('components.myActionBtn.click', () => {
  // Trigger an action in your external application.
});

Available Events

Line 5: send(event: "submission_data" | "operation", data: unknown, context?: any): Promise<void>

Executes an action in the module by sending it data or an operation.

Args

• event: The type of action to perform. For example, 'submission_data' or 'operation'.

• data: The payload for the action.

• context: OPTIONAL A context object for the action.

// Send data to a module component
module.send('submission_data', {
  // Keys here should correspond to component keys.
  firstName: 'Alex',
  email: '[email protected]',
});

// or
// Execute an operation to set a component property
module.send('operation', {
  "type": "SET_PROPERTY",
  "options": {
    "targetKey": "firstName",
    "property": "display.hidden",
    "value": false,
  }
})

Line 6: get(data: RuntimeDataType): any

Retrieves the internal state or data of the module at the current time.

Returns: The requested runtime data.

Arg

• data: The type of runtime data to retrieve.

For example:

const currentValues = module.get('runtime_data')

Available Runtime Data Types

Line 7: validate(): Promise<void>

Triggers a full validation of the module. This method does not display validation errors on untouched components.

Returns: A promise that resolves when validation is complete. The resolved value contains the validation results.

For example:

const {isModuleValid, moduleErrors} = await module.validate()

Line 8: registerSubmissionHandler(handler: ModuleSubmissionHandler): void

Replaces the module's default submission behavior with a custom handler. The default behavior  stores the data in a submission collection. When a custom handler is provided, this default action is not performed.

Arg

• handler: A function that receives the module's ID and data to submit. It should return a Promise that resolves to a SubmissionResponse object containing a unique ID, which is used as the submissionId for the last saved submission. The handler can also return undefined if no ID is needed.

ModuleSubmissionHandler type definition:

type ModuleSubmissionHandler = (
  moduleId: string,
  data: Record<string, any>,
) => Promise<undefined | SubmissionResponse>

type SubmissionResponse = {
  id: string
}

JavaScript example:

module.registerSubmissionHandler((moduleId, dataToSubmit) => {
  console.log('Custom handler is processing submission for module:', moduleId);
  // Send data to a custom API here.
})

Line 10: unregisterSubmissionHandler(): void

Removes any previously registered custom submission handler, reverting to the default submission behavior.

For example:

module.unregisterSubmissionHandler()

Line 11: registerValidationHandler(handler: ModuleValidationHandler): void

Registers a custom handler to intercept validation results, letting you customize the user experience.

Arg

• handler: A function that receives the module's ID and validation results.

Handler Return Values:

• No return value: The standard validation and errors work as normal.

• false: Clears all current validation errors for the embedded module.

• Updated results: You can return a modified ModuleValidationResult object to apply custom validation from an external source, like an API.

ModuleValidationHandler type definition:

type ModuleValidationHandler = (moduleId: string, results: ModuleValidationResult) => ModuleValidationResult | false

class ModuleValidationResult {
  isValid?: boolean
  results: Record<string, ValidationResult>
}

class ValidationResult {
  isValid?: boolean | null = null
  errors?: ValidationError[]
}

export class ValidationError {
  type: ValidationRuleTypes
  message?: string
}

JavaScript example:

module.registerValidationHandler((moduleId, results) => {
myApp.showErrors(results);
return results;
});

Line 12: unregisterValidationHandler(): void

Removes any previously registered custom validation handlers, reverting to the default validation behavior.

For example:                                          

module.unregisterValidationHandler()

Line 13: removeSubscriptions(): void

Destroys all event subscriptions that were created by the on() method.

For example:

module.removeSubscriptions()

Line 14: destroy(): Promise<void>

Removes the module and its state from the DOM.

Data does not preserve unless it's stored or submitted beforehand.

For example:

module.destroy();

Resources

Introduction to the Embedded User Interface (UI)

Learn how the Embedded UI feature works and discover frequently asked questions (FAQ).  

How to: Embed Unqork in an External Application

View the methods that enable you to interact with an Unqork module in real time.  

Understand the embedded.js File                                                    

Review the script that embeds the runtime API into an external application web page.

Examples of Embedded UI Modules

Discover examples of embedded single or multi-modules.