Template Design Editor

Hello World - Writing your First Template

To get a first impression of how the Template, Tree, and Node Editor work together, we'll start with a very simple example. Copy the following line into the "HTML" field:

Next, give your template a name by typing "helloworld" into the "Name" input field and click the "Save" button. A small message should appear indicating that saving was successful.

Congrats you have just created your very first design template. You can try it out in the Tree Editor 😊.

Styling your Template

Let's apply some color! Copy the following snippet into the "CSS" field. Ignore all predefined rules at the moment, we'll get to them later.

This will turn "Hello World" from black to red. So, if you are somewhat familiar with CSS you can go ahead and style your future templates however you like 😊. There are no restrictions whatsoever.

However, let's get back to those predefined rules now. Have a look at the following statement:

and replace it with:

The color mess is complete 😉. But where is this wrapper class coming from? It turns out that Zircel wraps all your custom HTML and puts it into a div container with the class name ".wrapper" (that's just something we have to do internally). Now that you are aware of this wrapper you can leverage this information for your benefit and use it in your CSS as we just did in the previous code snippet.

Zircel adds some more classes in certain situations/states. We'll revisit them later.

Text Interpolation

If you played around with the "helloworld" template, you will realize that it is fairly primitive. First of all, you do not always want your node to say "Hello World". You want to define the text for each node individually, right?

Here, text interpolation will come in handy. Replace the HTML of your "helloworld" template with:

Now the preview should display "*text*". The asterisks (*) mark a placeholder that you will be able to overwrite in the Node Editor.

If you save your template and head over to your Tree/Node Editor you should now be able to create multiple "helloworld" nodes with different contents.

Zircel Tags

At this point you are ready to dig into the core of our little template engine: "Zircel Tags". They are super handy. A Zircel Tag looks like a regular HTML tag but starts with "z-" and always needs a special attribute "z-name" (which must be unique). For example:

One can distinguish two types of Zircel Tags: primitive and composite.

Primitive Zircel Tags

Here's a list of primitive Zircel Tags that you can use:

Primitive tags allow Zircel to infuse magic into the regular HTML markup. For example, when you use a "z-img" tag you'll be able to upload your custom picture in the Node Editor. If you use "z-input" or "z-textarea" Zircel will be able to capture user input (e.g. an email address) on your conversational application and use it within the State Machine and, of course, you will see the user input under Analytics (when logged in). Finally, z-buttons are the glue of the (Execution) Tree. They let you define the execution logic of your conversational application. Users mainly navigate your application by clicking button pointing to other tree nodes.

A few things to notice. Primitive Tags...

• need a "z-name" attribute.
• can be self-closing/standalone tags (e.g. <z-button z-name="x"/> is equivalent to <z-button z-name="x"></z-button>)
• are automatically mapped to the native HTML element (e.g. <z-input ../> will be mapped to a native <input ../> node)
• can be styled by writing CSS rules for the mapped native element (see example below).
• can have additional native attributes (e.g. <z-img z-name="im" alt="{{alt}}" />)

Here's an example bringing it all together. Replace your HTML with the follwing:

and your CSS with:

Notice, this looks really ugly. As a little exercise, try to beautify this template with the skills you just learned😊

Once your are happy with the styling: save it and have a look at the template in the Node Editor! Quite cool, right?

Supported z-input types

We currently support the input types text, checkbox, and radio. Other input types tags might work out-of-the-box but are not tested. If you need support for other input types, let us know.

The code snippet below uses the checkbox input type. Both checkboxes and radio-inputs will set the associated state key to "on" when they are checked and no value attribute is provided. The checkbox example below will set the state key to "myvalue" when checked. In case they remain unchecked by the user, no state key value is set.

Omitting z-button tags

Your design templates do not need a "z-button" tag. When omitted, the execution of the tree is progressed automatically after 2 seconds to a single child node. It is good practice to always let the user chose when to progress to the next node (i.e. to use "z-button" tags). However, they are useful when you intend to terminate the execution with the next node.

Composite Zircel Tags

What if you want to have more than one button? Or what if you sometimes want one button, and sometimes 2 or even 3 buttons without creating multiple copies of the same template? You can solve this problem by using composite tags:

Composite tags: z-optional and z-iterable

Here's an example how you can use "z-optional" and "z-iterable":

This snippet will add an optional title (you can toggle it on/off in the Node Editor). Wrapping z-img's in a "z-iterable" tag will also allow you to add one or multiple images to your node. You can choose how many images you want in the Node Editor.

Here is everything you need to know about "z-itearble" and "z-optional":

• They are supposed to have one or multiple child elements in them. You can both use native HTML elements or Primitive Zircel Tags as children.
• Currently, you cannot nest two "z-optional" tags. This doesn't work:
<z-optional z-name="opt"> <z-optional ..>...</optional> </z-optional>
• The same is true for "z-iterable" tags. This doesn't work neither:
<z-iterable z-name="it"> <z-iterable ..>...</iterable> </z-iterable>
• However, you can nest a "z-optional" inside a "z-iterable" or vice versa (only once):
<z-iterable z-name="it"> <z-optional z-name="opt"> {{optionalText}} </optional> <z-button z-name="btn" /> </z-iterable>

Composite tag: z-stackable

The composite tag "z-stackable" is a hybrid of both "z-optional" and "z-iterable". Let's see an example which features all details you need to know:

The following "z-stackable" lets users in the Node Editor compose arbitrary sequences (or stacks) of elements:

The screenshot above the Node Editor shows the "article" stack with four stack-elements. Notice that the sequence "title→paragraph→image→button-wrapper" is not identical to the sequence of tags in the zhtml code snippet above. Further, you can repeatedly use stack-elements for as often as you like.

The following rules apply when using "z-stackable":

• All immediate (first generation) child nodes are supposed to have a "z-name" attribute. The first generation child tags <h1>, <p> and <div> are equipped with an additional "z-name" while regular z-tags are supposed to have a "z-name" anyway.
• All first generation child nodes with the z-name are "stackable" i.e. users can stack them in the Node Editor in an arbitrary order.
• Notice that subsequent child nodes are not required to have a "z-name".
• Text content is not allowed as first generation child node.

Congrats, you are Zircel specialist now 😊 by making it this far in the tutorial.

Styling Revisited

Let's look into some additional styling details you can leverage. Remember those empty CSS styling rules at the beginning? Here's how they are useful:

Template Lifecycle

We have already covered the technical aspects of writing design templates. We have yet to do a bit of housekeeping.

Save as Draft

When experimenting with an unfinished design template, you can save it as a "draft". No checks for validity are performed. A new "draft" is not accessible in the Node Editor. If you save an existing template as "draft", its latest regularly saved version is accessible in the Node Editor.

Save

Before you can use a new/modified design template in the Node Editor, you have to save it in a valid state.

Here are a few notes on keeping your template valid:

• When editing an existing template, deleting Zircel Tags will render the template invalid. However, you can always add more Zircel Tags to extend your templates.
• Renaming "z-name" attributes or interpolation names will render the template invalid.
• You can freely change CSS to keep your layouts up to date. Just don't forget to save 😉.

After saving, the latest version of your template will be accessible in the Node Editor. However, already released applications will not be affected by your latest updates. To deploy design updates, you'll have to "release" again in the Tree Editor.

Delete

Templates that are no longer needed can be deleted. As expected, once a template is deleted it can no longer be selected as a new node in the Tree Editor. If there are any trees that still use the deleted template, the nodes will turn red and the specific trees can no longer be released until all references to the deleted design have been removed. However and most importantly, released trees that comprise a deleted template are not affected by the deletion of templates. They remain functioning as expected.

Gotchas