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.
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
The JSON Schema follows the 2020-12 meta-schema.
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 byblocks
. 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);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).
π 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 }
ποΈ 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β
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β
π·οΈ 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.