UI Components can be initialized from templates. There are templates for plain custom elements, Vue.js and Svelte. The IFrame adapter is a special tool that we will skip in this introduction. We’ll use three frameworks in this chapter, any of these frameworks are valid choices. A UI Component can be created with the generate command. You’re asked to choose a template, choose the framework of your liking for this example.

npx cdk generate hello-world

A new folder named hello-world is created in the components folder. This folder contains two files, the source code file and manifest.json. hello-world.js / hello-world.vue / hello-world.svelte contains your components source code. The manifest file is used during runtime. It contains height and width constraints, target constraints and input configuration.

Running your UI Component

The CDK has a simulator built in so you can preview and test your UI Components. You can run the following command in the root of the component workspace to start the simulator.

npx cdk simulate hello-world

By default, the simulator will use mock data. You can keep it running; when you save your file, the component will automatically be reloaded. You can find all details about the simulator in the article Simulator.

Developing

To create your component, update the source code file. While simulating, the file is automatically recompiled on every save, and the simulator will reload it from disk.

Adding an input

Inputs are used so that users can configure your component. This can be text, data sources select menus, or other types, see Component inputs for all details. Let's add a name input. Add the following to the inputs field in manifest.json

{
  "main": "pct-hello-world.min.js",
  "version": "1",
  "sheetSettings": {
    "defaultCols": 6,
    "defaultRows": 6,
    "minCols": 3,
    "minRows": 3
  },
  "inputs": [
    {
      "key": "name",
      "type": "Text",
      "label": "Name",
      "placeholder": "Enter your name"
    }
  ]
}

When you select your component in the simulator, you can enter your name in the properties bar on the right of your screen. Your component won’t do anything with it, we'll need to make your component context aware.

The Component Context

The Component Context is your entry point to the IXON platform from your UI Component. For now we'll only use it to retrieve inputs, but it has more functionality which you can read about in Component Context API.

Update your component to the following

class PctHelloWorld extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    const name = this.context.inputs.name || "world";
    const template = document.createElement("template");
    template.innerHTML = /*html*/ `
      <main>
        <h1>Hello, ${name}!</h1>
      </main>
    `;
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}

customElements.define("pct-hello-world", PctHelloWorld);

<script>
  import { onMount } from "svelte";

  export let context;

  let name = "world";

  onMount(() => {
    if (context.inputs.name) {
      name = context.inputs.name;
    }
  });
</script>

<main>
  <h1>Hello, {name}!</h1>
</main>

<template>
  <main>
    <h1>Hello, {{ name }}!</h1>
  </main>
</template>

<script>
export default {
  name: "hello-world",
  props: ["context"],
  computed: {
    name() {
      return this.context?.inputs?.name || "world";
    },
  },
};
</script>

If you now enter your name in the simulator, it will show your name in the component.

Once your are confident in your code, you are ready to deploy your UI Component.