Bring Your Own (BYO) Component SDK

Overview

Bring Your Own (BYO) Component enables Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. 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:

1
2
3
4
5
6
7
8
9
10
11
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:

1
2
3
4
5
6
7
8
9
10
11
{
    "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.

1
2
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
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:

api.state.set({ value: "new value" })

const state = api.state.currentState()

1
2
3
api.state.state$('value', true).subscribe((value) => {
. // update component based on the new value
})

api.state.updateExternalComponentState(args.dataStoreKey, { value: data })

const componentState = api.state.resolveByKey(args.dataComponentKey)

1
2
3
api.state.resolveByKey$(args.dataComponentKey).subscribe((value) => {
. // update component based on the new value
})

api.events.emit({ name: 'customEvent', payload: { someValue: "value" }})

Resources