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

To develop on FormIt Web, simply run the following command instead:

You can verify the web server in the same way as outlined above for Windows.

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, but 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.

Creating an Add-In

An Add-In is a plugin that also loads DLLs that expose new JavaScript APIs. To build DLLs that support FormIt, the FormIt API is needed. The FormIt API can be downloaded from the Autdesk Developers Network. A login is needed to access the download. Once logged in, the FormIt API is available under SOFTWARE.

An Add-In has access to the FormIt API and FormIt Modeling Kernel C++ API.

An add-in has the following structure-

            // FormIt looks for REGISTERAPIMETHODS to load new JS APIs
            REGISTERAPIMETHODS
            {
                // Declare new namespace for the new JS APIs
                REGISTERNAMESPACE("HelloDLL")
                // Create a JS API with no arguments
                APIMETHOD(HelloDLL, API1, "") {}
                // Create a JS API with 1 argument
                APIMETHOD(HelloDLL, API2, "arg1") {}
                // Create a JS API with 2 argument
                APIMETHOD(HelloDLL, API3, "arg1, arg2") {}
                ...
                ...
            }
        

To get the arguements into C++ variables use SCRIPTCONVERTER-

            // Create a JS API with 2 argument
            APIMETHOD(HelloDLL, API3, "arg1, arg2")
            {
                // NOTE: The arg names above ^^^^ have to match the args in the macros below.
                // arg1 expects a bool
                SCRIPTCONVERTER(bool, arg1);
                // arg2 expects an int
                SCRIPTCONVERTER(int, arg2);
                return JSON_UNDEFINED;
            }
        

Either JSON_UNDEFINED or any json object can be returned. Use to_json to convert your C++ variable to json-

            // Create a JS API with 2 argument
            APIMETHOD(HelloDLL, API3, "arg1, arg2")
            {
                // NOTE: The arg names above ^^^^ have to match the args in the macros below.
                // arg1 expects a bool
                SCRIPTCONVERTER(bool, arg1);
                // arg2 expects an int
                SCRIPTCONVERTER(int, arg2);

                std::string myValue = "Test";
                return to_json(myValue);
            }
        

Once the DLL is defining all the needed JS APIs, the plugin must tell FormIt what DLLs need loaded. This is done in the manifest.

        "DLLs" : ["PLUGINLOCATION/MyClass.dll", "PLUGINLOCATION/HelloDLL.dll"]
        

HelloAddIn is a working example that explains how to make an Add-In.

HelloWSMAddIn is a working example that explains how to make an Add-In with the FormIt Modeling Kernel C++ API.

Creating a Combined HTML Panel and Toolbar with One Manifest

With a single manifest.json, you can initialize both a toolbar and an HTML panel, offering a variety of UI types and tools, all loaded from the same directory.

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

Versioning Plugins

As you develop and update your plugin, at some point, you may need to version the code.

For example, FormIt's APIs may change between releases, and while you may want the new version of your plugin to use new FormIt or WSM APIs, you'd also like to keep the plugin working in older clients.

Starting with FormIt v18.0, you can implement versioning for your plugin in 3 simple steps:

Your versions.json should look like this:

        [
            {
                "version":{
                    "major":18,
                    "minor":0
                },
                "path":"v18_0"
            },
            {
                "version":{
                    "major":19,
                    "minor":1
                },
                "path":"v19_0"
            }
        ]
        

The above paths v18_0 and v19_0 must be valid subpaths from the root of your directory/repository.

A great way to handle this is to move your plugin code into subdirectories. Using the above versions.json, a directory structure would look like this:

It's also possible to use git branches/tags/commits for your paths.

If you're working with a pre-release or beta build of FormIt, and would like to test changes to a plugin that only works with the pre-release version:

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

Previewing Your Plugin with the Plugin Manager

To preview how your plugin would appear in the Plugin Manager (updated title, description, etc) before it's pushed to GitHub, you can paste the localhost URL into the box at the bottom of the Plugin Manager:

Then look for your plugin in the Installed section at the top:

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 "Default" folder above, then reload the Plugin Manager to see the updated titles and descriptions.

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

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

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

Having issues building or running plugins? Reach out to us on the FormIt forums.