IChat interface

📖 Description

Properties interface for configuring a runner instance using the run function.

📃 Type declaration

interface IChat {
  element?: HTMLElement;Optional
  definition?: IDefinition | Promise<IDefinition | undefined>;Optional
  snapshot?: ISnapshot | Promise<ISnapshot | undefined>;Optional
  styles?: IChatStyles | Promise<IChatStyles | undefined>;Optional
  l10n?: IL10n | Promise<IL10n | undefined>;Optional
  license?: string | Promise<string | undefined>;Optional
  view?: "live" | "test" | "preview";Optional
  display?: "inline" | "button" | "page";Optional
  removeBranding?: boolean;Optional
  persistent?: boolean;Optional
  className?: string;Optional
  customStyle?: CSSProperties;Optional
  customCSS?: string;Optional
  attachments?: IRunnerAttachments;Optional
  language?: string;Optional
  locale?: L10n.ILocale | ((locale: string) => L10n.ILocale | Promise<L10n.ILocale | undefined> | undefined);Optional
  translations?: L10n.TTranslation | L10n.TTranslation[] | ((language: string, name: string, version: string) => L10n.TTranslation | L10n.TTranslation[] | Promise<L10n.TTranslation | L10n.TTranslation[] | undefined> | undefined);Optional
  builder?: Builder;Optional
  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;
      alias?: 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
}

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

🗃️ 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

IRunnerAttachments

warning

If your form uses file uploads and no attachments handler is defined, the uploaded files are included in the dataset using Base64 encoding.

tip

Have a look at the Handling file uploads guide to learn how to use this feature.

🏷️ `builder`

Property to receive a reference to a Builder instance. This will bind the runner with the builder and allows the builder to use the runner as a live form preview.

Type

Builder

tip

Have a look at the Live preview guide to learn more about this feature.

🏷️ `className`

Specifies a custom class name for the HTML element that holds the runner.

Type

string

tip

Have a look at the Style forms 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

Example

import { run } from "@tripetto/runner-chat";

run({
  definition: /* Supply your form definition here */,
  customCSS: `
    [data-block="@tripetto/block-text"] { background-color: blue; }
    [data-block="@tripetto/block-checkbox"] {
      input {
        background-color: red;
      }
    }
  `
});

tip

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

Example

import { run } from "@tripetto/runner-chat";

run({
  definition: /* Supply your form definition here */,
  customStyle: {
    height: "100px"
  }
});

tip

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>

Example

import { run } from "@tripetto/runner-chat";

// Supply a static definition
run({
  definition: /* Supply your form definition here */
});

// Or, supply a definition dynamically
run({
  definition: new Promise((resolve) => {
    // This example uses fetch to retrieve a form definition
    fetch("/definition.json")
      .then((response) => {
        response.json().then((definition) => resolve(definition));
      });
  }),
});

🏷️ `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"

tip

Have a look at the Display guide to learn more about the runner display modes.

warning

The display setting overrides the display property in the styles settings of the runner.

🏷️ `element`

Specifies the parent element for the runner. If this property is omitted the runner inserts a new HTML element on the position where the run function is invoked. If the display property is set to page, the runner uses the body element of the HTML document.

Type

HTMLElement

tip

Have a look at the Plain JS implementation guide for an example of how to use this property.

🏷️ `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>

tip

Have a look at the Localization guide for more information about locales and translations.

🏷️ `language`

Specifies the preferred language to use for the form locale and translation. This property is only used for form definitions that don't have a specified language. If a language is specified in the form definition, that language is always used.

Type

string

warning

Make sure to implement dynamic loading of locales and translations to let this feature work. Dynamic loading allows the runner to load the appropriate locale and translation based on the form language or the language specified by this property.

🏷️ `license`

Specifies a license code for the runner. This property also accepts a Promise. That's useful when you want to load the license code dynamically from an external source.

Type

string | Promise<string | undefined>

tip

Have a look at the License guide for more information about applying licenses.

🏷️ `locale`

Specifies the locale or the locale loader function to use. The locale data contains the number and date/time formats the runner uses.

Type

L10n.ILocale | ((locale: string) => L10n.ILocale | Promise<L10n.ILocale | undefined> | undefined)

tip

Have a look at the Localization guide to learn more about this feature.

🏷️ `persistent`

Specifies if the runner should try to store sessions in the local store to preserve persistency on navigation between multiple pages that host the runner.

Type

boolean

tip

Have a look at the Form data persistency guide to learn more about this feature.

🏷️ `removeBranding`

