IRunner interface

📖 Description

Interface that describes the return type of the useRunner hook.

📃 Type declaration

interface IRunner {
  definition: IDefinition;
  view: "live" | "test" | "preview";
  mode: "paginated" | "continuous" | "progressive" | "ahead" | undefined;
  l10n: L10n.Namespace;Readonly
  instance: Instance | undefined;Readonly
  fingerprint: string;Readonly
  stencil: string;Readonly
  actionables: string;Readonly
  storyline: Storyline | IRunnerSequenceItem[] | undefined;Readonly
  prologue: IPrologue | undefined;Readonly
  epilogue: IEpilogue | undefined;Readonly
  preview: "prologue" | "blocks" | "epilogue" | undefined;Readonly
  status: "empty" | "idle" | "running" | "preview" | "evaluating" | "stopped" | "finishing" | "finished" | "pausing" | "paused" | "error" | "error-outdated" | "error-rejected" | "error-paused";Readonly
  isRunning: boolean;Readonly
  isFinishing: boolean;Readonly
  isEvaluating: boolean;Readonly
  isPausing: boolean;Readonly
  allowStart: boolean;Readonly
  allowRestart: boolean;Readonly
  allowPause: boolean;Readonly
  allowStop: boolean;Readonly
  kickOff: () => void;Function
  start: () => Instance | undefined;Function
  restart: () => void;Function
  reload: (definition: IDefinition) => void;Function
  pause: (
    data?: {},
    pausing?: (
      pSnapshot: ISnapshot,
      done: (result: "succeeded" | "failed" | "canceled") => void,
      item: IRunnerSequenceItem | undefined
    ) => void
  ) => Promise<ISnapshot> | ISnapshot | undefined;Function
  snapshot: (data?: {}) => ISnapshot | undefined;Function
  stop: () => void;Function
  update: () => void;Function
  discard: () => void;Function
  doAction: (type: "stage" | "unstage" | "focus" | "blur", node?: IObservableNode) => void;Function
  doPreview: (data: TRunnerPreviewData) => void;Function
  resetPreview: () => void;Function
}

🖱️ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

🗃️ Properties

🏷️ `actionables`

Retrieves the form stencil hash for the actionable data.

Type

string

tip

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

🏷️ `allowPause`

Retrieves if the runner can be paused.

Type

boolean

🏷️ `allowRestart`

Retrieves if the runner can be restarted.

Type

boolean

🏷️ `allowStart`

Retrieves if the runner can be started.

Type

boolean

🏷️ `allowStop`

Retrieves if the runner can be stopped.

Type

boolean

🏷️ `definition`

Sets or retrieves the current form definition that is running.

Type

IDefinition

🏷️ `epilogue`

Retrieves 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

🏷️ `fingerprint`

Retrieves the fingerprint of the form.

Type

string

tip

More information in the Form fingerprint guide.

🏷️ `instance`

Retrieves the instance of the current running form.

Type

Instance | undefined

🏷️ `isEvaluating`

Retrieves if the runner is evaluating a block or condition.

Type

boolean

🏷️ `isFinishing`

Retrieves if the runner is finishing (response data is being transmitted).

Type

boolean

🏷️ `isPausing`

Retrieves if the runner is pausing (pause data is being transmitted).

Type

boolean

🏷️ `isRunning`

Retrieves if the runner is running.

Type

boolean

🏷️ `l10n`

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

Type

L10n.Namespace

🏷️ `mode`

Sets or retrieves the current mode of operation for the runner. It can be one of the following values:

paginated: Render each section on a separate page (this is the default behavior);
continuous: Render all completed (past) sections and the current (present) section on a page;
progressive: Render all completed (past), current (present) and future sections on a page till the point where one of the sections fails validation;
ahead: Render all completed (past), current (present) and future sections on a page, regardless of the section's validation result.

info

When the runner is in sequence mode, this property returns undefined.

Type

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

🏷️ `preview`

Retrieves the current preview mode of the runner. It can be one of the following values:

prologue: Prologue preview is active;
blocks: Blocks preview is active;
epilogue: Epilogue preview is active.

Type

"prologue" | "blocks" | "epilogue" | undefined

🏷️ `prologue`

Retrieves 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

🏷️ `status`

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

empty: The form is empty (has no blocks);
idle: The runner is idle (ready to start);
running: The runner is running;
preview: The runner is in preview mode;
evaluating: The runner is evaluating a block or condition;
stopped: The runner is stopped;
finishing: The runner is finishing (response data is being transmitted);
finished: The runner has finished;
pausing: The running is pausing (pause data is being transmitted);
paused: The runner has paused;
error: An unknown error occurred when finishing the form;
error-outdated: The form definition is outdated;
error-rejected: The server rejected the response data;
error-paused: An error occurred when pausing the form.

Type

🏷️ `stencil`

Retrieves the form stencil hash for the exportable data.

Type

string

tip

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

🏷️ `storyline`

Retrieves the Storyline instance when the runner is not in sequence mode. Otherwise, it returns an array of sequence items.

caution

This property may be undefined if there is no form running.

Type

storyline | IRunnerSequenceItem[] | undefined

🏷️ `view`

Sets or retrieves the current view mode of the runner. It can be one of the following values:

live: The form is running in normal (production) mode;
test: The form is running in test mode (no response data is submitted);
preview: The form is running in preview mode, which shows all blocks in a single view.

Type

"live" | "test" | "preview"

▶️ Functions

🔧 `discard`

