Building FormIt JavaScript Plugins

Learn How to Build, 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 (First time plugin developers)...

Jump to (Advanced users)...

Useful Links

Your first plugin from the Plugin Playground

If you're building your first FormIt plugin, the Plugin Playground is a great place to start. Write, test, debug, and view your plugin directly inside FormIt for Web or Windows, then publish instantly to GitHub for others to try.

Learn how to use the Plugin Playground

Plugin Playground

Setting Up Your Environment

Plugin development is supported in FormIt for Windows and FormIt for Web.

Get the Source Code

Start a Web Server

FormIt for Windows

FormIt for Windows only requires a simple HTTP server to host plugins on a local web server.

An HTTP server that works well is npm's http-server, which you can install by:

Verify the Web Server

FormIt for Web

Developing on FormIt Web requires an HTTPS server for local debugging.

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

Before the HTTPS server can be run, OpenSSL must be installed and configured. Instructions to install OpenSSL are located here.

Open a command prompt to the directory above where the files that need served. This example assumes the FormItExamplePlugins and FormItWorkflowPlugins repos have been cloned locally. This is a directory listing of where to start the server.


                Directory of c:\git\FormIt3D
                04/09/2020  02:00 PM	<DIR>      	.
                04/09/2020  02:00 PM	<DIR>      	..
                04/09/2020  01:46 PM	1,228 cert.pem
                01/24/2020  12:03 PM	<DIR>      	FormItExamplePlugins
                12/24/2019  02:43 PM	<DIR>      	FormItWorkflowPlugins
                04/09/2020  01:44 PM	1,732 key.pem
                               2 File(s)      	2,960 bytes
                               4 Dir(s)  167,606,239,232 bytes free
            

Run the following OpenSSL command from the directory that the HTTPS server needs to server the files. Note: Replace [OPENSSL_INSTALL_DIR] with the directory where openssl.exe lives.

[OPENSSL_INSTALL_DIR]\OpenSSL-Win64\bin\openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
            

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

Configuring FormIt Web

Now open FormIt Web

Open the browser’s DevTools (F12) in the FormIt Web page. In this new DevTools view, go to Application tab/Service Workers and enable Bypass for network:

Bypass for network

And also click the Unregister link:

Unregister

Try loading a plugin from the local repo in the DevTools console input:

Console Input

Note: Once all these steps are working, all that will need to be done to work on local plugins is to start the server in the correct location:

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 v17.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]",
    "PluginType": "[PluginType]"
    "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",
    "PluginType": "Toolbar",
    "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!",
    "PluginType": "Panel",
    "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.

Using a single manifest file to create panel and toolbar plugins

{
    "PluginName": "Name...",
    "PluginDescription": "Description...",
    "ToolbarEntry": "index.html", <-- This is the "main entry" used to load/define all code used by your toolbar buttons
    "ToolbarButtons": [ <-- Contains an entry for each toolbar button
        {
            "iconText": "TB",
            "iconURL": "circle.png",
            "command": "window.AlertFormItVersion" <-- Javascript that will run in the document defined by ToolbarEntry
        },
        {
            "iconText": "CB",
            "iconURL": "block.png",
            "command": "window.CreateBlock"
        }
    ],
    "Panel": "panel.html", <-- Panel entry point
    "PanelIcon": "block.png" <-- Icon for your panel button
}
        
See ToolbarPanelAsync for a working example. Note that this has only been tested using FormIt's async APIs.

Versioning Plugins (Optional step)

As you continue to develop and update your plugin, it is possible that you will want to version your plugin. The most probable reason for implempenting plugin versioning is because FormIt's APIs can change between versions. You'll want to update your plugin to make use of newer APIs, but also keep your plugin working for older FormIt clients.

Starting with FormIt v18.0, to implement versioning follow some simple steps:

versions.json should have the following structure:

            [
                {
                    "version":{
                        "major":18,
                        "minor":0
                    },
                    "path":"myV18Path"
                },
                {
                    "version":{
                        "major":18,
                        "minor":1
                    },
                    "path":"myV18.1Path"
                }
            ]
            

It is also possible to use git branches/tags/commits for your paths. Those details won't be covered here, but it's enitrely possible to separate your plugins versions this way.

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");.

To test how a plugin or a repository will appear in the Plugin Manager, see Hosting Plugins.

Debugging Plugins

FormIt plugins utilize two distinct JavaScript engines: one in the panel displaying the HTML, and another engine in the FormIt client, which can make calls to FormIt and its geometry kernel. These JavaScript engines are in two different processes.

Client-Side (FormIt) Debugging

To debug in FormIt-side code, which applies to both toolbar- and panel-based plugins, you can add a line in the code to pop the desktop application's built-in JS debugger:

Web-Side (HTML) Debugging

Panel-based FormIt plugins offer HTML-based UI debugging, since the panels are fundamentally HTML websites with styling and scripts.

To debug HTML-side code for plugins built into a panel, including scripts and styling:

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!

Hosting Your Repo + Plugins on GitHub

{
  "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.

Previewing Your Plugin with the Plugin Manager

To preview how your hosted repo/plugins would appear in the Plugin Manager (updated title, description, etc) before it's pushed to GitHub, you'll need to clone the FormItExamplePlugins repo and host the Plugin Manager locally.

Due to restrictions with mixed HTTP and HTTPS content, you cannot use the production version of the Plugin Manager with a locally-hosted version of your plugin.

Once you've cloned the FormitExamplePlugins repo above, start a local server in the folder containing the FormItExamplePlugins folder. Then, enter the following in the Script Editor in FormIt for Windows, select the text, and hit the "Run Selected" button:

Then, you can paste your repo URL (in our example, http://localhost:8080/Joe) into the box at the top of the Plugin Manager, and hit the (+) button to add your locally-hosted repository to the Plugin Manager.

If nothing happens, check that your server is running where you expect it to, and that the URL is pointing to the correct folder relative to your server.

Force Clearing the Web Cache for .JSON Files

If you modify the title or description inside the manifest.json file for a plugin or repo, you may need to force clear the cache in FormIt for Windows to see those changes take effect the next time you reload the Plugin Manager.

FormIt for Windows stores its web cache here:

To delete the web cache, simply delete the "cache" folder above, then reload the Plugin Manager to see the updated titles and descriptions.

Publishing a plugin

If you created the plugin with the Plugin Playground, you can publish your plugin with the bullhorn icon.

publish

If you created the plugin without the Plugin Playground, you can publish your plugin by:

If you'd like your plugin to appear under the list of recommended plugins in the Plugin Manager, add an additional topic to your repository, formit-plugin-recommended. The FormIt team will then review your plugin.

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.