Skip to main content

Runner class

📖 Description​

The Runner class is the workhorse of all Tripetto runners. It parses a form definition and turns it into an virtual finite state machine. New form instances can then start and the right events for rendering the UI will invoke while the Runner library executes the state machine for that form. It also handles the data collection (storing the values it receives from the UI) and handles the validation of that data. Form instances can be paused and resumed if desired.

🆕 constructor​

Creates a new Runner instance with the specified runner properties.

Signature​

constructor(properties: IRunnerProperties): Runner

Parameters​

NameTypeOptionalDescription
propertiesIRunnerPropertiesNoSpecifies the runner core properties.

Return value​

Returns a reference to the new Runner instance.

Example​

const runner = new Runner({
  definition: /* Supply your form definition here */,
  mode: "paginated"
});

📌 Statics​

🔧 getInitialStoryline​

Retrieves an initial empty storyline. Some runners use this to initiate a storyline before the runner is actually started.

Signature​

getInitialStoryline<T extends NodeBlock>(mode: "paginated" | "continuous" | "progressive" | "ahead"): IStoryline<T>

Parameters​

NameTypeOptionalDescription
mode"paginated" | "continuous" | "progressive" | "ahead"NoSpecifies the mode of operation of the runner. See the IRunnerProperties interface for more information.

Return value​

Returns a storyline object of type IStoryline.

🗃️ Fields​

🏷️ definition​

Sets or retrieves the form definition.

Type​

IDefinition

🏷️ epilogue​

Retrieves the epilogue of the loaded definition (or undefined if the form does not have an epilogue configured). An epilogue can be used by runners (that support it) to show a closing message when a form is completed.

Type​

IEpilogue | undefined

🏷️ fingerprint​

Retrieves the fingerprint of the form.

Type​

string

tip

More information in the Form fingerprint guide.

🏷️ instance​

Retrieves the active instance or undefined if no form instance is active.

Type​

Instance | undefined

🏷️ isEmpty​

Retrieves if the loaded form definition is an empty form. Useful when you want to render a special message in the UI for indicating an empty form.

Type​

boolean

🏷️ isFinished​

Retrieves if the form is finished.

Type​

boolean

🏷️ isFinishing​

Retrieves if the form is finishing. This is true when the form is in the process of completing, but this process might fail. Check isFinished to determine if the form actually has finished.

Type​

boolean

🏷️ isLoaded​

Retrieves if the form definition is loaded successfully.

Type​

boolean

🏷️ isPaused​

Retrieves if the form is paused.

Type​

boolean

🏷️ isPausing​

Retrieves if the form is pausing. This is true when the form is in the process of being paused, but this process might fail. Check isPaused to determine if the form actually has paused.

Type​

boolean

🏷️ isPreview​

Sets or retrieves if the form is in preview mode. This is a special mode that allows the whole form to be shown by the runner UI (basically ignoring all branch conditions, so all branches are taken and shown). This is useful when building a live preview panel that is shown along with the builder.

Type​

boolean

🏷️ isRunning​

Retrieves if the form is running (a form instance is active).

Type​

boolean

🏷️ isStopped​

Retrieves if the form was stopped.

Type​

boolean

🏷️ isTest​

Sets or retrieves if the form is in test mode. This is a special mode that runs the whole form normally, but without invoking the data submission events when the form completes. This is useful in a live preview setup where users want to test a form, without generating response data.

Type​

boolean

🏷️ isVerbose​

Sets or retrieves the verbose mode of the runner. When verbose mode is activated, it will log more messages to the log and the logger function. This is useful for debugging a form definition.

Type​

boolean

🏷️ l10n​

Retrieves the localization namespace with helper functions for working with translations and locales.

Type​

L10n.Namespace

🏷️ log​

Contains the log of the runner.

Type​

string[]

🏷️ logger​

Sets or retrieves the log function that is invoked when a new message is logged.

Type​

(message: string) => void

Example​

