Skip to main content

Tripetto form definition

📖 Description​

The IDefinition interface defines a Tripetto form. This so-called form definition contains the complete structure of a form and also holds some meta-information about the form, like the name and language of it. It is the output of the builder and can be directly supplied to a form runner (which turns it into a usable form). The interface is JSON compatible and can be easily converted to a JSON string with JSON.stringify(). A JSON Schema is available for validation and reference.

caution

The form definition interface IDefinition is included in both the Tripetto Builder and Tripetto Runner Foundation packages. The interface declaration in those packages is identical. The reason the interface is included in both packages is to avoid importing the Tripetto Builder package into a project that uses the Tripetto Runner Foundation package or vice versa.

So pay attention when importing this interface to avoid bundle bloat. For projects related to the builder, import it from the Tripetto Builder package: import { IDefinition } from "tripetto". For projects related to runners, import it form the Tripetto Runner Foundation package: import { IDefinition } from "tripetto-runner-foundation".

📜 JSON Schema​

📥 Download JSON Schema

info

The JSON Schema follows the 2020-12 meta-schema.

tip

Read the Validating forms guide guide to learn how to implement static validation using the JSON Schema.

🧐 Entities​

To better understand the structure of a form definition, we need to familiarize ourselves with the following entities (see the diagram below for an overview):

  • Nodes: A form consists of form elements we call nodes. These nodes will usually be the form input controls, such as a text input control, dropdown control, etc. In Tripetto, those input controls are defined by blocks. Each node can contain one block (if a node doesn't have a block, it has no functionality other than supplying static text to the runner);

    • Blocks: Gives a node a certain functionality (for example, a text input field);
    • Slots: Serve as the data transporters for the form. They are generated by the block attached to the node;

  • Clusters: One or more nodes can be placed in a so-called cluster. Generally speaking, a cluster will render as a page or view (based on the type of runner). Clusters are also known as sections in the builder UI;

  • Branches: One or more clusters can form a branch. A branch can be conditional, meaning it will only be taken in certain circumstances, namely when the conditions of the branch are valid. These conditions can be defined with the builder and determine if a branch is taken (effectively displaying the clusters and nodes it contains) or just skipped;

  • Conditions: A branch can contain one or more conditions, which are used to direct flow into the pertaining branch. Only branches with matching condition(s) will be taken/displayed. Just like with nodes, the actual behavior of a condition is determined by the condition block that is attached to the condition.

    • Blocks: Condition blocks are attached to a condition and provide the actual behavior to the condition.

The clusters are the starting point of each form, so you will find a clusters property in the IDefinition interface. A form without any clusters is considered empty. Clusters are recursive data structures where the child branches of a cluster can, in turn, contain new clusters, as shown in the diagram below.

📐 Diagram​

This diagram shows the basic form lifecycle. A form starts, and the clusters in the root of that form are shown. Clusters can have branches with conditions. The branches that have matching conditions are taken. Branches, in turn, can have more clusters, and those clusters can have nested branches where this process repeats itself (recursive model).

Form definition diagram

📃 Type declaration​

interface IDefinition {
  builder: {
    name: string;
    version: string;
  };Readonly
  name?: string;ReadonlyOptional
  description?: string;ReadonlyOptional
  keywords?: string[];ReadonlyOptional
  language?: string;ReadonlyOptional
  prologue?: IPrologue;ReadonlyOptional
  clusters: ICluster[];Readonly
  epilogue?: IEpilogue;ReadonlyOptional
}
🖱️ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

🗃️ Properties​

🏷️ builder​

Contains meta-information about the builder that last saved the form definition.

Type​

{
  /* Contains the name of the builder. */
  name: string;

  /* Contains the version number of the builder. */
  version: string;
}

🏷️ clusters ♾️​

Contains the clusters of the form. These clusters (also referred to as sections in the builder UI) contain the nodes and branches of the form. This is a recursive data structure where the branches can, in turn, contain new clusters.

Type​

ICluster[]

info

This property is where the form definition gets its recursive behavior.

🏷️ description​

Contains an optional description for the form.

Type​

string

🏷️ epilogue​

Contains the optional epilogue for the form. This epilogue can be used by runners (that support it) to show a closing message when the form is completed.

Type​

IEpilogue

🏷️ keywords​

Contains optional keywords for the form.

Type​

string[]

🏷️ language​

Contains the language of the form using the ISO 639-1 standard language codes.

Type​

string

🏷️ name​

Contains the name of the form.

Type​

string

🏷️ prologue​

Contains the optional prologue for the form. This prologue can be used by runners (that support it) to show a welcome message before starting the actual form.

Type​

IPrologue