Bring Your Own (BYO): Custom Component

The Bring Your Own framework is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript.

Overview

Developers can build and register custom components that integrate seamlessly into the Unqork Designer Platform. These components must be valid Web Components, conform to the UnqorkComponent interface, and expose a model and view using named exports.

To improve security, external URLs cannot be imported into a BYO implementation file. Unqork recommends copying external source code into the implementation JavaScript file.

After registering a custom component, it can be configured and rendered through the Unqork Designer Platform like any native component.

Component Definition

Defining a custom component begins with specifying its key attributes in the manifest.json file. Each entry in the components array outlines a new component that will be available in the Unqork platform.

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

To register a component, define its model and view as named exports in a file called yourComponentNameHere.js. The file name must match the main field specified in the manifest.json, and the export name must match the component type defined in the same file.

export class CustomComponent extends HTMLElement {
  constructor() {
    super()
    this.attachShadow({ mode: 'open' })
  }

  /**
   * This is the only required method to integrate with the Unqork system
   * 
   * @param {*} api The interface to the Unqork Runtime, used for both
   * monitoring state and emitting events
   */
  initialize(api) {
    this.config = api.state.currentState()
    this.api = api;
  }

  /**
   * This is a web component lifecycle method
   * 
   * It's recommended for setting up initial view and events, but not required
   */
  connectedCallback() {
    this.initialView()
  }

  /**
   * Render initial dom structure
   */
  initialView() {
    this.shadowRoot.innerHTML = `
      <h1 id="heading">I'm a custom component</h1>
    `
  }
}

class CustomComponentDefinition {
  color = 'red';
  output;
}

export const MyCustomComponent = {
  model: async () => CustomComponentDefinition,
  view: async () => CustomComponent
}

State

A custom component’s runtime state looks like the following:

{
  "key": "myComponent",
  "type": "byoc",
  "name": "BYOC Component",
  "byo": {
    "componentType": "MyCustomComponent"
  },
  "text": "I'm custom text",
  "color": "red"
}

Updating from v7.22 to v7.24 might cause issues with older custom components. The component settings model is no longer nested under the args property. It's now the top level of the component state. For example, state.color instead of state.args.color.

Interface

All custom components must implement the UnqorkComponent interface:

export interface UnqorkComponent extends HTMLElement {
  initialize: (api: UnqorkAPI) => void;
}

Line 2: initialize(api: UnqorkAPI): void

Calls after the component is added to the DOM. Use this value to subscribe to state changes or dispatch events.

Updating from v7.22 to v7.24 might cause issues with older custom components. The first argument, initialConfig, has been removed. Now, the initial state is retrieved by API. For example, const state = api.state.currentState();.

Events

A component can emit events to communicate with the platform or other components:

this.api.events.emit(new CustomEvent());

To learn more about custom component events, view our BYO: Events article.

Bring Your Own (BYO): Custom Component

Overview

Component Definition

State

Interface

Line 2: initialize(api: UnqorkAPI): void

Events

Resources

Bring Your Own (BYO) Framework Landing Page

Introduction to the Bring Your Own (BYO) Framework

Create a BYO Package

Understanding the manifest.json File

Understanding the BYO Runtime Engine API

Custom Component SDK

Custom Events

Custom Operations

Event Payloads

BYO Implementation Examples

BYO Best Practices

BYO General FAQ