About Nodes and Trees

Nodes

Every tree consists of nodes that are interconnected to each other. Below you can find a list of them with respective color coding.

Template Nodes

The first node you will likely happen to stumble upon is a Template Node. It represents one information byte that is visually displayed to the user. The design of the node is defined by the associated template. A Template Node has several child nodes. Initially, those child nodes are red and we call them Missing Nodes.

Missing Nodes

A missing node can be recognized by its red borders and the red plus sign in the middle. Think of it as a placeholder for any other type of node. By clicking on it you can add another, regular node to take its place to grow your tree. For a tree to be released you must get rid of all missing nodes.

Recurring Nodes

The fundamental structure of any conversational experience built with Zircel is a tree. A tree has a predefined starting point and potentially multiple endpoints. However, often a conversation is not linear but takes turns and jumps. To cover this aspect Zircel introduced the concept of Recurring Nodes.

A Recurring Node is essentially a way for a user to continue his or her conversation at a different place in the tree. You can use it by clicking "pick recurring node" in the node menu of a missing node. Once clicked, you get into the "selection-mode" where some nodes are greyed out and others are pulsating. By picking a pulsating node you establish a link between the missing node and the picked node.

Notice that Recurring Nodes can be recognized by the blue border that encloses them.

Logic Nodes

Yellow is the color of logic. And you can add yellow nodes for even more logic in your (decision-) tree by adding a yellow Logic Node to your tree. Let's say you want to offer different experiences for returning website visitors and new website visitors. You can easily distinguish returning and new visitors in your tree by setting a state key once a user passes a certain node in the conversation/tree. With a logic node, you route a conversation based on a state key. You can learn more about the Logic Editor and how to troubleshoot it below.

Action Nodes

An action node opens up a conversation to the whole internet. By adding an action node to your tree you can build a bridge to any other server in the world wide web to communicate with. You can send or receive state and dynamically route a conversation by using a webhook. Quite soon, you will be able to achieve even more! In the meantime, we have dedicated documentation to learn more about this powerful node.

Component Nodes

A component node lets you write your own web component which integrates seamlessly into your tree. By implementing your own component you have full flexibility while maintaining the benefits of the conversational model. You can learn more about custom components here.

Module Placeholder Nodes

Module Placeholder Nodes are "placeholders for modules". Think of them as nodes that expand during an end user's conversation to make room for the complete module. You can learn more about modules in the next chapter.

Termination Nodes

A Termination Node can be used once a process or conversation has come to an end. It will close the execution of a given subtree.

Modules

When your tree starts to grow, it sooner or later gets to a complexity that is no longer sustainable which makes it hard to manage. In other cases, you realize that some parts of your model appear over and over again at different parts of your tree or even in multiple, different trees simultaneously.

Modules can help in both cases! They build an easy way to encapsulate reusable parts of your model. You can define one on the welcome page under the "Tree" tab. In the Tree Editor, click on a missing node and select "Modules" to chose one.

Connectors

Building modules is no different than building regular trees. However, there is one small difference: While regular trees are not supposed to have missing nodes, modules are. They are called connectors and form the interface between a module and the consuming regular tree.

When developing a module you have to manually set the number of connectors in the side panel of the Tree Editor. This number needs to be reflected by the number of missing nodes you intentionally leave blank.

Logic

A logic node essentially boils down to a simple condition (or if-statement). Based on its outcome (true or false) a users' conversation will take one or the other turn.

Currently, a condition needs to be defined by hand. It consists of logical operators, constants (Strings or Numbers) and state keys. In general, the syntax of a condition is closely related to how you'd write an if-statement in JavaScript (or in any other programming language).

• You can use the same logical operators as in JavaScript: ||, ||, ==, !=, ===, !==, <, <=, >, >=. Further, you can negate literals or do existence checks with a negation !.
• Keywords reserved in JavaScript such as undefined, null or this are not allowed.
• Instead of variables we use state keys that are denoted by a hashtag (e.g. #name)

Sounds complicated? Hopefully, a few examples can help! Let's start with a simple example by checking whether a users' name is Mike.

In the next example we check if a name is neither Mike nor Anna.

You can also work with numerical constants. Notably, in the example below we do not only check whether a user is over 18 we also do an existence check: has the user entered a value for the state key 'age' or is it still undefined?

Last but not least: one of the most common use cases! In the example below we check whether a visitor has visited the conversational website before. #hasVisited is state key of type boolean which is either true or false.

Test State

Even with a sufficient amount of examples conditions can still feel confusing. To help you develop the right conditions for your use case Zircel uses Test State.

Test State is a simulation of how your users' state might look like during an actual conversation. It supports your development and debugging efforts. For example, when writing a logical condition Zircel can evaluate it on the fly with the help of the current Test State.

Notice that you can change and interact with the Test State. Simply click on a value field to edit (as seen in the picture above where the age is being edited). In contrast, if you engage in a conversation in the Preview the Test State updates itself based on your interaction with the tree, which makes it super useful during development.

If you use Zircel as plugin, you can profit from the Test State too. While you are in the development mode (i.e.page.mode = 'development') you also have access to the same, shared Test State.