Building FormIt JavaScript Plugins

Learn How to Assemble, Test, and Host Your Own Plugins

FormIt's JavaScript plugin infrastructure allows the creation of custom 3D workflows and bespoke modeling functionality, using a variety of UI types and a powerful API.

Jump to...

Useful Links

Setting Up Your Environment

Plugin development is currently limited to Windows OS environments.

Get the Source Code

Start a Web Server

Plugin files and directories need to be hosted on a web server for FormIt to load from.

A simple web server that works well is npm's http-server, which you can install by:

Verify the Web Server

Install an IDE

Write your code in an integrated development environment (IDE) that helps identify issues, correct syntax errors, and includes a terminal for running your local server.

A free IDE that works well for FormIt plugin development is Microsoft's Visual Studio Code.

Once installed:

Optionally start your server from the IDE

Now, you have the option of starting the server you installed previously right inside Visual Studio Code, instead of from a separate terminal window:

Setting Up FormIt

In order to test and build plugins, you'll need FormIt for Window v16.0 or later.

Enable Development Windows

Once toggled, the Script Editor and Script Output will appear at the bottom of the FormIt window.

Switch between the Script Editor and Script Output by using the buttons at the bottom.

You can also get both panels to show up side-by-side by clicking the button next to the "x" in the upper right corner to detach one of the panels, then drag and drop the panels next to each other:

Working With the Sample Plugins

If you've cloned the repositories and set up a web server from the previous steps, you can now get the local plugins to show up in FormIt.

You can load or install any of the plugins from the example repositories. For the purposes of this exercise, you'll install both a panel-based and toolbar-based plugin. We'll assume your npm http-server is running on port 8080 hosting both example repositories.

Load vs. Install:

Toolbar Plugin Sample

HTML Panel Plugin Sample

Modal + Modeless Dialog Plugin Sample

Dialog plugins are unique: they can only be loaded, not installed.

General Plugin Setup

FormIt plugins are comprised of a key core component called a manifest.json file. The manifest file is a JSON object that tells the FormIt infrastructure what files to fetch and what kind of plugin to create.

A manifest.json file has the following structure, but has additional properties depending on whether it's a toolbar or a panel-based plugin (see the following sections for more info):

{
    "PluginName" : "[PluginName]",
    "PluginDescription": "[PluginDescription]",
    "Scripts": [
        "PLUGINLOCATION/[script1].js",
        "PLUGINLOCATION/[script2].js",
        ...
        "PLUGINLOCATION/[scriptn].js"
    ]
}               

A typical plugin includes these JSON properties:

Start your plugin development by creating a manifest.json file in your plugin folder. Next, you'll need to decide if you are making a toolbar or panel-based plugin.

Note: the use of PLUGINLOCATION throughout the manifest.json file above is essential and also case sensitive. FormIt will replace PLUGINLOCATION with the server location for the plugin.

Creating a Toolbar Plugin

A toolbar-based plugin has a manifest.json file with the following structure:

{
    "PluginName": "Flip Along",
    "PluginDescription": "Creates a toolbar with X, Y, and Z buttons to quickly flip selected geometry in the direction of the selected axis.",
    "ToolbarURL": "PLUGINLOCATION/toolbar.json",
    "Scripts": [
        "PLUGINLOCATION/flipalong.js"
    ]
}               

In addition to the standard JSON properties, a toolbar-based plugin includes these special JSON properties:

After creating a manifest file like the one described above, you'll need to create the toolbar.json file which defines the toolbar buttons, their names, text, icons, and the onClick function assigned to each button. The toolbar's JSON file will have the following format:

{
    "name": "Flip Along Toolbar",
    "buttons": [
        {
            "name": "Flip Along X",
            "command": "FlipAlongPlugin.ButtonX",
            "iconText": "X",
            "iconURL": "[Icon URL]"
        },
        {
            "name": "Flip Along Y",
            "command": "FlipAlongPlugin.ButtonY",
            "iconText": "Y",
            "iconURL": "[Icon URL]"
        },
        {
            "name": "Flip Along Z",
            "command": "FlipAlongPlugin.ButtonZ",
            "iconText": "Z",
            "iconURL": "[Icon URL]"
        }
    ]
}               

The toolbar.json file includes these JSON properties:

After the buttons have all been defined in the toolbar.json file, the plugin is ready to go. If there are any additional JavaScript functions you would like to define, add them to the same folder as the manifest.json file and be sure to add the file reference to the "Scripts" field of the manifest file as well so that FormIt can find the files.

Creating an HTML Panel Plugin

A panel-based plugin that displays an HTML page has a manifest.json file with the following structure:

{
    "PluginName": "Hello Block!",
    "PluginDescription": "Creates a panel with an HTML form that allows dimensional input for a 3D block which will get generated at the world origin.",
    "Scripts": [
        "PLUGINLOCATION/block.js"
    ],
    "Panel": "PLUGINLOCATION/hello_block.html",
    "PanelIcon": "PLUGINLOCATION/hello_block.png"
}               

In addition to the standard JSON properties, a panel-based plugin includes these special JSON properties:

Once your HTML, CSS, and JavScript files are set up, you can begin testing your HTML panel plugin by loading it or installing it.

Testing Plugins

If your web server is running per the instructions above, you can test your in-progress plugins easily using the built-in Script Editor in FormIt for Windows:

We recommend using FormIt.LoadPlugin("URL"); when testing, which loads plugins temporarily for this session (they will disappear when FormIt is restarted). Once testing is complete, you can persist the plugin between sessions using FormIt.InstallPlugin("URL");.

Debugging Plugins

Panel-based FormIt plugins utilize two distinct JavaScript engines. One is in the panel displaying the HTML, and another engine which is built in to FormIt for Windows. These JavaScript engines are actually in two different processes.

To debug in FormIt-side code (for toolbars or panels), you can enter the following to pop the desktop application's built-in JS debugger:

To debug HTML-side code (for panels only), including scripts and styling:

First, add a required Windows Environment Variable to enable HTML debugging (first-time setup only):

Once you've added the required Environment Variable (first-time setup only), proceed based on the version of FormIt:

Learn more about Qt Web Engine Debugging and Profiling

Hosting Plugins

Built a useful plugin that you want to share? Host your repository on GitHub so others can install your plugins from the Plugin Manager!

{
  "RepoName": "Joe's Plugins",
  "Plugins": 
  [
  "MyFormItPlugin1",
  "MyFormItPlugin2"
  ]
}               

You should now be able to load your GitHub-hosted plugin repository in the Plugin Manager by entering its URL (for our example, https://github.com/Joe/JoesPlugins) in the box at the top and hitting the (+) button. Learn more about the Plugin Manager.

At this point, you can continue adding, modifying, and testing plugins locally, and when you're ready to publish, use GitHub Desktop to push your changes to your GitHub repo. Anyone consuming your repo and plugins will always get the latest code when they start FormIt.

Help With FormIt Plugins

Trying to use or build a plugin and running into issues? We're here to help. Use the links below to reach out and get support.