Embedded UI: Understanding the EmbeddedModule Interface

Overview

The Embedded Module interface provides Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. with methods In JavaScript, a method is a function that is associated with an object. It is essentially a property of an object whose value is a function. Methods define actions or operations that can be performed on the object they belong to. 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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: 'alex@example.com',
});

// 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 APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services..

ModuleValidationHandler type definition:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page..

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

For example:

module.destroy();

Resources