Removes all visual Tripetto branding from the runner (a valid license is required).

Type

boolean

tip

Have a look at the Disable Tripetto branding guide to learn more about removing the branding.

🏷️ `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>

tip

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>

tip

Have a look at the Style forms guide to learn more about styling the runner.

🏷️ `translations`

Specifies the translations or the translations loader function to use.

Type

tip

Have a look at the Localization guide to learn more about this feature.

🏷️ `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.

tip

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

tip

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).

tip

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 runner is destroyed.

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.

tip

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 library as shown in the Prefilling forms guide.

tip

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.

Example

import { run } from "@tripetto/runner-autoscroll";
import { Import } from "@tripetto/runner";

run({
  definition: /* Supply your form definition here */,
  onImport: (instance) => {
    // This example assumes the form has two text fields with
    // the data identifiers (aliases) `FIRSTNAME` and `LASTNAME`.
    Import.fields(instance, [
      {
        name: "FIRSTNAME",
        value: "John",
      },
      {
        name: "LASTNAME",
        value: "Doe",
      }
    ]);
  }
});

🔔 `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.

tip

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.

info

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.

Signature

() => IDefinition | Promise<IDefinition>

Return value

Returns the reloaded IDefinition or a Promise that resolves with the IDefinition.

info

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.

🔔 `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 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.

tip

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

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).

Example

import { run } from "@tripetto/runner-autoscroll";
import { Export } from "@tripetto/runner";

run({
  definition: /* Supply your form definition here */,
  onSubmit: (instance) => {
    // This exports all exportable data in the form
    const exportables = Export.exportables(instance);

    // Iterate through all the fields
    exportables.fields.forEach((field) => {
      // Output each field name and value to the console
      console.log(`${field.name}: ${field.string}`);
    });

    // This exports the collected data as a CSV object
    const csv = Export.CSV(instance);

    // Output CSV to the console
    console.log(csv.fields);
    console.log(csv.record);
  }
});

🔔 `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

IChat interface

📖 Description​

📃 Type declaration​

🗃️ Properties​

🏷️ attachments​

Type​

🏷️ builder​

Type​

🏷️ className​

Type​

🏷️ customCSS​

Type​

Example​

🏷️ customStyle​

Type​

Example​

🏷️ definition​

Type​

Example​

🏷️ display​

Type​

🏷️ element​

Type​

🏷️ l10n​

Type​

🏷️ language​

Type​

🏷️ license​

Type​

🏷️ locale​

Type​

🏷️ persistent​

Type​

🏷️ removeBranding​

Type​

🏷️ snapshot​

Type​

🏷️ styles​

Type​

🏷️ translations​

Type​

🏷️ view​

Type​

📢 Events​

🔔 onAction​

Signature​

Parameters​

🔔 onChange​

Signature​

Parameters​

🔔 onComplete​

Signature​

Parameters​

🔔 onData​

Signature​

Parameters​

🔔 onDestroy​

Signature​

🔔 onEdit​

Signature​

Parameters​

🔔 onImport​

Signature​

Parameters​

Example​

🔔 onPause​

Signature​

Parameters​

Return value​

🔔 onReady​

Signature​

Parameters​

🔔 onReload​

Signature​

Return value​

🔔 onSubmit​

Signature​

Parameters​

Return value​

Example​

📖 Description

📃 Type declaration

🗃️ Properties

🏷️ `attachments`

Type

🏷️ `builder`

Type

🏷️ `className`

Type

🏷️ `customCSS`

Type

Example

🏷️ `customStyle`

Type

Example

🏷️ `definition`

Type

Example

🏷️ `display`

Type

🏷️ `element`

Type

🏷️ `l10n`

Type

🏷️ `language`

Type

🏷️ `license`

Type

🏷️ `locale`

Type

🏷️ `persistent`

Type

🏷️ `removeBranding`

Type

🏷️ `snapshot`

Type

🏷️ `styles`

Type

🏷️ `translations`

Type

🏷️ `view`

Type

📢 Events

🔔 `onAction`

Signature

Parameters

🔔 `onChange`

Signature

Parameters

🔔 `onComplete`

Signature

Parameters

🔔 `onData`

Signature

Parameters

🔔 `onDestroy`

Signature

🔔 `onEdit`

Signature

Parameters

🔔 `onImport`

Signature

Parameters

Example

🔔 `onPause`

Signature

Parameters

Return value

🔔 `onReady`

Signature

Parameters

🔔 `onReload`

Signature

Return value

🔔 `onSubmit`

Signature

Parameters

Return value

Example

🔔 `onTouch`