Introduction to Extensions

The Extensions feature is currently in open beta. Please contact your Unqork representative for more details and access.

Vega (v2.0) Extensions enable Creators to build custom functionality inside the Module Builder. Extensions are modules that perform Creator-customized actions to a module that’s currently being edited on the Module Builder’s canvas. Like standard modules, extensions can perform complex logic, connect to APIs, or interact directly with the UDesigner Module Builder.

Examples of extensions that Creators can build include:

• Retrieve, modify, and update component JSON data. For example, mass formatting of Property IDs.

• Implement an API that can interact with module component data.

• Check for component best practices. For example, verifying all components are set to Manual instead of Watch.

Unqork environments can have any number of extensions, and extensions are available to all applications and modules in the environment.

The Extensions feature is intended for developers who have a strong understanding of the Unqork Designer Platform, Operations Builder, and Vega (v2.0) Runtime.

How Extensions Work

Extensions operate in an isolated Vega (v2.0) runtime inside the UDesigner Module Builder. This runtime acts as a secure container, letting an extension interact with the module currently being edited. An extension can also function as a standalone tool if no interaction with the current module is required. Additionally, Creators should note the extension's startup behavior: whenever an extension is loaded or reloaded, any Initializer component configured to trigger on New Submission executes automatically.

Creators can learn how to use extensions in our Module Extensions Drawer article.

Create and Size an Extension Module

Creators can create or convert a module into an extension module using tags. Tags are assigned during the creation of a new module or by using the Settings menu in the Module Builder.

The extension Tag

The extension tag converts the current module to an extension module. Extension modules display in the extensions drawer for all Creators in the environment.

RBAC (role-based access control) for extensions is not supported at this time.

Extension Sizing Tags

Creators can control the size of an extension’s modal window by adding a size tag to the module. For example, to create a medium-sized extension modal, you would assign the module the extension and size:-medium tags.

The available size options include:

• size:-small

• size:-medium

• size:-large

• size:-xlarge

Converting a Module to an Extension in the Module Builder

While Creators can convert any module into an extension using the extension tag. Unqork recommends using the Extension Layout Starter module for configuring new extensions. This module includes the minimum components required to create a functioning extension.

To convert an existing module to an extension module:

1. In the Module Builder, click the (ellipsis) button.

2. Click Module Settings.

3. Scroll down to the Tags field.

4. Click the Tags field, enter or select extension.

5. Click on the Tags field again, enter a size tag using the Sizing an Extension list. For example: size:-medium.

6. Click Save & Close.
   The module now functions as an extension and displays in the Extension drawer.

How Extensions Interact With the Module Builder

When an interaction with the Module Builder is required, an extension emits an EXTENSION_EVENT. While this event type is generic, its payload must specify one of the predefined actions that UDesigner can perform. View a list of predefined actions in the Events and Keywords Reference Lists section.

Learn more about events in our Introduction to Operations Builder article.

Emitting the Extension Event

To trigger an action, emit an EXTENSION_EVENT using the Events and Operations Builder or a logic component like an Initializer component.

Let’s look at the structure of a Vega (v2.0) EMIT_EVENT operation:

  {
    "type": "EMIT_EVENT",
    "options": {
      "event": "EXTENSION_EVENT",
      "payload": {
        "event": "EXTENSION_READY_FOR_COMPONENTS",
        "includeOperationContext": true
      }
    }
 }

1. The operation type is EMIT_EVENT.

2. Inside the options object, the event property is set to the string EXTENSION_EVENT. This tells the UDesigner platform that the event is intended for the extension.

3. The payload object within options contains its own event property. Set this to the name of the specific action you want to run.

   View a list of possible actions in the Extension Events Reference List section.

4. The payload object should also include includeOperationContext: true when your extension is sending data to UDesigner or when using the postEventTriggerKey pattern.

Using the GET_PROPERTY Operation

The GET_PROPERTY operation is a crucial part of the Extension toolkit when sending data or defining post-event triggers. It retrieves a value from a component and adds that data to the operation context.

Let’s look at the structure of a Vega (v2.0) GET_PROPERTY operation:

  {
    "name": "dataOut",
    "type": "GET_PROPERTY",
    "options": {
      "targetKey": ["postEventTriggerKey"],
      "property": "value"
    }
  }

