Zircel Documentation

Prerequisites

In order to use custom components, you'll need to have your conversational website running on your own domain by installing it as a plugin.
Web Components are a standardized web technology. It is advised to learn the basic concepts before carrying on with this documentation. We recommend the introduction written by css-tricks.

Installing a Component

Before you can start writing your own custom components you'll need to let Zircel know about the existence of the web components you create. Simply add a custom component node to you tree to do so and specify the name of your component. At runtime, Zircel will use this information to seamlessly integrate your web component into the conversational model. In the following example we name the custom component "my-component". Further, we define a configuration property "buttonLabel" with the value "Continue" and an exit called "success" (see picture below).

Component Node of the Zircel Tree Editor — Definition of a component node in the Zircel Tree Editor.

Next, you can start writing your own web component. Here's a simplified example:

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

  init(goto, config, page) {
      const button = document.createElement('button')
      button.textContent = config.buttonLabel
      this.shadowRoot.appendChild(button)
      button.addEventListener('click', _ => {
        page.setState({ confirmed: true })
        goto('success')
      })
  }
}

customElements.define('my-component', MyComponent)

The above example is a standard web component. However, there are a handful of details to cover explicitely:

init(goto, config, page): your web component needs a function called "init" which takes 3 arguments explained below.
The first argument goto is a function you have to call whenever you want the conversation to continue i.e. move to the next node in the tree. In the example above, we call goto('success') which takes the user to the exit node which is identified by the "success" label.
config is a key-value object. This object is helpful to keep web components as reusable as possible as you can separate logic from content. In the above example, we use the config object to set the label of a button rendered to the user screen with button.textContent = config.buttonLabel. Notice that we already set the property "config.buttonLabel" in the custom component node to the value "Continue".
The last argument is the whole conversational page (which is a web component on its own). You can use the reference to interact with the overall conversation. Have a look at the Event API to learn more how to interact with it. For example, in the code above we update the internal state and set a boolean state key "confirmation" to true: page.setState({ confirmed: true }).

At this point, we have one question left to be answered: how can the conversational model run your web component? Answer: with one line of code:

page.register('my-component', MyComponent)

You'll need to call the register function before you initialize the plugin. Here's a short overview of how you code could look like:

class MyComponent extends HTMLElement {
  constructor() { ... }
  init(goto, config, page) { ... }
}

customElements.define('my-component', MyComponent)

page.pid = '5891d72c07d37b8c12266e8a'
page.path = '/my-page'
page.register('my-component', MyComponent)
...
page.init()
...

That's it! Your web component should now be executed like any other design template in the execution tree. If your code is not working make sure to check the developer console of your favourite browser. If the second part of the code looks peculiar to you, make sure to read up on how to run your conversational website as a plugin.

Custom Components

Prerequisites

Installing a Component