Skip to main content

IBuilderProperties interface

📖 Description​

Properties interface for configuring the builder instance. This interface is used when constructing a new builder instance.

📃 Type declaration​

interface IBuilderProperties {
  element?: HTMLElement;Optional
  fonts?: string | "inherit";Optional
  locale?: L10n.ILocale;Optional
  translations?: L10n.TTranslation | L10n.TTranslation[];Optional
  namespace?: {
    identifier: string;
    umd?: string;
    url?: string;
    onLoad?: (namespace: INamespace) => void;
  };Optional
  tier?: IBuilderTier;Optional
  license?: string;Optional
  zoom?: "1:1" | "fit" | "fit-horizontal" | "fit-vertical";Optional
  centering?: boolean;Optional
  controls?: "left" | "right";Optional
  rubberBandEffect?: "always" | true | false;Optional
  disableResizing?: boolean;Optional
  disablePrologue?: boolean;Optional
  disableEpilogue?: boolean;Optional
  disableNesting?: boolean;Optional
  disableZoombar?: boolean;Optional
  disableLogo?: boolean;Optional
  disableSaveButton?: boolean;Optional
  disableRestoreButton?: boolean;Optional
  disableClearButton?: boolean;Optional
  disableEditButton?: boolean;Optional
  disableCloseButton?: boolean;Optional
  disableTutorialButton?: boolean;Optional
  disableOpenCloseAnimation?: boolean;Optional
  showTutorial?: boolean;Optional
  previewURL?: string;Optional
  supportURL?: string | false;Optional
  nestedFormMode?: boolean;Optional
  disableFormAbort?: boolean;Optional
  disableCreateEmptyForm?: boolean;Optional
  disableConvertToForm?: boolean;Optional
  disableMoveToForm?: boolean;Optional
  browseFormsLabel?: string;Optional
  saveFormLabel?: string;Optional
  helpTopics?: {
    prologue?: string;
    epilogue?: string;
    branches?: string;
    conditions?: string;
    culling?: string;
    terminators?: string;
    [topic: string]: string | undefined;
  };Optional
  onLoad?: (builder: Builder) => void;EventOptional
  onError?: (erroneousBlocks: number, missingBlockTypes: string[], builder: Builder) => void;EventOptional
  onReady?: (builder: Builder) => void;EventOptional
  onOpen?: (builder: Builder) => void;EventOptional
  onSave?: (definition: IDefinition, builder: Builder) => void | Promise<void>;EventOptional
  onChange?: (definition: IDefinition, builder: Builder) => void | Promise<void>;EventOptional
  onPreview?: (definition: IDefinition, builder: Builder) => void;EventOptional
  onEdit?: (data: TBuilderEditData) => void;EventOptional
  onClose?: (builder: Builder) => void;EventOptional
  onOpenForm?: (definition: INestedDefinition, layer: Layer) =>
    Promise<INestedDefinition | string | void> | boolean | void;EventOptional
  onListForms?: TFormsList | (() => TFormsList | Promise<TFormsList>);EventOptional
  onBrowseForms?: (element: Element, layer: Layer) => Promise<INestedDefinition | string>;EventOptional
  onLoadForm?: (reference: string) => INestedDefinition | undefined | Promise<INestedDefinition>;EventOptional
  onUpdateForm?: (reference: string, version?: string) => boolean | Promise<boolean>;EventOptional
  onSaveForm?: (definition: INestedDefinition, element: Element, layer: Layer) => Promise<{
    reference: string;
    version?: string;
    readonly?: boolean;
  } | string>;EventOptional
  onBreadcrumb?: (
    forms: {
      name: string;
      edit: () => void;
      activate: () => void;
      close: () => void;
    }[],
    back: (() => void) | undefined
  ) => void;EventOptional
  onMenu?: (
    type: "node" | "section" | "branch" | "condition",
    options: MenuOption[],
    reference: Node | Section | Branch | Condition
  ) => MenuOption[];EventOptional
}
🖱ī¸ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

🗃ī¸ Properties​

🏷ī¸ browseFormsLabel​

Specifies an alternative label for the browse forms feature (default is Browse forms).

Type​

string

🏷ī¸ centering​

