Bring Your Own (BYO): Custom Operations

Overview

The BYO framework enables developers to create custom operations that integrate seamlessly with the Unqork Designer Platform. After defining and registering a custom operation, it functions as a native operation that can be used throughout the platform.

Discover how Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. use operations in the Introduction to the Operations Builder article.

To improve security, external URLs cannot be imported into a BYO implementation file. Unqork recommends copying external source code into the implementation JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. file.

Operation Definition

Define a custom operation's key attributes in the manifest.json file. Each entry in the root-level or component-level events array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. (components → operations) defines an operation available in the Unqork Designer Platform.

Learn more about the operation definition in our BYO: Understanding the manifest.json File article.

A component can execute custom operations through configuration in the Operations Builder. This enables Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. to execute custom JavaScript functions as operations, performing complex logic, implementing interactions, or changing behavior with a BYO component.

Define each operation as a named export in your main JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. file. The export name must match the type value specified in the manifest.json file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Pseudo Code for an operation

class Operation {
  // ...
}

class OperationHandler {
  // ...
}

// If the operation handler does not return a result. This can be omitted.
class OperationContext {
  // ...
}

// Export for the operation
export const operationsOnly = {
  model: async () => Operation,
  handler: async () => OperationHandler,
  contextModel: async () => OperationContext, // If the operation handler does not return a result. This can be omitted.
}

Line 7 : OperationHandler

The operation handler must have an execute method. When the operation runs, this method is called with the following arguments:

• operation: The operation configuration.

• api: The Operation 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. that lets the operation read or write component state, and emit events.

Line 12: OperationContext

The operation API consists of the following methods, state, and events.

Method: state

• resolveByKey(targetingKey: string): Resolves a targeting string into the state for the targeted component. It locates only one component.

• set(key: string, update: Partial<ComponentState>): Sets the component state as identified by a unique key.

• get(key: string): Retrieves the component state as identified by a unique key.

Method: events

• emit(event: Event): Emits a custom event.