IRunnerProps interface
đ Descriptionâ
Properties interface for configuring the useRunner hook.
đ Type declarationâ
interface IRunnerProps { definition: IDefinition; snapshot?: ISnapshot;Optional l10nNamespace?: L10n.Namespace;Optional view?: "live" | "test" | "preview";Optional attachments?: IRunnerAttachments;Optional onReady?: (instance?: Instance) => void;EventOptional onChange?: (instance: Instance) => void;EventOptional onImport?: (instance: Instance) => void;EventOptional onData?: (instance: Instance) => void;EventOptional onAction?: ( type: "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete", definition: { fingerprint: string; name: string; }, block?: { id: string; name: string; alias?: string; } ) => void;EventOptional onSubmit?: ( instance: Instance, language: string, locale: string, namespace: string | undefined ) => Promise<string | undefined> | boolean | void;EventOptional onComplete?: (instance: Instance, id?: string) => void;EventOptional onDestroy?: () => void;EventOptional }
đī¸ Propertiesâ
đˇī¸ attachmentsâ
Specifies the attachments handler for processing file uploads.
Typeâ
đˇī¸ definitionâ
Specifies the form definition to use.
Typeâ
đˇī¸ l10nNamespaceâ
Specifies the l10n namespace to use for translations and locale data.
Typeâ
đˇī¸ snapshotâ
Specifies the snapshot that should be restored.
Typeâ
đˇī¸ viewâ
Sets the initial 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"
đĸ Eventsâ
đ onActionâ
Specifies a function that is invoked when the user performs an action. This is useful when you need to implement a tracking service like Google Analytics, Google Tag Manager, or FaceBook Pixel.
Have a look at the Tracking guide to learn more about this feature.
Signatureâ
(
type: "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete",
definition: {
fingerprint: string;
name: string;
},
block?: {
id: string;
name: string;
alias?: string;
}
) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
type | "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete" | No | Contains the action type. It can be one of the following values: - start: A form is started;- stage: A block gets activated;- unstage: A block gets deactivated;- focus: An input element gains focus;- blur: An input element loses focus;- pause: A form is paused;- complete: A form is completed. |
definition | object | No | Contains information about the form definition. |
block | object | undefined | Yes | Contains information about the blocks. |
đ onChangeâ
Specifies a function that is invoked when there is a change in the runner. This change can be anything from a data update to a UI rendering cycle.
If you only need updates on data changes, use the onData event.
Signatureâ
(instance: Instance) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
đ onCompleteâ
Specifies a function that is invoked when the runner is completed (after the data is submitted).
Signatureâ
(instance: Instance, id?: string) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
id | string | undefined | Yes | Contains an optional identifier or reference returned by the server. |
đ onDataâ
Specifies a function that is invoked when there is a data change.
Signatureâ
(instance: Instance) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
đ onDestroyâ
Specifies a function that is invoked when the component unmounts.
Signatureâ
() => void
đ onImportâ
Specifies a function that is invoked when data can be imported into the instance. To import form data, you need to use one of the Import functions from the Runner library as shown in the Prefilling forms guide.
Have a look at the Prefilling forms guide to learn more about importing data.
Signatureâ
(instance: Instance) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
đ onReadyâ
Specifies a function that is invoked when the runner is ready.
Signatureâ
(instance: Instance | undefined) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | undefined | No | Reference to the runner instance or undefined if no form has started. |
đ onSubmitâ
Specifies a function that is invoked when the runner submits data. This event is the one to use to submit the form data to an endpoint. To retrieve the form data, you need to use one of the Export functions from the Runner library.
This event supports different return types. First of all, you can return a boolean value to indicate if the submission was successful or not. That's only useful for synchronous operations. If you need async operation, you can return a Promise which resolves in case of a successful operation or rejects when the submission fails. The Promise can resolve with an optional string reference.
Signatureâ
(instance: Instance, language: string, locale: string, namespace: string) =>
Promise<string | undefined> | boolean | void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
language | string | No | Contains the language used in the runner (default is en). |
locale | string | No | Contains the locale identifier used in the runner (default is en). |
namespace | string | No | Contains the namespace identifier for the runner. |
Return valueâ
Returns true when the submission succeeded, false if it failed or a Promise that resolves with an optional reference string (in case it succeeds) or rejects (in case of an error).