Specifies if the content in the builder is centered instead of left-aligned (default is true).

Type​

boolean

🏷ī¸ controls​

Specifies the location of the navigation and zoombar (default is right).

Type​

"left" | "right"

🏷ī¸ disableClearButton​

Disables the clear button in the navigation bar (default is true). When the clear button is pressed, the whole form is removed and a new empty one is created.

Type​

boolean

🏷ī¸ disableCloseButton​

Disables the close button in the navigation bar. The close button closes the builder and invokes the onClose event.

Type​

boolean

🏷ī¸ disableConvertToForm​

Disables the possibility to convert sections into nested forms or vice-versa.

Type​

boolean

🏷ī¸ disableCreateEmptyForm​

Disables the possibility to create new (empty) nested forms.

Type​

boolean

🏷ī¸ disableEditButton​

Disables the edit button in the navigation bar. The edit button opens the form properties editor panel, where the name, language, description, and keywords of the form are managed.

Type​

boolean

🏷ī¸ disableEpilogue​

Specifies if the epilogue feature should be disabled. The epilogue is the closing message that is shown when a form is completed. If you don't need this feature, you should disable it so that users cannot access it in the builder.

Type​

boolean

🏷ī¸ disableFormAbort​

Disables the possibility to abort the whole form in nested forms. Nested forms can then only return to the parent form, but never end the whole form.

Type​

boolean

Disables the Tripetto logo in the navigation bar.

Type​

boolean

🏷ī¸ disableMoveToForm​

Disables the possibility to move sections to existing nested forms.

Type​

boolean

🏷ī¸ disableNesting​

Specifies if creating new nested branches (subforms) should be disabled.

Type​

boolean

🏷ī¸ disableOpenCloseAnimation​

Disables the open and close animation of the builder. When the builder is opened or closed a zoom animation can be used.

Type​

boolean

🏷ī¸ disablePrologue​

Specifies if the prologue feature should be disabled. The prologue is the welcome message that is shown before a form starts. If you don't need this feature, you should disable it so that users cannot access it in the builder.

Type​

boolean

🏷ī¸ disableResizing​

Disables automatic resizing when the dimensions of the HTML element that holds the builder are changed. If you set this to true you should invoke the resize function of the builder instance whenever the parent element is resized.

Type​

boolean

tip

See this guide for more information about handling resizing.

🏷ī¸ disableRestoreButton​

Disables the restore button in the navigation bar (default is true). The restore button restores a form to the previous saved state. So this will undo any changes made to the form since the last save action was called.

Type​

boolean

🏷ī¸ disableSaveButton​

Disables the save button in the navigation bar.

Type​

boolean

warning

When you disable the save button, you need to invoke the save function manually to initiate a save action. Or use the onChange event to detect form changes.

🏷ī¸ disableTutorialButton​

Disables the tutorial button in the navigation bar.

Type​

boolean

🏷ī¸ disableZoombar​

Disables the visual zoombar that is shown when the form exceeds the size of the builder viewport.

Type​

boolean

🏷ī¸ element​

Host HTML element for the builder. The builder renders inside this element. If omitted, the builder renders in the document body element.

Type​

HTMLElement

warning

When you specify a custom HTML element for the builder, you need to make sure to set the position style attribute of that element to absolute, relative, fixed, or sticky. Otherwise, it is possible that the builder is displayed outside of the element boundaries.

🏷ī¸ fonts​

Specifies the path to the folder with the font files. The Tripetto builder requires these font files, and they are included in the builder package in the fonts folder. If you don't specify a value for this property, the fonts will be loaded from the unpkg CDN. We recommend to copy the font files to the static asset folder of your project and then supply a relative path or an absolute URL to those files. You can also supply inherit if you take care of the font loading yourself.

Type​

string | "inherit"

tip

See this guide for more information about font loading.

🏷ī¸ helpTopics​

Specifies URLs to help topics and enables assistive buttons/links in the builder. You can define as many topics as you like, but the following topics are used in the builder:

Type​

{
  [topic: string]: string | undefined;
}
tip

Use the getHelpTopic function to retrieve the topic data.

🏷ī¸ license​

Specifies a license code for the builder.