Discards the error state of a runner when the runner status is either error, error-outdated, error-rejected, or error-rejected. It sets the runner status back to running.

info

The status property can be used to generate an error message in the UI when an error occurs. The discard function can then be used to remove/close this error message.

Signature

() => void

🔧 `doAction`

Emits an action to the runner.

Signature

doAction: (
  type: "stage" | "unstage" | "focus" | "blur",
  node?: IObservableNode
) => void;

Parameters

Name	Type	Optional	Description
`type`	"stage" \| "unstage" \| "focus" \| "blur"	No	Specifies the type of action.
`node`	`IObservableNode`	Yes	Reference to the node.

🔧 `doPreview`

Request a preview of the specified element of the form. This function is used in a live preview setup to bring a certain element in the form into view.

Signature

(data: TRunnerPreviewData) => void

Parameters

Name	Type	Optional	Description
`data`	`TRunnerPreviewData`	No	Specifies the preview data.

🔧 `kickOff`

Starts a runner in sequence mode.

Signature

() => void

🔧 `pause`

Pauses a form.

Signature

(
  data?: {},
  pausing?: (
    snapshot: ISnapshot,
    done: (result: "succeeded" | "failed" | "canceled") => void,
    item: IRunnerSequenceItem | undefined
  ) => void
) => Promise<ISnapshot> | ISnapshot | undefined;

Parameters

Name	Type	Optional	Description
`data`	`{}`	No	Optional data to store in the snapshot.
`pausing`	(snapshot: `ISnapshot`, done: (result: "succeeded" \| "failed" \| "canceled") => void, item: `IRunnerSequenceItem` \| undefined) => void	Yes	Optional function that can be used to process the pause data (for example, send it to an endpoint). When this function is supplied, the runner waits until the `done` function (with the result of the pause operation) is invoked.

Return value

Returns the ISnapshot object, a Promise for that object or undefined if the pause operation failed.

🔧 `reload`

Reloads a form definition while trying to keep the data already collected.

Signature

(definition: IDefinition) => void

Parameters

Name	Type	Optional	Description
`definition`	`IDefinition`	No	Specifies the form definition to load.

🔧 `resetPreview`

Resets the preview element.

Signature

() => void

🔧 `restart`

Restarts a runner.

Signature

() => void

🔧 `snapshot`

Creates a snapshot of the form (without pausing it).

Signature

(data?: {}) => ISnapshot | undefined

Parameters

Name	Type	Optional	Description
`data`	`{}`	Yes	Optional data to store in the snapshot.

Return value

Returns the ISnapshot object.

🔧 `start`

Starts a runner.

Signature

() => Instance | undefined

Return value

Returns the Instance of the form or undefined if the form cannot start.

🔧 `stop`

Stops a runner.

Signature

() => void

🔧 `update`

Invokes a runner update.

Signature

() => void

IRunner interface

📖 Description​

📃 Type declaration​

🗃️ Properties​

🏷️ actionables​

Type​

🏷️ allowPause​

Type​

🏷️ allowRestart​

Type​

🏷️ allowStart​

Type​

🏷️ allowStop​

Type​

🏷️ definition​

Type​

🏷️ epilogue​

Type​

🏷️ fingerprint​

Type​

🏷️ instance​

Type​

🏷️ isEvaluating​

Type​

🏷️ isFinishing​

Type​

🏷️ isPausing​

Type​

🏷️ isRunning​

Type​

🏷️ l10n​

Type​

🏷️ mode​

Type​

🏷️ preview​

Type​

🏷️ prologue​

Type​

🏷️ status​

Type​

🏷️ stencil​

Type​

🏷️ storyline​

Type​

🏷️ view​

Type​

▶️ Functions​

🔧 discard​

Signature​

🔧 doAction​

Signature​

Parameters​

🔧 doPreview​

Signature​

Parameters​

🔧 kickOff​

Signature​

🔧 pause​

Signature​

Parameters​

Return value​

🔧 reload​

Signature​

Parameters​

🔧 resetPreview​

Signature​

🔧 restart​

Signature​

🔧 snapshot​

Signature​

Parameters​

Return value​

🔧 start​

Signature​

Return value​

🔧 stop​

Signature​

🔧 update​

Signature​

📖 Description

📃 Type declaration

🗃️ Properties

🏷️ `actionables`

Type

🏷️ `allowPause`

Type

🏷️ `allowRestart`

Type

🏷️ `allowStart`

Type

🏷️ `allowStop`

Type

🏷️ `definition`

Type

🏷️ `epilogue`

Type

🏷️ `fingerprint`

Type

🏷️ `instance`

Type

🏷️ `isEvaluating`

Type

🏷️ `isFinishing`

Type

🏷️ `isPausing`

Type

🏷️ `isRunning`

Type

🏷️ `l10n`

Type

🏷️ `mode`

Type

🏷️ `preview`

Type

🏷️ `prologue`

Type

🏷️ `status`

Type

🏷️ `stencil`

Type

🏷️ `storyline`

Type

🏷️ `view`

Type

▶️ Functions

🔧 `discard`

Signature

🔧 `doAction`

Signature

Parameters

🔧 `doPreview`

Signature

Parameters

🔧 `kickOff`

Signature

🔧 `pause`

Signature

Parameters

Return value

🔧 `reload`

Signature

Parameters

🔧 `resetPreview`

Signature

🔧 `restart`

Signature

🔧 `snapshot`

Signature

Parameters

Return value

🔧 `start`

Signature

Return value

🔧 `stop`

Signature

🔧 `update`

Signature