How to Write Your Own Extension

A SmartDraw extension is a web page hosted inside an iframe that produces SDON - SmartDraw Object Notation - and passes it to SmartDraw so that it can be rendered into a diagram. This tutorial will walk you through creating a very basic "Hello World" extension written in JavaScript. Once you master this, you can try creating a more complex server-side extension using our SDK.

Requirements:

  1. Knowledge of JavaScript sufficient to use the bridging library.
  2. Knowledge of HTML sufficient to write an HTML page that utilizes the bridging library.
  3. Ability to host a web page on a secure (https) connection.
  4. Basic understanding of SDON, SmartDraw's diagram mark up language based on JSON

Step 1: Get the Bridging Library

The bridging library is a tool that allows your extension to communicate with SmartDraw via iframe messaging. All of the functions exposed in the bridging library send a message to SmartDraw, which performs the requisted actions and passes a message back to your extension asynchronously. The response message will carry a payload of data (which varies based on the call being made). It will also deliver an error message if something goes wrong.

The object that is passed back and forth is always an instance of SDAPI.CrossWindowPluginMessage:

SDAPI.CrossWindowPluginMessage

/**Object for sending messages back and forth between iframes hosted on different domains.*/
SDAPI.CrossWindowPluginMessage = function ()
{   
    /**Anything. Any data to transport from one window to another.*/
    this.Payload = null;
    /**String. An error message sent by the parent iframe informing the child iframe that the operation failed and why.*/
    this.ErrorMessage = null;
};

To get the bridging library, click here. Learn more about the functions of the bridging library.

Step 2: Create an HTML Page for Your Extension

Once you have the bridging library, you can write an HTML page that produces SDON and passes it to SmartDraw. Below is the simplest possible example of a working extension. It will generate a diagram with a single shape that says "Hello World."

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>  
</head>
<body>
    <button onclick="go()">Generate SDON</button>
         
    <script src="https://cs1.smartdraw.com/assets/api/sdapi-v1.min.js"></script>
    <script type="text/javascript">
        var go = function ()
        {
            var sdon =
            {
               
                Shape:
                {
                    Label: "Hello World"
                }
            };
 
            SDAPI.SDON.SDONDone(sdon, function (crossWindowMessage)
            {
                if (crossWindowMessage.Payload === false)
                {
                    if (crossWindowMessage.ErrorMessage != null) console.log(crossWindowMessage.ErrorMessage);
                    return;
                }
 
                //if the call telling SmartDraw to create a diagram from the SDON or inject the SDON into the current diagram succeeded, there will be no callback
            });
        };
    </script>
</body>
</html>

The only call that needs to be made to get SmartDraw to produce a diagram from SDON is SDAPI.SDON.SDONDone. Simply pass this function a JSON string, an object, or a blob of SDON data as the first parameter and the bridging library will send it to the SmartDraw application, which will either create a document containing the SDON (if the extension is run from the template dialog) or will directly inject the SDON into the current document (if currently editing a diagram).

The code above will create a diagram that looks like this:

The most basic extension that makes a hello world shape

Save and Load A User's Settings via Your Extension

There is an additional feature of the bridging library that allows you to save and load a user's settings with an extension. The user's "settings" with an extension is an arbitrary string that can be anything you want. You can use it to persist data between uses of your extensions for your users. Below is a slightly more complicated example that has the option to set/get the user's settings:

