Builder   Edit

npm downloads Join the community on Spectrum

Showing you the flow

You use the graphical builder to create and edit smart forms with logic and conditional flows in 2D on a self-organizing drawing board. The builder 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 builder comes in two flavors:

  • Stand-alone CLI tool to run the builder locally from your command line;
  • JavaScript library to integrate the builder 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 builder
$ npm i tripetto -g

# Start editing a form
$ tripetto form.json

Concepts   Edit

The builder 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 builder. 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 builder 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 builder, tidiness becomes key. We didn’t want you to have to worry about this, and so we taught the builder 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 builder. 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 builder 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 runner, 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 runner implementation. For this reason, Tripetto takes a flexible approach to the available building blocks in the builder.

In other words, you decide which building blocks you want to use in the builder and runner. 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 builder 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 builder 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 builder 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 runner 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 builder 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 runner in a website or application, or when building and testing custom blocks for Tripetto.

Installation   Edit

To be able use the builder, 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 builder 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 builder   Edit

By default, the builder loads no blocks. So you need to configure the builder in order to load the blocks you want. There are three methods for configuring the available blocks. In all cases an array with block package names needs to be supplied. You can find a list of available blocks here.

Method 1: Locally using an npm package file

If you start the builder 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 builder as a package dependency, so you could distribute the builder 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 builder 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 builder 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 builder 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 builder 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 builder package;
  5. package.json in the installation directory of the builder 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 builder 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 builder package itself and should therefore not be altered. Changes will be lost when the builder package is updated.

{
  "name": "my-builder-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 builder 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 builder at startup.  
--help Shows help information.  

Library   Edit

For a seamless integration in your project

When you want to seamlessly integrate the Tripetto builder 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 builder 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 builder with a simple command:
import { Builder } from "tripetto";

// Open the builder directly
Builder.open();

// Or create an instance first
const builder = new Builder();

builder.open();
  • Depending on your specific project configuration the ES6 or ES5 version of the builder 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 builder library -->
        <script src="https://unpkg.com/tripetto"></script>

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

Try the demo View the code

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

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

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

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

Loading and saving form definitions   Edit

Loading a form definition

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

import { Builder } from "tripetto";

const definition = // Supply your form definition here

// Open the builder for the definition
Builder.open(definition);

Saving or retrieving a form definition

To retrieve the definition back from the builder, 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 { Builder, IDefinition } from "tripetto";

const builder = new Builder.open();

// Open the builder and listen for the `OnSave` event
builder.onSave = (definition: IDefinition) => 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 { Builder } from "tripetto";

const builder = new Builder.open();

// Open the builder and monitor for changes using the `OnChange` event
builder.onChange = (definition: IDefinition) => console.dir(definition);

Builder options   Edit

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

import { Builder } from "tripetto";

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

// Or supply options directly to open method
Builder.open(undefined, {
    // Options here
});
import { Builder, IDefinition } from "tripetto";

const builder = new Builder({
  element: document.getElementById("Custom"),
  onChange: (d: IDefinition) => console.dir(d),
  disableSaveButton: true
});

builder.open();

Function reference   Edit

An Builder instance exposes the following properties and methods:

Builder.open(definition, properties): Builder

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

Arguments

definition
Specifies the form definition to load (supply undefined to open an empty one).
properties
Specifies the builder configuration.
constructor(properties): Builder

Creates a new builder instance.

Arguments

properties
Specifies the builder configuration.
definition

Sets or retrieves the form definition.

onLoad

Invoked when the builder is loaded.

onReady

Invoked when the builder is ready to use.

onOpen

Invoked when the builder 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): Builder

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

Arguments

definition
Specifies the form definition to load (optional).
resize(): Builder

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

load(definition): Builder

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

Arguments

definition
Specifies the form definition to load.
restore(): Builder

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

save(): IDefinition | undefined

Saves the form definition and returns it.

edit(): Builder

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

clear(): Builder

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

close(): Builder

Closes the builder. Returns a reference to the builder 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 { Builder } from "tripetto";

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

// Open the builder
Builder.open();

Method 2: Write your own blocks

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

import { Builder, NodeBlock, block } from "tripetto";

// Build a custom block
@block({
  type: "node",
  identifier: "ExampleBlock",
  label: "Example block",
  icon: "icon.svg"
})
export class Example extends NodeBlock {
  ...
}

// Open the builder
Builder.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 builder, 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 builder 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.Builder.open();
        </script>
    </body>
</html>

Notes   Edit

  • If you host the builder in a custom HTML element (using the element option), you should notify the builder 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 Builder-instance. This way the builder can adapt to the new viewport. If you don’t supply a custom element, the builder is placed under the body element and it will detect a dimension change automatically.
import { Builder } from "tripetto";

const builder = new Builder();

// Upon window resize notify the builder
window.addEventListener("resize", () => builder.resize());
window.addEventListener("orientationchange", () => builder.resize());

Live demo   Edit

See the Pen Tripetto builder 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 builder 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 builder? Report them here.

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