Type​

string

tip

See this guide for more information about licenses.

🏷ī¸ locale​

Specifies the locale data for the builder. The locale data contains localization information to configure the builder for a particular locale. This is used to show the right number and date/time formats in the builder. The builder package comes with all the locales included. Locale information is stored in a JSON file per locale. The locale JSON files are in the locales folder of the package. You need to load the appropriate locale JSON and feed it to this property. If omitted, the default locale en is used.

Type​

L10n.ILocale

info

You can only set the locale when creating a new builder instance. If you want to change the locale during runtime, you need to construct a new builder instance.

tip

See this guide for more information about localization.

🏷ī¸ namespace​

Specifies a block namespace object to use or load. This can be used to supply a bundle of blocks that needs to be loaded. The supplied object contains the following properties:

  • identifier: Specifies the namespace identifier;
  • umd: Specifies the UMD bundle code for the namespace;
  • url: Specifies the URL of the UMD bundle to load;
  • onLoad: Optional callback invoked when the namespace is loaded.

Type​

{
  identifier: string;
  umd?: string;
  url?: string;
  onLoad?: (namespace: INamespace) => void;
}
warning

If your application implements a Content Security Policy (CSP) and prohibits the use of eval(), you should always load namespace block bundles using the url property. This method uses a Trusted Type policy named tripetto#loader for loading the bundle, so make sure to whitelist that Trusted Type. More on CSP and Trusted Types can be found in this guide.

tip

See this guide for more information about block loading.

🏷ī¸ nestedFormMode​

Specifies if the builder should run in nested form mode. This disables the use of a prologue or epilogue on the main branch and optimizes the builder for editing forms that can be used as nested forms (subforms).

Type​

boolean

🏷ī¸ previewURL​

Specifies the URL of a preview page. When set, a preview button will be shown in the navigation bar. When the user clicks that button, a new tab/window with the supplied URL is loaded.

Type​

string

🏷ī¸ rubberBandEffect​

Specifies if the rubber band effect (also known as the elastic overscrolling effect) is enabled for the builder. Can be one of the following values:

  • always: Rubber band effect is always enabled, even when the content doesn't exceed the builder viewport (this is the default value);
  • true: Rubber band effect is enabled when the content exceeds the builder viewport;
  • false: Rubber band effect is disabled.

Type​

"always" | true | false

🏷ī¸ saveFormLabel​

Specifies an alternative label for the save form feature (default is Save).

Type​

string

🏷ī¸ showTutorial​

Shows the tutorial dialog on startup.

Type​

boolean

🏷ī¸ supportURL​

Specifies an URL to a custom help or support page or supply false to disable this button.

Type​

string | false

🏷ī¸ tier​

Specifies a tier for the builder. The tier defines which blocks are available for the user or not.

Type​

IBuilderTier

tip

See this guide for more information about using tiers.

🏷ī¸ translations​

Specifies the translations for the builder and blocks. To use the builder in another language, the translation for this language needs to be loaded. Builder translations are bundled with the builder package and stored in the translations folder. You need to load the appropriate translation JSON and feed it to this property.

This property can also be used to load translations for the blocks. Simply load the block translation JSON files and feed them as an array of translations.

Type​

L10n.TTranslation | L10n.TTranslation[]

info

You can only set the translations when creating a new builder instance. If you want to change the translation during runtime, you need to construct a new builder instance.

tip

See this guide for more information about localization and translations.

🏷ī¸ zoom​

Specifies the initial zoom state for the builder. It can be one of the following values:

  • 1:1: Start the builder without zooming out;
  • fit: Start the builder with a zoom factor so it can fit the entire form (this is the default behavior);
  • fit-horizontal: Start the builder with a zoom factor so it can fit the form horizontally;
  • fit-vertical: Start the builder with a zoom factor so it can fit the form vertically.

Type​

"1:1" | "fit" | "fit-horizontal" | "fit-vertical"

đŸ“ĸ Events​

🔔 onBreadcrumb​

Invoked everytime when a nested subform is opened or closed in the builder. Useful for rendering a breadcrumb that shows all the opened forms and allows to navigate back to parent form.

caution