1. The operation type is GET_PROPERTY.

2. Inside the options object, the targetKey accepts an array of Property IDs. This enables the retrieval of values from multiple components in a single operation. For example, targetKey: ["componentsOut", "postEventTriggerKey"].

The operation’s purpose is to act as temporary storage that exists for the duration of a single execution of a chain of operations. By adding data to this context, you make it available for any subsequent operations in the same chain. This is required for sending data to UDesigner, and for using the postEventTriggerKey pattern.

Handling Extension Event Timing and Post-Event Triggers

Sometimes, you need to ensure that logic runs only after an extension event has fully completed and all related data is available. There are two primary methods for handling this process:

The Watcher Pattern

You can configure a logic component, like an Initializer component, that watches the componentsIn Hidden component field. That way, the logic component triggers only when the componentsIn field changes. Doing so guarantees that extension module logic runs after the data is retrieved.

The postEventTriggerKey Pattern

A more direct method is to use the postEventTriggerKey feature, which lets you specify a component that UDesigner will execute automatically after the event logic completes.

To use the postEventTriggerKey pattern:

1. Create a Hidden component in your extension module with the Property ID of postEventTriggerKey.

2. In the Default Value field, enter the Property ID of the component you want to trigger after the event completes. For example, the Property ID of an Initializer or Calculator component.

3. In the operation logic that emits the event, use a GET_PROPERTY operation to load the value of postEventTriggerKey into the operation context before the EMIT_EVENT operation. For example:

   [
     {
       "name": "dataOut",
       "type": "GET_PROPERTY",
       "options": {
         "targetKey": ["postEventTriggerKey"],
         "property": "value"
       }
     },
     {
       "type": "EMIT_EVENT",
       "options": {
         "event": "EXTENSION_EVENT",
         "payload": {
           "event": "EXTENSION_READY_FOR_COMPONENTS_FLAT",
           "includeOperationContext": true
         }
       }
     }
   ]

4. You must also set includeOperationContext to true in the event’s payload, so UDesigner can process the post-event trigger.

This pattern works for all extension events except EXTENSION_READY_TO_CLOSE.

Data Flow

For the extension's data features to work, the necessary data-handling components must already exist in your extension module. These components use specific, reserved Property IDs.

• Receiving Data: When you request components from the canvas, UDesigner places the component JSON data into a Hidden component with the Property ID of componentsIn.

• Sending Data: When you want to update or replace components on the canvas, you must place your new component JSON data into a Hidden component with the Property ID of componentsOut before emitting the event.

• Displaying a Toast: To show a toast notification, you must place the message string in a component with the Property ID of toastContent.

View the Keyword List in the section below for more details on reserved keywords.

Events and Keywords Reference Lists

Click on the tabs below to learn more about the Extension feature’s specific Events, Operations, and Property IDs:

Styling an Extension

Unqork provides an Extension Starter Kit Template to help apply a consistent look and feel that matches the UDesigner platform. Creators can enhance this layout using the provided Extensions Design System module.

Getting Started with Starter Kits

The Extension Starter Kit Template can be found on the Unqork Marketplace. This pack includes three extension modules to get you started:

• Extension Layout Starter: This extension provides the standard layout for an extension, which has a content area and an action section.

• Extensions Design System: This extension provides you with the design tokens, or custom classes for the extension’s design and layout.

• Extension Interaction Examples: This extension showcases how all the different extension events and interactions work in practice.

You can run these as extensions to see what the design tokens do visually, and you can also look at their configuration to see how to achieve the intended layout.

Layout and Spacing

Extension layouts are typically built with Field Group components, and the custom class field is set to a specific design token. Nesting Field Groups with the correct custom classes defines layout and spacing.

A key part of the layout is the actions area. While users can always exit the extension by clicking the X button in the header, it is a best practice to also include a Close or Finish button in your defined actions. You can implement this by adding a Button component that triggers the EXTENSION_READY_TO_CLOSE event.

Styling Limitations

At this point, using your own custom stylesheet in an extension is not supported. This limitation ensures all extensions fit seamlessly in the look and feel of UDesigner. For text styling, like changing text size for headers, the recommended approach is to use an HTML Element component and standard header tags. For example, <h1>, <h2>.

Discover how to install and use the Extension Starter Kit Template in our Marketplace: Extension Starter Kit article.