Services class

📖 Description

The services class implements the connection between a client and the Studio back-end. To create a new instance, use the static form, get, or init function.

---

🆕 constructor

Creates a new services instance with the specified properties.

info

The token of a form can be obtained from the share panel of the Studio application. Open your form in the Studio and then click the Share button.

Signature

constructor(
  properties: {
    token: string;
    signature?: string;
    url?: string;
    filestoreUrl?: string;
  }
): Services

Properties

Name	Type	Optional	Description
token	string	No	Specifies the Studio API token for the form.
signature	string	Yes	Specifies a signature for the form. This signature is a SHA256 hash of the email address of the account that holds the form and the token of the form, separated by a colon: SHA256("<email address>:<token>"). The Studio server will verify the supplied signature and will only return the form if it is from the account specified. The account needs to be specified by the full email adress of the account or *@<domain> to allow all accounts from a certain domain.
url	string	Yes	Specifies the URL of the server. If omitted the default URL will be used.
filestoreUrl	string	Yes	Specifies the URL of the filestore service (used for file uploads). If omitted the default URL will be used.

Return value

Returns a reference to the new services instance.

📌 Statics

---

🔧 form

Initializes a new stock runner. This function retrieves a form from the Studio API and creates a new stock runner (of the supplied runner type). The goal of this function is to make it easy to fetch a form from the Studio, run it, and post the form data back to the Studio.

info

The token of a form can be obtained from the share panel of the Studio application. Open your form in the Studio and then click the Share button.

tip

All properties available in the runner you are using can be provided to this function. Those properties are then passed on to the runner.

caution

This function always sends the form data to the studio regardless of the use of the onSubmit event. Use the init function if you do not want form data to be sent to the Studio.

Signature

form(
  properties: {
    runner: {};
    token: string;
    signature?: string;
    element?: string | HTMLElement;
    persistent?: boolean;
    pausable?: boolean;
    trackers?: (
        type: "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete",
        definition: {
          fingerprint: string;
          name: string;
        },
        block?: {
          id: string;
          name: string;
        }
      ) => void;
    onSubmit?: (
        instance: Instance,
        id: string,
        language: string,
        locale: string,
        namespace: string
      ) => Promise<void> | void;
    url?: string;
    filestoreUrl?: string;
  }
): Services

Properties

Name	Type	Optional	Description
runner	{...}	No	Specifies the runner to use.
token	string	No	Specifies the Studio API token for the form.
signature	string	Yes	Specifies a signature for the form. This signature is a SHA256 hash of the email address of the account that holds the form and the token of the form, separated by a colon: SHA256("<email address>:<token>"). The Studio server will verify the supplied signature and will only return the form if it is from the account specified. The account needs to be specified by the full email adress of the account or *@<domain> to allow all accounts from a certain domain.
element	string | HTMLElement	Yes	Specifies the element to use for the form.
persistent	boolean	Yes	Specifies to store sessions in the local store to preserve persistency when navigating between multiple pages that host the runner.
pausable	boolean	Yes	Specifies if the form can be paused and resumed.
trackers	(...) => void	Yes	Specifies a tracking function that is invoked when the user performs an action.
onSubmit	(...) => Promise<void> | void	Yes	Specifies a function that is invoked when the form is submitted. ⚠️ Please note that the form data is also sent to the Studio. Use the init function if you want to avoid that.
url	string	Yes	Specifies the URL of the server. If omitted the default URL will be used.
filestoreUrl	string	Yes	Specifies the URL of the filestore service (used for file uploads). If omitted the default URL will be used.

Return value

Returns an object that can be used to initiate a new runner.

Example

import * as Autoscroll from "@tripetto/runner-autoscroll";
import Services from "@tripetto/studio";

Services.form({
  runner: Autoscroll,

  // You can obtain the token of a form in the share panel of the Studio
  token: "a-valid-tripetto-token",
});

---

🔧 get

Initializes a new services instance with the specified properties and returns an object that can be supplied directly to one of the Tripetto stock runners.

info

The token of a form can be obtained from the share panel of the Studio application. Open your form in the Studio and then click the Share button.

tip

All properties available in the runner you are using can be provided to this function. Those properties will be included in the return object of this function.

caution

This function always sends the form data to the studio regardless of the use of the onSubmit event. Use the init function if you do not want form data to be sent to the Studio.

Signature

get(
  properties: {
    token: string;
    signature?: string;
    element?: string | HTMLElement;
    persistent?: boolean;
    pausable?: boolean;
    trackers?: (
        type: "start" | "stage" | "unstage" | "focus" | "blur" | "pause" | "complete",
        definition: {
          fingerprint: string;
          name: string;
        },
        block?: {
          id: string;
          name: string;
        }
      ) => void;
    onSubmit?: (
        instance: Instance,
        id: string,
        language: string,
        locale: string,
        namespace: string
      ) => Promise<void> | void;
    url?: string;
    filestoreUrl?: string;
  }
): Services

Properties

