Bring Your Own (BYO): Custom Component

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 JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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:

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

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

Line 2: initialize(api: UnqorkAPI): void

Calls after the component is added to the DOM The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page.. 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 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.. For example, const state = api.state.currentState();.

Events

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

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

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