Editor Edit

npm downloads Join the community on Spectrum

Showing you the flow

You use the graphical editor to create and edit smart forms with logic and conditional flows in 2D on a self-organizing drawing board. The editor can run as a stand-alone CLI tool or be tightly integrated into your project. It works in any modern browser and with mouse, touch or pen. The complete structure of a form is stored in a JSON format; the form definition.

The editor comes in two flavors:

  • Stand-alone CLI tool to run the editor locally from your command line;
  • JavaScript library to integrate the editor into your project.

Try the demo View the code View the package

# TRY IT NOW!
# Just open your terminal or command prompt

# Install the Tripetto editor
$ npm i tripetto -g

# Start editing a form
$ tripetto form.json

Concepts Edit

The editor incorporates a number of solutions and principles to allow you to smoothly create and edit smart forms in 2D. Among many highly technical others, the most important visual ones are the drawing board, add-and-arrange, layout guidance, active allineation, smart zoom and feature cards. We’ll give you a high-level overview of these concepts here and provide some tips and tricks.

TL;DR Add and arrange building blocks on the drawing board to create your form. Layout guidance shows where to move and correctly drop building blocks, while active allineation continually handles the proper alignment of your arrangement. Use smart zoom to quickly go into and out of particular areas on the drawing board.

Drawing board

Forms are created by placing and arranging building blocks on the 2D drawing board in the editor. As the structure of the form expands beyond the edges of the screen, the drawing board can be shifted in any direction to view the desired part of the structure by simply dragging it with your mouse, finger or pen.

When the form expands beyond the edges of the screen, you can also use the smart zoom to quickly zoom in and out.

Add-and-arrange

As you add more building blocks to the form, you may also want to rearrange certain parts. You can move individual blocks or larger sub-structures at once. To do this, press-and-hold the relevant item for a brief moment to unlock and then move it. Release to drop and lock it again in the desired location.

Move items to an area out of view by dragging them up to the screen edge to shift the view to the desired point in the form structure.

Layout guidance

When you’re moving parts around, the editor visually guides you. It will show you where around your moving structure it could be correctly dropped and locked by temporarily drawing a guide with a duplicate structure in place and re-aligning all relevant structures.

Layout guides are doubly sticky. They both exactly follow the situational alignments and pull your moving structure precisely in there when you drop it. If you release something without a layout guide in sight, it will fall right back to where you picked it up.

Active allineation

As you expand your smart form in the editor, tidiness becomes key. We didn’t want you to have to worry about this, and so we taught the editor to understand what you’re doing. It actively aligns your form structure as you alter its arrangement. Nice and neat.

Smart zoom

This feature is also absolutely essential for the usability of the editor. It offers the following solutions to streamline navigation across the drawing board.

Zoom slider

Using the zoom slider to the side of the screen you can zoom in on and out of the area in the center of the screen by either moving the slider itself up and down or pressing the + and - buttons. On touchscreens, pinch to zoom also works.

Autosize buttons

Press the upper and lower ends of the button on the slider to instantly zoom all the way in on and out of the area in the center of the screen respectively. When your form structure exceeds the screen width, hit the middle of the button to fit it to the screen width.

Focus

Contrary to the zoom slider, this feature lets you swiftly zoom in on and out of a specific point on the screen without having to use the slider at all. Just double-press on the item you want to fully zoom in on. Repeat to zoom all the way out again.

Feature cards

You use feature cards inside the editor to manage the properties and settings of building blocks on the drawing board. Feature cards are designed specifically to not show what you don’t need in average scenarios and let you add only the desired additional settings options dynamically as you go. They make editing a breeze.

Blocks

Because we don’t impose any particular UI library or framework for the collector, we also don’t know which form element types (e.g. text input, checkbox, dropdown etc.) – the building blocks of a form – are available in your collector implementation. For this reason, Tripetto takes a flexible approach to the available building blocks in the editor.

In other words, you decide which building blocks you want to use in the editor and collector. We definitely offer a default set to choose from. But, you could of course decide to take a couple of them out. And you may also develop your own additional building blocks.

Form definitions Edit

The editor uses form definitions to store the complete structure of your form, including all the properties and settings of the blocks used. A form definition is a so called JSON structure stored in a plain UTF-8 encoded text format. The CLI version of the editor stores these form definitions as plain text files on your disk (you can give them any file name you like). In the library version of the editor it is up to you to decide what to do with the form definition data. Probably you want to store it on some sort of back-end.

The collector library is used to parse the form definitions into working forms in your website or application.

Command line tool Edit

For quick stand-alone form creation and testing

The CLI version of the editor is an easy to use command line tool that allows you to create and edit form definition files stored locally on your disk. This is ideal for developers implementing the collector in a website or application, or when building and testing custom blocks for Tripetto.

Installation Edit