Name	Type	Optional	Description
token	string	No	Specifies the Studio API token for the form.
signature	string	Yes	Specifies a signature for the form. This signature is a SHA256 hash of the email address of the account that holds the form and the token of the form, separated by a colon: SHA256("<email address>:<token>"). The Studio server will verify the supplied signature and will only return the form if it is from the account specified. The account needs to be specified by the full email adress of the account or *@<domain> to allow all accounts from a certain domain.
element	string | HTMLElement	Yes	Specifies the element to use for the form.
persistent	boolean	Yes	Specifies to store sessions in the local store to preserve persistency when navigating between multiple pages that host the runner.
pausable	boolean	Yes	Specifies if the form can be paused and resumed.
trackers	(...) => void	Yes	Specifies a tracking function that is invoked when the user performs an action.
onSubmit	(...) => Promise<void> | void	Yes	Specifies a function that is invoked when the form is submitted. ⚠️ Please note that the form data is also sent to the Studio. Use the init function if you want to avoid that.
url	string	Yes	Specifies the URL of the server. If omitted the default URL will be used.
filestoreUrl	string	Yes	Specifies the URL of the filestore service (used for file uploads). If omitted the default URL will be used.

Return value

Returns an object that can be used to initiate a new runner.

Example

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

run(Services.get({
    // You can obtain the token of a form in the share panel of the Studio
    token: "a-valid-tripetto-token",

    // If you want you can use the submit event to also send the response data
    // to a custom endpoint. Please note that when using this function, the
    // response data is always first stored in the Studio.
    onSubmit: (instance, id) => {
      const data = Export.dataset(instance);

      // Do something with the data here
    }
}));

---

🔧 init

Initializes a new services instance with the specified properties.

info

The token of a form can be obtained from the share panel of the Studio application. Open your form in the Studio and then click the Share button.

Signature

init(
  properties: {
    token: string;
    signature?: string;
    url?: string;
    filestoreUrl?: string;
  }
): Services

Properties

Name	Type	Optional	Description
token	string	No	Specifies the Studio API token for the form.
signature	string	Yes	Specifies a signature for the form. This signature is a SHA256 hash of the email address of the account that holds the form and the token of the form, separated by a colon: SHA256("<email address>:<token>"). The Studio server will verify the supplied signature and will only return the form if it is from the account specified. The account needs to be specified by the full email adress of the account or *@<domain> to allow all accounts from a certain domain.
url	string	Yes	Specifies the URL of the server. If omitted the default URL will be used.
filestoreUrl	string	Yes	Specifies the URL of the filestore service (used for file uploads). If omitted the default URL will be used.

Return value

Returns a reference to the new services instance.

Example

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

const { definition, onSubmit } = Services.init({
    // You can obtain the token of a form in the share panel of the Studio
    token: "a-valid-tripetto-token"
});

run({
    definition,
    onSubmit
});

🗃️ Fields

---

🏷️ attachments

Retrieves the attachments object that holds the endpoints for file upload store.

tip

For more information how this field is used in a runner, take a look at the attachments property of the Autoscroll stock runner.

Type

IRunnerAttachments

---

🏷️ definition

Fetches the form definition from the server. Returns a promise that resolves with the form definition (or undefined if the definition was not found).

Type

Promise<IDefinition | undefined>

---

🏷️ l10n

Fetches the form localization and translation data from the server. Returns a promise that resolves with the data (or undefined if no data was found).

tip

For more information how this field is used in a runner, take a look at the l10n property of the Autoscroll stock runner.

Type

Promise<IL10n | undefined>

---

🏷️ license

Retrieves the license code for the form.

tip

For more information how this field is used in a runner, take a look at the license property of the Autoscroll stock runner.

Type

() => Promise<string | undefined>

---

🏷️ locale

Retrieves the locale function used to retrieve locale data.

tip

For more information how this field is used in a runner, take a look at the locale property of the Autoscroll stock runner.

Type

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

---

🏷️ snapshot

Fetches the form snapshot from the server. Returns a promise that resolves with the form snapshot (or undefined if no snapshot was found).

Type

Promise<ISnapshot | undefined>

---

🏷️ styles

Fetches the form styles from the server. Returns a promise that resolves with the form styles (or undefined if no styles were found).

info

The form styles object differs per runner. For example, when the Autoscroll stock runner is used, this property returns an IAutoscrollStyles object.

Type

Promise<TStyles | undefined>

---

🏷️ translations

Retrieves the translation function used to retrieve translation data.

tip

For more information how this field is used in a runner, take a look at the translations property of the Autoscroll stock runner.

Type

(language: "auto" | string, context: string) => Promise<L10n.TTranslation | L10n.TTranslation[] | undefined>

📢 Events

---

🏷️ onPause

Retrieves the pause function that is invoked when a form is paused.

Signature

{
  recipe: "email";
  onPause: (
    emailAddress: string,
    snapshot: ISnapshot,
    language: string,
    locale: string,
    namespace: string
  ) => Promise<void>;
}

Parameters

Name	Type	Optional	Description
emailAddress	string	No	Contains the email address.
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 a Promise that resolves in case the pause succeeded or rejects in case of an error.

---

🏷️ onReload

Retrieves the reload function that is invoked when a form definition should reload from the server.

Signature

() => Promise<IDefinition>

Return value

Returns a Promise that resolves with the IDefinition.

---

🏷️ onSubmit

Retrieves the submit function that is invoked when a form response is submitted to the server.

Signature

(instance: Instance, language: string, locale: string, namespace: string) =>
  Promise<string | undefined>

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 a Promise that resolves with an optional reference string (in case it succeeds) or rejects (in case of an error).