When this event is implemented, the default navigation bar to close a subform (this is a floating bar in the builder) will not be shown anymore. So you should use this event to provide an interactive breadcrumb to the user with controls to edit the name of the subform and to close the subform (so it returns to the parent form).

Signature​

(
  forms: {
    name: string;
    edit: () => void;
    activate: () => void;
    close: () => void;
  }[],
  back: (() => void) | undefined
) => void

Parameters​

NameTypeOptionalDescription
forms{...}[]NoArray with forms to show in the breadcrumb. For each form, the following properties are supplied:
- name: Contains the name of the form;
- edit: Function to show the form properties editor where the name of the form can be edited;
- activate: Function to activate the form if it is not the active form currently;
- close: Function to close the form and return to the parent form.
back(() => void) | undefinedNoFunction to go back to the previous form (this parameter may be undefined when the root form is opened and you cannot go back any further).
tip

See the Subforms guide for more information.

🔔 onBrowseForms​

Invoked when the builder wants to browse for a subform. This allows to implement a custom UI for browsing through the possible forms and select the desired form to load.

Signature​

(element: Element, layer: Layer) => Promise<INestedDefinition | string>

Parameters​

NameTypeOptionalDescription
elementElementNoReference to the Element instance. This instance is a wrapper around the actual DOM element of the browser. If you need access to the DOM element itself, use element.HTMLElement.
layerLayerNoReference to the Layer instance which is the internal layering system of the Tripetto UI.

Return value​

Should return a Promise that resolves with a definition or reference. To cancel browsing for a form, the promise should reject. When a reference is returned, the builder will invoke the onLoadForm event to obtain the definition that belongs to that reference.

Example​

import { Builder } from "@tripetto/builder";

const builder = new Builder({
  onBrowseForms: (element) =>
    new Promise((resolve, reject) => {
      const root = ReactDOM.createRoot(element.HTMLElement);

      root.render(
        <div>
          <h1>Browse forms</h1>
          <ul>
            <li onClick={() => resolve("1")}>Form 1</li>
            <li onClick={() => resolve("2")}>Form 2</li>
          </ul>
          <button onClick={() => reject()}>Cancel</button>
        </div>
      );
    })
});
info

You can use the browseFormsLabel property to set a label for the save option in the builder menu.

tip

See the Subforms guide for more information.

🔔 onChange​

Invoked when the definition is changed.

Signature​

(definition: IDefinition, builder: Builder) => void | Promise<void>

Parameters​

NameTypeOptionalDescription
definitionIDefinitionNoContains the changed form definition.
builderBuilderNoReference to the builder instance.

Return value​

When a Promise is returned the builder goes into a loading state until the promise resolves or rejects.

info

If you need live (or real-time) saving of form definitions, you should use this event.

tip

You can also use the hook method to hook into this event.

🔔 onClose​

Invoked when the builder is closed.

Signature​

(builder: Builder) => void

Parameters​

NameTypeOptionalDescription
builderBuilderNoReference to the builder instance.
tip

You can also use the hook method to hook into this event.

🔔 onEdit​

Invoked when an editor panel is opened or closed.

Signature​

(data: TBuilderEditData) => void

Parameters​

NameTypeOptionalDescription
dataTBuilderEditDataNoContains information about the element being edited.
tip

You can also use the hook method to hook into this event.

🔔 onError​

