Overview

The Bring Your Own (BYO) Component SDK enables Creators to create new components or configure existing custom components using Unqork's External Component V1 SDK (Software Development Kit).

This feature is intended for Unqork configurators who have a strong understanding of the Unqork Designer Platform.

External Component SDK Design Principles

The External Component SDK is designed as a guideline for Creators to create their own components. The SDK supports the following design principles:

Minimal Surface Area: Expose only essential interfaces to prevent unintended modifications.
Encapsulation: Protect internal state and logic from direct access.
Extensibility: Provide a structured way to introduce new components.
Security & Stability: Ensure external plugins cannot compromise the core system.

Core Architecture of a Web Component

To register and render third-party components in Unqork, it must be a valid web component as defined by MDM Web Docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components.

Here is an example of a basic web component:

export class CustomComponent extends HTMLElement {
  initialize(config, api) {
    /* Insert Component Configuration Logic Here */
  }

  connectedCallback() {
    this.innerHTML = `<h1 id="heading">I'm custom component</h1>`
  }
}

export default CustomComponent

This web component is the default export from a module and uses the initialize method to interact with the Unqork runtime.

Configuring the initalize Method for Custom Unqork Components

The initialize method enables the Web Component to be rendered in Unqork Express View. Two parameters are required for the method: config and api.

Using the config Parameter

The config parameter provides the initial configuration for a component.

The example below contains a component's properties that can be referenced in the config parameter:

{
    "key": "myComponent",
    "type": "byoc",
    "name": "jm-byoc-component-tiiny",
    "url": "https://palbyo.tiiny.site/palBYOL.js",
    "args": {
        "text": "textfieldA",
        "color": "textFieldColor" // These are propertyNames of components.
    },
    "signature": "",
}

To view more examples of config parameter implementation, view our BYO 7.22 Implementation Examples and BYO 7.24 Implementation Examples articles.

Line 6: args

The most important information is the args object containing Creator-defined props with static values in the Unqork Designer Platform. The args are defined by the Creator in the Custom Assets Admin screen for a BYO component. This Admin screen stores the value of what's mapped in the configuration to your component. Doing so helps customize a component depending on the module or use case.

For example, you can change text color for a component (create textColor) or specify a component key that stores data to display a table (create dataComponentKey):

config.args.textColor 
config.args.dataComponentKey

Using the api Parameter

Unqork provides the api service to expose Unqork features. In the example below, the state object displays multiple methods to manipulate a custom component:

interface UnqorkAPI {
  state: {
    set(state: ComponentState) => void
    currentState() => ComponentState
    state$(path: string, includeInitialValue: boolean) => Observable<ComponentState>
    updateExternalComponentState(key: string, update: Partial<ComponentState>) => void
    resolveByKey(key: string) => ComponentState
    resolveByKey$(key: string) => Observable<ComponentState>
  },
  events: {
    emit(event: Event) => void
  }
}

To view more examples of api parameter implementation, view our BYO 7.22 Implementation Examples and BYO 7.24 Implementation Examples articles.

In the above example, each method performs a different function:

Line	Method	Description	Example
3	set(state: ComponentState) => void	Updates the state of the BYO component. This can be a partial object.	`api.state.set({ value: "new value" })`
4	currentState() => ComponentState	Gets the current state of the BYO component	`const state = api.state.currentState()`
5	state$(path: string, includeInitialValue: boolean) => Observable<ComponentState>	Gets a stream of state updates, you can specify if you want to receive the initial value	`1 2 3 api.state.state$('value', true).subscribe((value) => { . // update component based on the new value })`
6	updateExternalComponentState(key: string, update: Partial<ComponentState>) => void	Updates the state of any component in a module with a partial object	`api.state.updateExternalComponentState(args.dataStoreKey, { value: data })`
7	resolveByKey(key: string) => ComponentState	Gets the current state of any component in the module	`const componentState = api.state.resolveByKey(args.dataComponentKey)`
8	resolveByKey$(key: string) => Observable<ComponentState>	Gets the stream of state updates of any component in the module	`api.state.resolveByKey$(args.dataComponentKey).subscribe((value) => { . // update component based on the new value })`
11	emit(event: Event) => void	Dispatches an event from the BYO component, which can be configured in the Unqork Designer Platform for defining operations that should execute based on it.	`api.events.emit({ name: 'customEvent', payload: { someValue: "value" }})`

Resources

Bring Your Own (BYO) Framework Landing Page

Find all the resources needed to build your own components here.

Introduction to the Bring Your Own (BYO) Framework

Get started building your own custom assets, including components, events, and operations.

Create a BYO Package

Discover the structure and content of a BYO Package

Understanding the manifest.json File

Learn about the file's specification, component and event definitions.

Understanding the BYO Runtime Engine API

Discover the interface between your custom BYO components and the Unqork platform.

Custom Component

Understand the state, interface, and events of a custom component.

Custom Events

Learn more about creating custom events for use in the Operations Builder.

Custom Operations

Learn more about creating custom operations for use in the Operations Builder..

Event Payloads

Learn more about viewing and using event payloads with the Operations Builder.

BYO Implementation Examples

Discover examples of component implementation using the Unqork Designer Platform.

BYO Best Practices

Learn about best practices for implementing and using BYO assets.

BYO General FAQ

Learn about the Bring Your Own Framework and discover frequently asked questions.