Get/SetUserSettings

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>  
</head>
<body>
    <button onclick="setSettings()">Set Settings</button>
    <button onclick="getSettings()">Get Settings</button>
    <button onclick="go()">Generate SDON</button>
    <div>
        <textarea id="settings" style="height: 200px; width: 500px;"></textarea>
    </div>
         
    <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
    <script src="https://cs1.smartdraw.com/assets/api/sdapi-v1.min.js"></script>
 
    <script type="text/javascript">
        var settings = $("#settings");
         
        var setSettings = function ()
        {
            var currentSettings = settings.val();
            SDAPI.SDON.SetUserSettings(currentSettings, function (crossWindowMessage)
            {
                if (crossWindowMessage.Payload === false)
                {
                    if (crossWindowMessage.ErrorMessage != null) console.log(crossWindowMessage.ErrorMessage);
                }
                else
                {
                    alert("Set user settings to " + currentSettings);
                }
            });
        };
 
        var getSettings = function ()
        {
            SDAPI.SDON.GetUserSettings(function (crossWindowMessage)
            {
                if (crossWindowMessage.Payload == null)
                {
                    if (crossWindowMessage.ErrorMessage != null) console.log(crossWindowMessage.ErrorMessage);
                }
                else
                {
                    alert("Server returned user settings: " + crossWindowMessage.Payload);
                }
            });
        };
 
        var go = function ()
        {
            var sdon =
            {
                
                Shape:
                {
                    Label: "Hello World"
                }
            };
 
            SDAPI.SDON.SDONDone(sdon, function (crossWindowMessage)
            {
                if (crossWindowMessage.Payload === false)
                {
                    if (crossWindowMessage.ErrorMessage != null) console.log(crossWindowMessage.ErrorMessage);
                    return;
                }
 
                //if the call telling SmartDraw to create a diagram from the SDON or inject the SDON into the current diagram succeedes, there will be no callback.
            });
        };
 
    </script>
</body>
</html>

Note that all the functions in the bridging library are asynchronous and you must include a callback if you want to act on the completion of the operation.

Step 3: Add Your Extension to SmartDraw

Once you created your web page, you can use the Extension configuration modal to create a record of your extension in the SmartDraw UI.

First, click on the "Extensions" option under "New Document" on the left-hand side of the template dialog:

SmartDraw template dialog

Then click on the "Create Extension" tile under "Custom Extensions":

Create a new extension

This will bring up the Extension Configuration modal:

Extensions configuration modal

To create an extension, you must fill out the Extension Name field and the Extension Page URL field. The description and default settings are both optional.

The Extension Name must be unique to the creating user (the same user can't make two plugins with the same name, but two different users could make plugins with the same name).

The Extension Page URL must start with https:// in order to be valid. Extension urls starting with http:// may be blocked by your browser's security features (the SmartDraw app is always connected to a secure connection (https://), and browsers will show warnings or throw errors if you try and point an iframe at an insecure (http://) site). Beyond that restriction, any valid URL that your browser can resolve will work (i.e. your localhost if it's running with https).

The Extension Description is a note to you or your users on what your extension is, what it is supposed to do, and how to use it.

The Default Settings String is the fallback for calls to get a user's settings when the user has no existing settings. If you have never saved specific settings for a user of the plugin, the default settings will be returned if you call GetUserSettings.

Click "Save Extension" when you are done. In some environments, a Extension Share link field will appear - you can copy this link and send it to another person to share your plugin with them. They will be able to use it, but not edit or delete it.

Clicking "Delete Extension" will permanently delete the extension for all users who have access to it, including the owner.

Step 4: Run the Extension

Once you click "Save Extension" and close the extension configuration modal, a tile will appear in the Extensions section of the template dialog under Custom Extensions:

Your new extension will appear in the template dialog

Click on the tile to show your extension. In this example, we are using the simplest possible example of a working extension from above. Clicking on the tile brings up an iframe with your URL loaded into it:

Loaded extension

To run this extension, click the "Generate SDON" button. In this case, doing so will call SDAPI.SDON.SDONDone to be executed and it will hand SmartDraw some simple SDON. SmartDraw then creates a document and presents the user with a link to open the document they just created*. Click the link to open the new document in a new window.

Open SDON file

*If you're running an Extension in SmartDraw inside the Atlassian ecosystem, the new document will be opened immediately.

After clicking on the link or being redirected, you should see a box with "Hello World" written in it:

Visual created with our hello world extension

Debugging SDON and Your Extension in the Developer Tab

To help you debug your SDON or Extension, go to the "Developer" tab in the product.

Developer tab

Here you can import an SDON file to see how it renders and diagnose any issues.

You can also run extensions. Click "Extensions" then "Manage Extensions".

This will take you back to the configure extensions modal, except now it has a preview of your extension loaded so it can be run and tested repeatedly:

Extension preview

Note that when you run an extension from within the editor it will replace the contents of your current page with the diagram rendered from the SDON. Also note that the dialog will not close automatically in the editor, you need to call SDAPI.SDON.CloseDialog() to close the dialog.