Skip to main content

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" | 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.
info

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

Type​

"paginated" | "continuous" | "progressive" | 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​

"empty" | "idle" | "running" | "preview" | "evaluating" | "stopped" | "finishing" | "finished" | "pausing" | "paused" | "error" | "error-outdated" | "error-rejected" | "error-paused"


🏷ī¸ 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​

NameTypeOptionalDescription
type"stage" | "unstage" | "focus" | "blur"NoSpecifies the type of action.
nodeIObservableNodeYesReference 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​

NameTypeOptionalDescription
dataTRunnerPreviewDataNoSpecifies 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​

NameTypeOptionalDescription
data{}NoOptional data to store in the snapshot.
pausing(snapshot: ISnapshot, done: (result: "succeeded" | "failed" | "canceled") => void, item: IRunnerSequenceItem | undefined) => voidYesOptional 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​

NameTypeOptionalDescription
definitionIDefinitionNoSpecifies 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​

NameTypeOptionalDescription
data{}YesOptional 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