IChatProps interface
đ Descriptionâ
Properties interface for the ChatRunner React component.
đ Type declarationâ
interface IChatProps { definition?: IDefinition | Promise<IDefinition | undefined>;Optional snapshot?: ISnapshot | Promise<ISnapshot | undefined>;Optional styles?: IChatStyles | Promise<IChatStyles | undefined>;Optional l10n?: IL10n | Promise<IL10n | undefined>;Optional view?: "live" | "test" | "preview";Optional display?: "inline" | "button" | "page";Optional controller?: [IChatController | undefined];Optional className?: string;Optional customStyle?: CSSProperties;Optional customCSS?: string;Optional attachments?: IRunnerAttachments;Optional l10nNamespace?: L10n.Namespace;Optional onL10n?: (l10n: IL10n) => Promise<void>;EventOptional onReady?: (instance: Instance | undefined) => void;EventOptional onTouch?: () => void;EventOptional onAction?: ( type: "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete", definition: { fingerprint: string; name: string; }, block?: { id: string; name: string; } ) => void;EventOptional onImport?: (instance: Instance) => void;EventOptional onChange?: (instance: Instance) => void;EventOptional onData?: (instance: Instance) => void;EventOptional onPause?: { recipe: "email"; onPause: ( emailAddress: string, snapshot: ISnapshot, language: string, locale: string, namespace: string ) => Promise<void> | boolean | void; } | ((snapshot: ISnapshot, language: string, locale: string, namespace: string) => Promise<void> | boolean | void);EventOptional onSubmit?: (instance: Instance, language: string, locale: string, namespace: string) => Promise<string | undefined> | boolean | void;EventOptional onComplete?: (instance: Instance, id?: string) => void;EventOptional onReload?: () => IDefinition | Promise<IDefinition>;EventOptional onEdit?: (type: "prologue" | "epilogue" | "styles" | "l10n" | "block", id?: string) => void;EventOptional onDestroy?: () => void;EventOptional }
đī¸ Propertiesâ
đˇī¸ attachmentsâ
Specifies the attachments handler used by blocks that support file uploads. If your form does not need file upload support, you can omit this property.
Typeâ
If your form uses file uploads and no attachments handler is defined, the uploaded files are included in the dataset using Base64 encoding.
Have a look at the Handling file uploads guide to learn how to use this feature.
đˇī¸ classNameâ
Specifies a custom class name for the HTML element that holds the runner.
Typeâ
string
Have a look at the Style forms guide to learn more about this feature.
đˇī¸ controllerâ
Property to receive a controller reference to the runner. This controller reference can be used to perform actions (like start, stop, pause) and retrieve status information from the runner.
Typeâ
[IChatController | undefined]
Exampleâ
import { ChatRunner, IChatController } from "tripetto-runner-chat";
import ReactDOM from "react-dom";
const controller: [IChatController | undefined] = [undefined];
ReactDOM.render(
<>
<ChatRunner
definition={/* Supply your form definition here */}
controller={controller}
/>
<input type="button" value="Pause" onClick={() => controller[0].pause()}
</>,
document.getElementById("root")
);
Have a look at the Controlling the runner guide to learn more about this feature.
đˇī¸ customCSSâ
Specifies custom CSS rules for blocks used in the runner. Multiple CSS rules can be separated with a new line and nesting within CSS rules is supported. Each block is referenced by its block identifier (for the stock blocks, this identifier is always prefixed with tripetto-block- followed by the lowercase name of the block).
Typeâ
string
Have a look at the Style forms guide to learn more about this feature.
đˇī¸ customStyleâ
Specifies the inline style for the HTML element that holds the runner.
Typeâ
CSSProperties
Have a look at the Style forms guide to learn more about this feature.
đˇī¸ definitionâ
Specifies the definition to run. This property also accepts a Promise. That's useful when you want to load the definition dynamically from an external source.
Typeâ
IDefinition | Promise<IDefinition | undefined>
đˇī¸ displayâ
Specifies the display mode of the runner. It can be one of the following values:
inline: Chat content shown inline with other page content (this is the default mode);button: Chat window is behind a chat button (displayed in the bottom right corner of the page) and shown when the button is clicked;page: Chat uses the whole page (viewport).
Typeâ
"inline" | "button" | "page"
Have a look at the Display guide to learn more about the runner display modes.
đˇī¸ l10nâ
Specifies the localization (locale and translation) information. This property also accepts a Promise. That's useful when you want to load the l10n data dynamically from an external source.
Typeâ
IL10n | Promise<IL10n | undefined>
Have a look at the Localization guide for more information about locales and translations.
đˇī¸ l10nNamespaceâ
Specifies the l10n namespace to use. This namespace contains the locale data and translations for the runner.
Typeâ
Exampleâ
import { L10n } from "tripetto-runner-foundation";
import { namespace } from "tripetto-runner-chat";
// Create a new l10n namespace for the runner
const l10nNamespace = L10n.Namespace.create(namespace);
// Do stuff with it, like loading translations
l10nNamespace.load(/* Translation data here */);
// Use the gettext functions to retrieve translations
l10nNamespace._("Text to be translated");
l10nNamespace._n("1 car", "%1 cars", 10);
// Then you can use it in the component
<ChatRunner
definition={/* Supply your form definition here */}
l10nNamespace={l10nNamespace}
/>
đˇī¸ snapshotâ
Specifies the snapshot that should be restored. This property also accepts a Promise. That's useful when you want to load the snapshot dynamically from an external source.
Typeâ
ISnapshot | Promise<ISnapshot | undefined>
Have a look at the Pause and resume guide to learn more about pausing and resuming.
đˇī¸ stylesâ
Specifies the styles (colors, font, size, etc.) for the runner. This property also accepts a Promise. That's useful when you want to load the styles dynamically from an external source.
Typeâ
IChatStyles | Promise<IChatStyles | undefined>
Have a look at the Style forms guide to learn more about styling the runner.
đˇī¸ viewâ
Specifies the initial view mode of the runner. It can be one of the following values:
live: The form is running in normal (production) mode (this is the default value);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;
}
) => 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 | 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).
Have a look at the Collecting response data guide to learn how to feed an identifier or reference associated with the submitted response data back to the runner.
Signatureâ
(instance: Instance, id?: string) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
instance | Instance | No | Reference to the runner instance. |
id | string | 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
đ onEditâ
Specifies a function that is invoked when an edit action is requested. This event is useful in a live preview setup where the builder can open the properties panel of the referenced item.
Read the Live form preview guide for an example.
Signatureâ
(type: "prologue" | "epilogue" | "styles" | "l10n" | "block", id?: string) => void
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
type | "prologue" | "epilogue" | "styles" | "l10n" | "block" | No | Specifies the type of item being edited. |
id | string | Yes | Specifies the item identifier. |
đ 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 Foundation package 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. |
đ onL10nâ
Specifies a function that is invoked when the runner needs a locale or translation. This event is useful for dynamic loading of locale information and translations.
Have a look at the Localization guide to learn how to use this event.
Signatureâ
(l10n: IL10n) => Promise<void>
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
l10n | IL10n | No | Reference to the l10n object. |
Return valueâ
Returns a Promise that resolves when the loading is completed.
đ onPauseâ
Specifies a function or recipe that is invoked when the runner wants to pause. The recipe email can be used if you want to collect the email address of the respondent before pausing the form. Read the Pause and resume guide for more information about this feature.
Once you implement the onPause event, a pause button will appear in the runner's UI. When the respondent clicks this button, the pause event fires. When the email recipe is used, the runner will first ask for the respondent's email address and then invoke the event.
Have a look at the Pause and resume guide to learn more about this feature.
Signatureâ
{
recipe: "email";
onPause: (
emailAddress: string,
snapshot: ISnapshot,
language: string,
locale: string,
namespace: string
) => Promise<void> | boolean | void;
} | ((snapshot: ISnapshot, language: string, locale: string, namespace: string) => Promise<void> | boolean | void)
Parametersâ
| Name | Type | Optional | Description |
|---|---|---|---|
emailAddress | string | No | Contains the email address when the email recipe is used. |
snapshot | ISnapshot | No | Contains the snapshot data. |
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 pause succeeded, false if it failed or a Promise that resolves in case the pause succeeded or rejects in case of an error.
đ onReadyâ
Specifies a function that is invoked when the runner is ready.
The onReady event is invoked after all the resources (form definition, styles, locales, and translations) are loaded.
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. |
đ onReloadâ
Specifies a function that is invoked when the runner wants to reload the definition. The definition returned by this event handler is loaded, preserving the data already entered by the user.
This event will be automatically invoked when data is submitted to an endpoint, but the endpoint indicates the form is outdated. To indicate this, the onSubmit event can reject with status outdated. See the Collecting response data guide for more information about this feature.
Signatureâ
() => IDefinition | Promise<IDefinition>
Return valueâ
Returns the reloaded IDefinition or a Promise that resolves with the IDefinition.
đ 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 Foundation package as shown in the Collecting response data guide.
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.
Have a look at the Collecting response data guide to learn more about submitting data, async operation, and handling errors. To learn more about validating the response data, read the Validating response data guide. If you need spam protection for your forms, the Prevent form spamming guide is of interest to you.
Signatureâ
(instance: Instance, language: string, locale: string, namespace: string) =>
Promise<string | undefined> | boolean | void
| 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).
đ onTouchâ
Specifies a function that is invoked when the runner is "touched" by a user. This is an interaction by the user with the runner by either the mouse, touch input, or keyboard.
Signatureâ
() => void