Invoked when there was an error during loading a form definition. It also gives some details about the number of errors found (that's the number of blocks that could not load) and a list of blocks types that are missing (and the reason for the error).

Signature​

(erroneousBlocks: number, missingBlockTypes: string[], builder: Builder) => void

Parameters​

NameTypeOptionalDescription
erroneousBlocksnumberNoContains the number of blocks that could not load.
missingBlockTypesstring[]NoContains an array of block type identifiers that are missing.
builderBuilderNoReference to the builder instance.
tip

You can also use the hook method to hook into this event.

🔔 onListForms​

Invoked when the builder needs the list of forms that can be used as subform. This list is shown to the builder user when a new subform is about to be created. The list can contain forms, categories, and dividers. The TFormsList type describes the format for the list structure. You can either supply the list as value for the onListForms property, return it from a function, or use a Promise (in case you need asynchronous loading of the list).

Signature​

TFormsList | (() => TFormsList | Promise<TFormsList>)

Usage​

The TFormsList type is used to define the list of forms. This is an array that allows the following types of items:

Forms​

Forms can be defined using a reference or the actual definition for the subform. When a reference is supplied, the builder will invoke the onLoadForm event to obtain the definition that belongs to that reference.

Specify a form by reference​
{
  /* Name of the form. */
  name: string;

  /* Reference (identifier) of the form. */
  reference: string
}
caution

This requires the onLoadForm event to load the actual form definition.

Specify a form by its definition​
{
  /* Name of the form. */
  name: string;

  /* Definition of the form. */
  definition: INestedDefinition | (() => INestedDefinition | Promise<INestedDefinition>)
}
info

You can either supply a form definition, or a function that returns a form definition, or a promise to a form definition. The latter is useful when you want to retrieve the form definition from an API or other asynchronous process when the user selects the form in the list.

Categories​

Categories can be used to organize forms. This is a recursive structure, so it can be used to define subcategories. You can create as many levels as you want.

{
  /* Name of the category. */
  category: string;

  /* Items for the category. */
  forms: TFormsList;
}
Dividers​

Dividers can be used to create sections in the menu. Each section is divided by a separator (line) and the name of the divider.

{
  /* Name of the divider. */
  divider: string;
}

Example​

import { Builder } from "@tripetto/builder";

const builder = new Builder({
  onListForms: [
    {
      divider: "Recently used forms"
    },
    {
      name: "Form 1",
      reference: "1"
    },
    {
      name: "Form 2",
      reference: "2"
    },
    {
      divider: "Your forms library"
    },
    {
      category: "Contact forms",
      forms: [
        {
          name: "Form 3",
          reference: "3"
        },
      ]
    },
    {
      category: "Quotation forms",
      forms: []
    },
  ]
});
tip

See the Subforms guide for more information.

🔔 onLoad​

Invoked when the builder is loading.

Signature​

(builder: Builder) => void

Parameters​

NameTypeOptionalDescription
builderBuilderNoReference to the builder instance.
info

The onLoad event is invoked before the onReady and onOpen events.

tip

You can also use the hook method to hook into this event.

🔔 onLoadForm​

Invoked when the builder wants to load a certain subform.

Signature​

(reference: string) => INestedDefinition | undefined | Promise<INestedDefinition>

Parameters​

NameTypeOptionalDescription
referencestringNoReference of the form to load.

Return value​

Should return a INestedDefinition object or undefined if the form could not be loaded. You may also return a Promise that resolves with the definition or rejects when the load failed.

Example​

import { Builder } from "@tripetto/builder";

const builder = new Builder({
  onLoadForm: (reference) =>
    new Promise((resolve, reject) => {
      fetch("/api/form/get/" + reference)
        .then((response) => response.json())
        .then((data) => resolve(data))
        .catch(() => reject());
    })
});
tip

See the Subforms guide for more information.

🔔 onMenu​

Invoked when the context menu of a node, section, branch, or condition is requested. This event receives both a reference to the context and the layout of an item. The context serves as the model of the item in the definition and the layout as the view of the item in the UI. Most actions (like adding, reordering, or deleting items) are performed on the model (so using the context parameter), but some actions are initated using the layout. Hence the reason why it is supplied as parameter to this event.

info

The most common action that should be invoked from the layout is opening the editor panel of an item in the builder. This is done by calling the layout.edit() method.

danger

This event can be used to alter the default menus used by the builder. If you do this, always make sure to verify your implementation when you update the builder to a new version. Changes in the default context menus might require updates to your code.

Signature​

(
  type: "node" | "section" | "branch" | "condition",
  options: MenuOption[],
  context: Node | Section | Branch | Condition,
  layout: NodeLayout | SectionLayout | BranchLayout | ConditionLayout
) => MenuOption[]

Parameters​

NameTypeOptionalDescription
type"node" | "section" | "branch" | "condition"NoSpecifies the type of context menu.
optionsMenuOption[]NoContains the default context menu options.
contextNode | Section | Branch | ConditionNoReference to the item for which the context menu is.
layoutNodeLayout | SectionLayout | BranchLayout | ConditionLayoutNoReference to the layout of the context.

Return value​

Should return an array with menu options.

🔔 onOpen​

Invoked when the builder is opened and shown to the user.

Signature​

(builder: Builder) => void

Parameters​

NameTypeOptionalDescription
builderBuilderNoReference to the builder instance.
info

The onOpen event is always invoked after the onLoad and onReady events.

tip

You can also use the hook method to hook into this event.

🔔 onOpenForm​

Invoked when the builder wants to open a subform for editing.

Signature​

(definition: INestedDefinition, layer: Layer) =>
  Promise<INestedDefinition | string | void> | boolean | void

Parameters​

NameTypeOptionalDescription
definitionINestedDefinitionNoReference to form definition of the subform (this is an immutable version of the definition).
layerLayerNoReference to the Layer instance which is the internal layering system of the Tripetto UI.

Return value​

There are three options for the return value of this event:

  • Return nothing (void) when you want to use this event to track opening a subform, but don't want to change the default editing behavior;
  • A boolean value to indicate if the default editing behavior should execute (return true if the subform should be opened or return false to disallow opening the subform);
  • A Promise to indicate to the builder that you are controlling the opening of the form. Resolve the promise when the editing of the form ends. Optionally you can resolve with the updated definition (or the reference of the updated definition in case you've implemented the onLoadForm event). As long as the promise is not resolved or rejected, the builder will remain in a waiting state where no user interaction is allowed.

🔔 onPreview​

Invoked when a definition preview should be updated.

Signature​

(definition: IDefinition, builder: Builder) => void

Parameters​

NameTypeOptionalDescription
definitionIDefinitionNoContains the changed form definition.
builderBuilderNoReference to the builder instance.
tip

You can also use the hook method to hook into this event.

🔔 onReady​

Invoked when the builder is ready loading.

Signature​

(builder: Builder) => void

Parameters​

NameTypeOptionalDescription
builderBuilderNoReference to the builder instance.
info

The onReady event is invoked after the onLoad event but before the onOpen event.

tip

You can also use the hook method to hook into this event.

🔔 onSave​

Invoked when the definition is saved. This happens when the user clicks the save button in the Tripetto toolbar.

Signature​

(definition: IDefinition, builder: Builder) => void | Promise<void>

Parameters​

NameTypeOptionalDescription
definitionIDefinitionNoContains the form definition to save.
builderBuilderNoReference to the builder instance.

Return value​

When a Promise is returned the builder goes into a loading state until the promise resolves or rejects.

info

It is possible to disable the save button (or the whole toolbar). Then you can use the 'save' method to initiate a save action or use the onChange event for real-time monitoring changes in the form definition.

tip

You can also use the hook method to hook into this event.

🔔 onSaveForm​

Invoked when the builder wants to save a subform. This event allows to implement a custom UI with a save dialog.

Signature​

(definition: INestedDefinition, element: Element, layer: Layer) => Promise<{
  reference: string;
  version?: string;
  readonly?: boolean;
} | string>

Parameters​

NameTypeOptionalDescription
definitionINestedDefinitionNoReference to form definition.
elementElementNoReference to the Element instance. This instance is a wrapper around the actual DOM element of the browser. If you need access to the DOM element itself, use element.HTMLElement.
layerLayerNoReference to the Layer instance which is the internal layering system of the Tripetto UI.

Return value​

Should return a Promise that resolves with a string that contains the reference of the saved form, or an object with the reference, version, and readonly properties for the saved form.

info

You can use the saveFormLabel property to set a label for the save option in the builder menu.

tip

See the Subforms guide for more information.

🔔 onUpdateForm​

Invoked when the builder wants to know if there is an update available for a certain form.

Signature​

(reference: string, version?: string) => boolean | Promise<boolean>

Parameters​

NameTypeOptionalDescription
referencestringNoReference of the form to verify.
versionstringNoVersion of the form that is currently loaded.

Return value​

Should return true if there is an update available for the form (the update button in the builder becomes available) or false when there is no newer version of the form available. You may also return a Promise that resolves with the result.

tip

See the Subforms guide for more information.