To be able use the editor, you need to first install it using npm. And for that you’ll need Node.js. Assuming this is installed, you can enter the following command in your terminal/command prompt:

$ npm install tripetto -g

This will install the latest stable version. If you want to validate the installation, run the command tripetto --version after the installation. This should return the Tripetto version number.

If you don’t want to install Tripetto globally, omit the -g argument.

If you want to try the latest bleeding edge version, you can do so by adding the @next tag as follows: npm i tripetto@next -g. Use at your own risk. Could be unstable!

Using the CLI version Edit

You start the editor from the terminal/command prompt. It runs in any modern browser. You need to specify the filename of the form definition you want to create or edit. It can be any filename you like. The form definition contains the complete structure of your form.

Let’s say you want to create a new form definition with the filename demo.json. Run the following command to do so:

$ tripetto demo.json

This will create the file in the current working directory if it does not already exist there, or load the file if it is indeed available. A server instance at localhost port 3333 is then started. And probably your default browser will automatically open http://localhost:3333. If not, open the browser of your choice and navigate to this URL.

There are some additional command line options you can use. Please, find these here.

Configuring the editor Edit

By default, the editor comes with a predefined set of blocks. These blocks are automatically loaded when the editor starts. You can configure the editor to only use the blocks you want, or you can add additional blocks. There are three methods for configuring the available blocks. In all cases an array with block package names needs to be supplied.

Method 1: Locally using an npm package file

If you start the editor from a folder containing a package.json file, you can use this file to embed your configuration:

{
  "name": "your-package-name",
  "version": "0.0.1",
  "tripetto": {
    "blocks": [
      "block-a",
      "block-b"
    ]
  }
}

In this case you can also include the editor as a package dependency, so you could distribute the editor with your own package. The local instance will parse the configuration found in package.json and load the appropriate block packages.

Since the block packages are preferably npm packages, they can be included as package dependencies as well. This allows you to create bundled packages that contain the editor with a complete set of block packages.

An example package file is displayed to the right (or a bit further down, if you’re reading this on a device with limited screen width).

You can choose to make the specified block packages available in the same local folder as the configuration, or install the block packages globally.

Method 2: Locally using a configuration file

If you don’t want to pollute your package.json file or you are not using the editor from within a package, you can create a separate configuration file named tripetto.json with the following structure:

{
  "blocks": [
    "block-a",
    "block-b"
  ]
}

When the editor is started from a folder containing a tripetto.json file, this configuration will be parsed.

You can choose to make the specified block packages available in the same local folder as the configuration, or install the block packages globally.

Method 3: Globally

If you want to specify blocks globally, create a file in the user/home folder ~/tripetto.json with the following structure:

{
  "blocks": [
    "block-a",
    "block-b"
  ]
}

Since the configuration is global, the block packages should also be globally installed. Otherwise the editor can’t find the supplied block packages.

Configuration loading order

When Tripetto starts, it tries to load any configuration files in the following order:

  1. tripetto.json in the current working directory;
  2. package.json in the current working directory;
  3. ~/tripetto.json in the user/home folder;
  4. tripetto.json in the installation directory of the editor package;
  5. package.json in the installation directory of the editor package.

Stop further loading

You can stop further loading of configuration files (and thus blocks) by setting the property noFurtherLoading to true:

{
  "name": "your-package-name",
  "version": "0.0.1",
  "tripetto": {
    "blocks": [
      "block-a",
      "block-b"
    ],
    "noFurtherLoading": true
  }
}

As soon the editor hits a configuration file that has this option enabled, the loading stops right after processing that file.

The configuration files mentioned in step 4 and 5 are included in the editor package itself and should therefore not be altered. Changes will be lost when the editor package is updated.

{
  "name": "my-editor-bundle",
  "version": "0.0.1",
  "tripetto": {
    "blocks": [
      "block-on-npm",
      "block-on-github"
    ],
    "noFurtherLoading": true
  },
  "dependencies": {
    "tripetto": "*",
    "block-on-npm": "^1.0.0",
    "block-on-github": "git+ssh://git@github.com/user/block.git"
  },
  "scripts": {
    "start": "tripetto ./example.json"
  }
}

Command line options Edit

The following command line options are available:

Parameter Explanation Default
--host Specifies a custom host name. localhost
--port Specifies a custom server port. 3333
--preview Specifies the preview URL.  
--silent Do not automatically open the editor in the default browser.  
--verbose Enables verbose logging (logs the loaded blocks).  
--language Specifies the language locale/translation to use. en
--version Shows the version.  
--tutorial Shows the tutorial dialog in the editor at startup.  
--help Shows help information.  

Library Edit

For a seamless integration in your project

When you want to seamlessly integrate the Tripetto editor into your own project, you need the JavaScript library to do so. Implementation is very easy. So let’s get this thing started right away!

