Embedded User Interface (UI): Vega Runtime API

Estimated Reading Time:  4 minutes

Overview

The Vega Runtime 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. used by Unqork's Embedded User Interface (UI) exposes a few crucial methods for interacting with runtime data and commands. These methods provide an interface to read the current state, respond to changes in that state, and trigger actions in the embedded runtime.

This article assumes you have mounted a module using the mountModule method. What's returned is called an embedded module, which exposes the methods discussed in this article.

TIP  To learn more about mounting a module, view our Embedded User Interface (UI) article.

Embedded Module Methods

Unqork supports various methods to read, write, and listen to data in your embedded module. They also support triggering actions, like running commands and responding to events.

Unqork is working on the concept of multiple modules in a single runtime. Even though the following methods will be supported for individual modules soon, they are currently only supported at the runtime level. In the meantime, it's suggested that you create a new runtime instance for each embedded module. For example, calling makeUnqorkApi for each instance.

TIP  To learn more about calling the makeUnqorkApi, view our Embedded User Interface (UI) article.

Working With Data

Unqork supports various Vega runtime data types and methods for reading, writing, and listening to data in your embedded module.

Data Types

Only submission_data supports reading and writing values. All other runtime data types are read-only.

  • isValid: This value is true or false depending on whether or not the entire module is valid.

  • results: An object containing validation errors by component key.

Reading Data

If you only need to access the data once, use the get method to synchronously retrieve any supported data type.

Copy 
const currentValues = module.get('runtime_data')
const {isValid, results} = module.get('validation_results')

Listening to Data

When you want to monitor values and receive notifications of changes to your embedded module, use the on method. The initial parameter is the same as the get method, but with a suffix of _updated. You also must provide a callback function that is called for the current values, and again when values have changed.

Copy 
module.on('runtime_data_updated', (values) => {
  // Handle value updates here.
})

module.on('validation_results_updated', ({isValid, results}) => {
  // Do something here.
})

Writing Data

When updating data in the embedded module, use the send method.

NOTE  Currently, this method only supports submission_data.

Copy 
module.send('submission_data', {
  // Keys here should correspond to component keys.
  firstName: 'Alex',
  email: 'alex@example.com',
})

Triggering Actions

You can also use methods to trigger actions, like running commands, calculating the validation status, and responding to events.

Running Commands

The send method supports initiating actions or commands using Vega operations. You'll set the string operation as the first parameter and the JSON operation as the second.

Copy 
module.send('operation', {
  "type": "SET_PROPERTY",
  "options": {
    "targetKey": "firstName",
    "property": "display.hidden",
    "value": false,
  }
})

Calculating Validation Status

One of the most commonly used commands is calculating the full validation status of a module. If you use the get(‘validation_results’), only validation statuses that are already evaluated return. So, if the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. has not interacted with a required component, its invalid status is not yet stored. An interaction is necessary to run the validation.

Using the validate method, you can trigger the full validation of the module without displaying errors on untouched components.

Copy 
// This method is asynchronous because you must perform all the validations.
const {isModuleValid, moduleErrors} = await module.validate()

Responding to Events

The on method supports responding to other events in the runtime. Some of the most common examples include:

  • Listening to a module to determine whether it's ready to be interacted with or displayed.

  • Listening to a DOM event that occurs on a specific component. This example requires a prefix of components.{componentKey}, where componentKey is the component's Property ID.

Copy 
// Listen for when the module is ready for interaction/display
module.on('system.module.ready', () => {
  // Hide the loader or notify the end-user.
})

// If you want to listen to a DOM event on a specific component, prefix it with `components.{componentKey}`
module.on('components.myActionBtn.click', () => {
  // Trigger an action in your application.
})

Resources