How to Write a JavaScript Extension

Extensions allow users to generate diagrams from data, skipping the drawing process. You can create your own custom extensions with some powerful built-in tools and share it with your team.

There are three ways to create your own extension:

  1. Use the built-in Javascript Editor and UI builder with lots of helper functions and built-in validation
  2. Create a program that translates data to VisualScript elsewhere and expose a REST endpoint for SmartDraw to access, but build the end-user UI inside SmartDraw
  3. Host your own extension code on your own server

The process for creating any extension follows the same pattern.

You will need to write a program that:

  1. Extracts data from a source based on user input
  2. Organizes the data into a form that can be represented visually (like a tree or a sequence of steps)
  3. Converts that model into VisualScript (ideally using the VisualScript SDK)
  4. Passes the VisualScript markup to SmartDraw to turn into a diagram

The JavaScript Extension is probably the simplest way to accomplish all these steps. It allows you to write your extension in JavaScript directly in your browser inside SmartDraw and create a simple UI to enter parameters with a UI Builder. The editor has built-in validation that will make sure you're using the SDK correctly. No server is needed to host any part of the extension.

Create an Extension with JavaScript

To create a new JavaScript Extension go to the Extensions folder in the SmartDraw Template Dialog and click on the "Create an Extension" icon. This presents the "Choose Extension Type" dialog:

Choose the JavaScript Extension option.

Choose the JavaScript Extension

Writing a Simple Extension

The JavaScript Extension will show you a work area where you can name your extension and write your code.

You must give your extension a name. The description you give the extension will show in the dialog a user sees when running the extension.

Name and code your extension

Let's go over writing a simple "Hello World" extension. The VisualScript SDK is already loaded in this editor so you can reference all the classes and methods in the SDK to generate valid VisualScript markup.

To learn more about the classes and methods available, read this detailed reference guide to the SDK.

Here's the script that we will be loaded by default to show you the most basic construction of an extension:

@method VisualScript
@param {String} paramString: A parameter string created by the parameter input form.
@param {Function} vsCompleteCallback: A function to call once the VisualScript is complete, triggers the creation of a document. Takes one parameter: (<string> VisualScript JSON)*/
function VisualScript(paramString, vsCompleteCallback)
{
var vs = new VS.Document();

var rootShape=vs.GetTheShape();


rootShape.SetLabel("Hello World. Parameter string: " + paramString);


var vsJSON = vs.toJSON();
vsCompleteCallback(vsJSON);
}


Passing Script Parameters

SmartDraw lets you define variables that will appear as fields in a form to an end user. This is called the UI Builder.

You define these variables in the Script Parameters section of the dialog.

These fields will capture a string to pass to a JavaScript function with field tokens that are replaced by their values.

Field tokens are defined with matching double curly brackets separated by commas:

{
"IssueID":"{{Issue}}",
"ProjectID":"{{Project}}"
}

Using this syntax for variables creates a form for the end user to input values. You can also set their defaults and provide a label and description.

Use the UI builder with the JavaScript extension

You can see what the end user form will look like by clicking the "Show Form Preview" button.

Use the UI builder with the JavaScript extension

Sharing Your Extension

Once you've completed your extension, click "Create Extension" and the JavaScript Extension will add a new icon to your Extensions folder with the name that you assigned to it. Once you've saved your extension, you can run it and add parameters to it for users to use as input fields. If you (as the author) click on your new extension icon, you'll return to the extension dialog that lets you edit the code and parameters. You can run it or edit the code or parameters.

You may also want to make this extension available for other users. You do this by sharing it with them.

Right click on the Extension icon and choose "Share". This copies a share URL to the clipboard. Paste this into an email and send it to anyone you want to be able to use it. If the user clicks on the link, the icon for the extension will appear in their Extensions dialog. When they run your extension, they won't see the code used to configure the extensions, they'll only see the UI you built for them.

Note that sharing is only allowed between users that share the same SmartDraw Enterprise Site License.

Share your extension

Running a Shared Extension

Anyone running a shared extension will see your icon, but they won't see the configuration dialog. They'll see the end user dialog you created in the UI Builder.

Running an extension