Using the library in your project Edit

First you need to add the library to your project. There are multiple ways to do this, depending on your specific needs. The two most common are the following.

Method 1: Using npm

If you are familiar with npm, this is the preferred way to go. It allows you to use modern techniques like ES6 module syntax and code bundling (for example using webpack) and it has extensive TypeScript support.

  • First add the Tripetto editor package to your project’s devDependencies:
$ npm install tripetto -D
  • Next, import the appropriate symbols into your application (if you use TypeScript, the type information should work out-of-the-box) and you can invoke the editor with a simple command:
import { Editor } from "tripetto";

// Open the editor directly
Editor.Open();

// Or create an instance first
const editor = new Editor();

editor.Open();
  • Depending on your specific project configuration the ES6 or ES5 version of the editor might be used.

Method 2: Using a CDN

If you want to use a more classic approach, you can load the library from a CDN (or host a copy of the library yourself). In this example we use the unpkg CDN.

  • Add the library to your HTML page and you are ready to go:

Try the demo View the code

<html>
    <body>
        <!-- Load the Tripetto editor library -->
        <script src="https://unpkg.com/tripetto"></script>

        <!-- Fire it up! -->
        <script>
            Tripetto.Editor.Open();
        </script>
    </body>
</html>
  • Or use a custom element to host the editor:

Try the demo View the code

<html>
    <body>
        <!-- Load the Tripetto editor library -->
        <script src="https://unpkg.com/tripetto"></script>

        <!-- This div will host the editor -->
        <div id="CustomElement"></div>

        <!-- Fire it up! -->
        <script>
            // Configure a new editor instance
            const editor = new Tripetto.Editor({
                Element: document.getElementById("CustomElement")
            });

            // Open the editor
            editor.Open();
        </script>
    </body>
</html>

Loading and saving form definitions Edit

Loading a form definition

To open an editor with a form definition, all you need to do is supply that form definition to the Open method:

import { Editor } from "tripetto";

const definition = // Supply your form definition here

// Open the editor for the definition
Editor.Open(definition);

Saving or retrieving a form definition

To retrieve the definition back from the editor, you have two options:

  • Retrieve when the user clicks the save button

    Attach a listener to the OnSave event (this event is invoked when the user clicks the save button in the UI):

import { Editor } from "tripetto";

// Open the editor and listen for the `OnSave` event
Editor.Open().OnSave = (definition) => console.dir(definition);
  • Retrieve on each change

    You can also monitor for changes in the definition (if you want you can hide the save button from the UI).

import { Editor } from "tripetto";

// Open the editor and monitor for changes using the `OnChange` event
Editor.Open().OnChange = (definition) => console.dir(definition);

Editor options Edit

The editor accepts a range of options to customize its behavior. These options are constructed using an IEditorProperties object that can be supplied to the instance constructor or Open method as follows:

import { Editor } from "tripetto";

// Supply options on instance creation
const editor = new Editor({
    // Options here
});

// Or supply options directly to open method
Editor.Open(undefined, {
    // Options here
});

The following options are available (they are all optional):

Option Type Explanation
Element HTMLElement Host HTML element (the editor is displayed inside this element or the document body if omitted).
Fonts string Specifies the path to the folder with the static font files. This can be a relative path or an absolute URL.
Style IEditorStyle Contains the editor styles (can be used to create a custom skin). You need a commercial license for this.
Locale ILocale Specifies locale information for the desired locale. You can find all the available locales in the ./locales folder in the root of the editor package folder.
Translations ITranslation, ITranslation[] Optional translations for the editor and the blocks. The editor translations can be found in the ./translations folder in the root of the editor package folder.
Zoom string Specifies the initial zoom level (1:1, fit, fit-horizontal or fit-vertical). The default is fit.
DisableZoombar boolean Disables the zoombar.
DisableLogo boolean Disables the Tripetto logo in the navigation bar. You need a commercial license for this.
DisableSaveButton boolean Disables the save button in the navigation bar.
DisableRestoreButton boolean Disables the restore button in the navigation bar (true by default).
DisableClearButton boolean Disables the clear button in the navigation bar (true by default).
DisableEditButton boolean Disables the edit button in the navigation bar.
DisableCloseButton boolean Disables the close button in the navigation bar.
DisableTutorialButton boolean Disables the tutorial button in the navigation bar.
ShowTutorial boolean Specifies if the tutorial should be shown at startup.
PreviewURL string Specifies the URL of a preview page.
SupportURL string or false Specifies an URL to a help or support page (supply false to disable this button).
OnLoad (e: Editor) => void Invoked when the editor is loaded.
OnReady (e: Editor) => void Invoked when the editor is ready to use.
OnOpen (e: Editor) => void Invoked when the editor is opened.
OnSave (d: IDefinition, e: Editor) => void Invoked when the user clicks the save button (or when the Save() command is called).
OnChange (d: IDefinition, e: Editor) => void Invoked when a change occurs.
OnClose (e: Editor) => void Invoked when the editor is closed.
import { Editor } from "tripetto";