const runner = new Runner({
  definition: /* Supply your form definition here */,
  mode: "paginated"
});

// A simple logger to output log messages to the browser console.
runner.logger = (message) => console.log(message);

🏷️ metrics​

Contains metrics about the virtual finite state machine that is generated for the currently loaded form definition.

Type​

{
  /* Number of states. */
  states: number;

  /* Number of transducers. */
  transducers: number;

  /* Number of branches. */
  branches: number;

  /* Number of conditions. */
  conditions: number;

  /* Number of slots. */
  slots: number;
}

🏷️ mode​

Sets or retrieves the current mode of operation for the form. See the IRunnerProperties interface for more information about the possible modes.

Type​

"paginated" | "continuous" | "progressive" | "ahead"

🏷️ name​

Retrieves the name of the form.

Type​

string

🏷️ namespace​

Retrieves the namespace for the runner. The namespace contains the blocks used in the runner.

Type​

INamespace

🏷️ prologue​

Retrieves the prologue of the loaded definition (or undefined if the form does not have a prologue configured). A prologue can be used by runners (that support it) to show a welcome message before starting the actual form.

Type​

IPrologue | undefined

🏷️ status​

Retrieves the status of the runner. It can be one of the following values:

  • idle: The runner is idle, no form instance is running;
  • empty: The form definition is empty, so the form cannot run;
  • preview: The runner runs in preview mode (see preview for more information);
  • running: An active form instance is running;
  • pausing: The active form instance is pausing;
  • paused: The active form is paused;
  • stopped: The active form is stopped;
  • finishing: The active form has completed and is now finishing;
  • finished: The active form is completed and finished.

Type​

"idle" | "empty" | "preview" | "running" | "pausing" | "paused" | "stopped" | "finishing" | "finished"

🏷️ storyline​

Retrieves the storyline of the active form instance. The storyline contains all sections and nodes that are visible and should render in the UI.

Type​

Storyline | undefined

▶️ Methods​

🔧 destroy​

Destroys the runner instance.

Signature​

destroy(): void

🔧 finish​

Finish the active instance when it is finishable. A form is finishable when all nodes pass their validation and the form has reached the end.

Signature​

finish(): Promise<void> | false

Return value​

Returns a Promise that resolves when the instance was finished or false when the instance is not finishable. When an instance is finishable the submission events will invoke when the form is finished. Those events could contain asynchronous code, for example when form data is sent to a HTTP endpoint. When that operation fails, the promise will reject, and the form instance is kept active. If the operation succeeds, the promise will resolve.

🔧 load​

Loads a form definition.

Signature​

load(definition: IDefinition | string): Errors

Parameters​

NameTypeOptionalDescription
definitionIDefinition | stringNoSpecifies the form definition to load. You can either supply the form definition as an object or as a JSON string.

Return value​

Returns an Errors type with the result of the load operation. Errors.None indicates the operation succeeded.

🔧 pause​

Pauses the runner and returns an ISnapshot object that can be used to restore it later on.

Signature​

pause(customData?: {}, onPause?: (snapshot: ISnapshot, done: (succeeded: boolean) => void) => void): Promise<ISnapshot> | ISnapshot | undefined

Parameters​

NameTypeOptionalDescription
customData{}YesOptional custom data that should be stored in the snapshot.
onPause(snapshot: ISnapshot, done: (succeeded: boolean) => void) => voidYesSpecifies a function that is invoked when the pause is initiated. This function receives the pause snapshot together with a callback function that needs to be invoked to indicate if the pause should be executed or dismissed.

Return value​

When the onPause argument is omitted, this method returns a ISnapshot object or undefined when the snapshot fails. When the onPause argument is specified, this method returns a Promise that resolves or rejects based on the result of the done function called in the onPause function.

info

There is a JSON Schema available for the ISnapshot object (handy for static validation). You can download it here.

Example​

const runner = new Runner({
  definition: /* Supply your form definition here */,
  mode: "paginated"
});