const editor = new Editor({
  Element: document.getElementById("Custom"),
  OnChange: (d) => console.dir(d),
  DisableSaveButton: true
});

editor.Open();

Function reference Edit

An Editor instance exposes the following properties and methods:

Editor.Open(definition, properties): Editor

Creates a new editor instance, opens it and returns a reference to it.

Parameters
definition
Specifies the form definition to load (supply undefined to open an empty one).
properties
Specifies the editor configuration.
constructor(properties): Editor

Creates a new editor instance.

Parameters
properties
Specifies the editor configuration.
Definition

Sets or retrieves the form definition.

OnLoad

Invoked when the editor is loaded.

OnReady

Invoked when the editor is ready to use.

OnOpen

Invoked when the editor is opened.

OnSave

Invoked when the definition is saved.

OnChange

Invoked when the definition is changed.

OnClose

Invoked when the definition is changed.

Open(definition): Editor

Opens the editor. Returns a reference to the editor instance.

Parameters
definition
Specifies the form definition to load (optional).
Resize(): Editor

Notifies the editor about a parent element resize. If you host the editor inside a custom element, you should invoke this method when the dimensions of the element are changed. This way the editor can adapt to the new viewport. Returns a reference to the editor instance.

Load(definition): Editor

Loads a form definition. Returns a reference to the editor instance.

Parameters
definition
Specifies the form definition to load.
Restore(): Editor

Restores to the last loaded or saved definition. Returns a reference to the editor instance.

Save(): IDefinition | undefined

Saves the form definition and returns it.

Edit(): Editor

Opens the definition edit form where the name of the form can be set. Returns a reference to the editor instance.

Clear(): Editor

Clears the form (creates a new empty one). Returns a reference to the editor instance.

Close(): Editor

Closes the editor. Returns a reference to the editor instance.

Working with blocks Edit

Tripetto allows you to use custom building blocks. Anyone can build blocks using our publicly available SDK. But how can you consume those blocks in your own application? Multiple options are available depending on your method of implementation.

Method 1: Using npm

  • First add the block packages to your project’s devDependencies:
$ npm install tripetto-block-text tripetto-block-checkbox -D
  • Next, simply import the blocks:
import { Editor } from "tripetto";

// Import blocks
import "tripetto-block-text";
import "tripetto-block-checkbox";

// Open the editor
Editor.Open();

Method 2: Write custom blocks

If you want to implement custom blocks, you can do this right within your project. For example:

import { ConditionCreateTemplates, Editor, NodeBlock, PropertiesEditor, node } from "tripetto";

// Build a custom block
@node("ExampleBlock", "Example block")
export class Example extends NodeBlock {
  public static readonly Icon = "icon.svg";
  public readonly Type = Example;

  public OnSlots(): void {}

  public OnProperties(properties: PropertiesEditor): void {}

  public OnConditions(): ConditionCreateTemplates {
    return [];
  }
}

// Open the editor
Editor.Open();

More information on how to write blocks can be found here.

Method 3: Add scripts to HTML page

If you use a simple HTML page to implement the editor, you can simply load the blocks by adding them to the HTML page. For example:

Try the demo View the code

<html>
    <body>
        <!-- Load the Tripetto editor library -->
        <script src="https://unpkg.com/tripetto"></script>

        <!-- Load some blocks -->
        <script src="https://unpkg.com/tripetto-block-text"></script>
        <script src="https://unpkg.com/tripetto-block-checkbox"></script>

        <!-- Fire it up! -->
        <script>
            Tripetto.Editor.Open();
        </script>
    </body>
</html>

Notes Edit

  • If you host the editor in a custom HTML element (using the Element option), you should notify the editor when the dimensions of that element are changed (for example when the browser window is resized or when the display orientation is changed). To do so, you should invoke the Resize method on the Editor-instance. This way the editor can adapt to the new viewport. If you don’t supply a custom element, the editor is placed under the body element and it will detect a dimension change automatically.

Live demo Edit

See the Pen Tripetto editor with some blocks by Tripetto (@tripetto) on CodePen.

Translations Edit

Currently the following translations are available:

Locale Language
en English
nl Dutch

If you want to help us translating the Tripetto editor to other languages, you’re very welcome to! Download our POT file and start translating it. We use POEdit for this job, but you can use any other tool or service you like. Send us the translated PO file and we are more than happy to include it.

Make sure to include your name so we can give you the appropriate credits!

Download POT file

Issues Edit

Run into issues using the editor? Report them here.

Take a look at our support page for more support options.