// Example 1: Synchronous pause
const snapshot = runner.pause();

// Example 2: Asynchronous pause
const snapshot = await runner.pause({}, async (snapshot, done) => {
  // Send the snapshot to an endpoint
  const response = await fetch("/example-server", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(snapshot)
  });

  done(response.ok);
});
tip

If you want to retrieve a runner snapshot without actual pausing/stopping it, use the snapshot method.

🔧 reload​

Reloads the runner with the specified definition. During a reload the runner tries to maintain any collected data, making it suitable to use in a live preview setup.

Signature​

reload(definition: IDefinition, onlyRestartWhenRunning: boolean = false): Instance | undefined

Parameters​

NameTypeOptionalDescription
definitionIDefinitionNoSpecifies the definition to load.
onlyRestartWhenRunningbooleanYesSpecifies to only restart the runner if it was running before the reload was requested (default is false).

Return value​

Returns a reference to the new form instance or undefined when no instance was started.

🔧 rerender​

Rerenders the runner for the specified instance.

Signature​

rerender(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceYesReference to the instance.

🔧 restart​

Restarts the runner.

Signature​

restart(preserveData: boolean = false): Instance

Parameters​

NameTypeOptionalDescription
preserveDatabooleanYesSpecifies if the data of an existing running instance should be preserved (default is false).

Return value​

Returns a reference to the new form instance.

🔧 restore​

Restores a runner snapshot. A snapshot is a saved state of a form instance that can be restored later on. To obtain a snapshot you either pause the runner or use snapshot.

Signature​

restore(snapshot: ISnapshot): Instance | undefined

Parameters​

NameTypeOptionalDescription
snapshotISnapshotNoSpecifies the snapshot to restore.

Return value​

Returns a reference to the form instance or undefined if the snapshot data was invalid.

🔧 snapshot​

Takes a snapshot of the current state of the runner without stopping/pausing it. The returned ISnapshot object can be used to restore the runner later on.

Signature​

snapshot(customData?: {}): ISnapshot | undefined

Parameters​

NameTypeOptionalDescription
customData{}YesOptional custom data that should be stored in the snapshot.

Return value​

Returns a ISnapshot object or undefined when the snapshot fails.

info

There is a JSON Schema available for the ISnapshot object (handy for static validation). You can download it here.

tip

The pause method does the same, but that function also stops (pauses) the runner.

🔧 start​

Starts a new form instance. Throws an error if no form definition is loaded.

Signature​

start(snapshot: IInstanceSnapshot, onInitialize?: (instance: Instance) => void): Instance

Parameters​

NameTypeOptionalDescription
snapshotIInstanceSnapshotNoSpecifies the instance snapshot to restore.
onInitialize(instance: instance) => voidYesSpecifies a function that is invoked when the instance is started. Can be used to prefill values.

Return value​

Returns a reference to the form instance.

caution

The IInstanceSnapshot interface is different then the ISnapshot interface. An instance snapshot only contains a single instance, whereas the snapshot interface could contain multiple instances. Use restore to restore an ISnapshot object.

🔧 stencil​

Calculates the form stencil hash for the specified type. The form data stencil is a set of two hashes calculated from the form definition. Those data stencil hashes remain stable as long as the data fields generated when running the form definition remain the same. This is different than the fingerprint hash, which remains stable as long as the structure of the form stays the same.

Signature​

stencil(type?: "exportables" | "actionables"): string

Parameters​

NameTypeOptionalDescription
type"exportables" | "actionables"YesSpecifies the stencil type. It can be one of the following values:
- exportables: Generates the hash for all exportable fields (this is the default type);
- actionables: Generates the hash for all actionable fields.

Return value​

Returns the stencil hash.

tip

More information about the stencil hashes in the Form data stencil guide. More information about exportable vs. actionable data can be found here.

🔧 stepBackward​

Step backward in the active instance.

Signature​

stepBackward(): boolean

Return value​

Returns true if the step succeeded.

info

This is only useful for runners in the paginated or continuous mode. When invoked the runner goes to the previous section.

🔧 stepForward​

Step forward in the active instance.

Signature​

stepForward(): boolean

Return value​

Returns true if the step succeeded.

info

This is only useful for runners in the paginated or continuous mode. When invoked the runner goes to the next section.

🔧 stepToHead​

Step to the head in the history of the active instance. This is the furthest point in the form that has been reached.

Signature​

stepToHead(): boolean

Return value​

Returns true if the step succeeded.

info

This is only useful for runners in the paginated or continuous mode.

🔧 stepToStart​

Step to the start of the active instance (beginning of the form).

Signature​

stepToStart(): boolean

Return value​

Returns true if the step succeeded.

info

This is only useful for runners in the paginated or continuous mode.

🔧 stop​

Stops the currently running form instance.

Signature​

stop(): boolean

Return value​

Returns true when a form instance was active and stopped.

🔧 unload​

Unloads the currently loaded form definition and frees up the used memory.

Signature​

unload(): void

🔒 onInstanceBranchLeave​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a branch is left.

Signature​

onInstanceBranchLeave(context: Context, branch: Branch): void

Parameters​

NameTypeOptionalDescription
contextContextNoReference to the context.
branchBranchNoReference to the branch.

🔒 onInstanceChange​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a change occurred in the form instance. You could override this method and use it to update the UI to reflect this change.

Signature​

onInstanceChange(
  instance: Instance,
  typeOfChange: "started" | "render" | "evaluating" | "validated" | "forward" | "backward" | "progress" | "finishing" | "finished" | "stopped" | "paused" | "mode" | "preview",
  storyline: Storyline | undefined
): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
typeOfChange"started" | "render" | "evaluating" | "validated" | "forward" | "backward" | "progress" | "finishing" | "finished" | "stopped" | "paused" | "mode" | "preview"NoSpecifies the type of change that occurred. It can be one of the following values:
- started: The form instance is started;
- render: The form UI should render;
- evaluating: The form is evaluating;
- validated: The form is validated;
- forward: A step forward is made in the form;
- backward: A step backward is made in the form;
- progress: The progress of the form is changed;
- finishing: The form is finishing;
- finished: The form is completed and finished;
- stopped: The form is stopped;
- paused: The form is paused.
- mode: The mode of the runner is changed;
- preview: The preview mode of the runner is changed.
storylineStoryline | undefinedNoReference to the storyline.

🔒 onInstanceCreate​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a form instance is created.

Signature​

onInstanceCreate(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceData​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the collected data of an instance is changed.

Signature​

onInstanceData(instance: Instance, dataChangeEvent: IDataChangeEvent): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
dataChangeEventIDataChangeEventNoReference to a data change event.

🔒 onInstanceEnd​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when an instance ends. This event is always invoked when an instance is finished, stopped or paused.

Signature​

onInstanceEnd(instance: Instance, type: "finished" | "stopped" | "paused"): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
type"finished" | "stopped" | "paused"NoSpecifies why the instance has ended. It can be one of the following values:
- finished: The instance has finished;
- stopped: The instance was forced to stop;
- paused: The instance was paused.

🔒 onInstanceFinish​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance has finished.

Signature​

onInstanceFinish(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceFinishing​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when an instance is about to finish. The function allows you to perform an action before the form is actually completed (for example, sending the form data to a server). If the action fails, the form remains active, and the user can, for example, try to complete (resubmit) the form again.

Signature​

onInstanceFinishing(
  instance: Instance,
  onFinish: (succeeded: boolean, reference?: string) => void
): boolean

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
onFinish(succeeded: boolean, reference?: string) => voidNoCallback function that is invoked when the finish process ends. It contains two arguments:
- succeeded: Contains whether the form completed successfully or not;
- reference: Optional reference (for example, the server identifier of the form submission).

Return value​

Return true to allow the form instance to finish synchronously or return false to wait for the onFinish callback function to be invoked.

🔒 onInstanceNode​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a node is entered.

Signature​

onInstanceNode(context: Context, node: Node, observer: Await): void

Parameters​

NameTypeOptionalDescription
contextContextNoReference to the context.
nodeNodeNoReference to the node.
observerAwaitNoReference to the await pointer that signals the runner to validate the node. If the mode is set to progressive or ahead this is done automatically.

🔒 onInstancePause​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance is paused.

Signature​

onInstancePause(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceProcessing​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when an instance is processing. This means the runner is currently evaluating conditions and branches.

Signature​

onInstanceProcessing(instance: Instance, processing: boolean): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
processingbooleanNoSpecifies if the instance is processing.

🔒 onInstanceProgress​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the progress with in the form changes.

Signature​

onInstanceProgress(instance: Instance, percentage: number): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
percentagenumberNoContains the progress percentage of the form.

🔒 onInstanceSection​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a section is entered.

Signature​

onInstanceSection(context: Context, section: Section, observer: Await): void

Parameters​

NameTypeOptionalDescription
contextContextNoReference to the context.
sectionSectionNoReference to the section.
observerAwaitNoReference to the await pointer that signals the runner to validate the section and make a step forward. If the mode is set to progressive or ahead this is done automatically.

🔒 onInstanceSectionEvaluating​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a section starts or stops evaluating.

Signature​

onInstanceSectionEvaluating(instance: Instance, section: Section, evaluating: boolean): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
sectionSectionNoReference to the section.
evaluatingbooleanNoSpecifies if the section is evaluating.

🔒 onInstanceSectionLeave​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a section is left.

Signature​

onInstanceSectionLeave(
  instance: Instance,
  direction: "forward" | "backward",
  section: Section
): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
direction"forward" | "backward"NoSpecifies the step direction.
sectionSectionNoReference to the section.

🔒 onInstanceStart​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when a form instance is started.

Signature​

onInstanceStart(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceStep​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance makes a step.

Signature​

onInstanceStep(instance: Instance, direction: "forward" | "backward"): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
direction"forward" | "backward"NoSpecifies the step direction.

🔒 onInstanceStepForward​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when an instance wants to check if it can step forward.

Signature​

onInstanceStepForward(instance: Instance, section: Section): boolean

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
sectionSectionNoReference to the section.

Return value​

Should return true when the runner may step forward or false when the step should reject.

🔒 onInstanceStop​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance is stopped.

Signature​

onInstanceStop(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceUpdate​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance is updated and needs an UI rendering.

Signature​

onInstanceUpdate(instance: Instance): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔒 onInstanceValidated​

Protected method

This is a protected method that you can override to extend its functionality (but never need to call).

Invoked when the instance is validated.

Signature​

onInstanceValidated(
  instance: Instance,
  result: "fail" | "pass",
  type: "initial" | "revalidate"
): void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
result"fail" | "pass"NoSpecifies the validation result.
type"initial" | "revalidate"NoSpecifies the validation type.

📢 Events​

🔔 onChange​

Invoked when a change in an instance occurs.

Signature​

(event: IRunnerChangeEvent) => void

Parameters​

NameTypeOptionalDescription
eventIRunnerChangeEventNoReference to the event object.

🔔 onData​

Invoked when the collected data of a form instance is changed.

Signature​

(instance: Instance, event: IDataChangeEvent) => void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.
eventIDataChangeEventNoReference to the event object.

🔔 onFinish​

Invoked when a form instance finishes.

tip

The collected form data can be extracted from the instance using one of the available export functions.

Signature​

(instance: Instance) => void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.

🔔 onRestart​

Invoked when a form instance is restarted.

Signature​

(instance: Instance) => void

Parameters​

NameTypeOptionalDescription
instanceInstanceNoReference to the instance.