VisualScript SDK

The VisualScript SDK provides an object model that allows a developer to build a VisualScript document without using JSON.

Using the SDK is strongly recommended because it eliminates the possibility of introducing formatting and syntax errors.

Three versions of the SDK are available: JavaScript, C# and Java. The JavaScript SDK is automatically included in any VisualScript app you write using the built-in a Script Editor (in SmartDraw or VisualScript Studio). The C# and Java versions are used in applications that use a REST endpoint to generate VisualScript or any self-hosted Extension built outside SmartDraw. The documentation below uses the JavaScript version syntax, but the C# and Java versions are (except for language differences) identical.

VisualScript Object Classes

The VisualScript SDK provides classes that match the VisualScript object model. Each class will have methods that set properties and add it to any existing shapes. These methods are explored in detail on the pages for each class.

A table of shape data.

The VisualScript document that is rendered as a visual. All other instances of classes are contained within a document.

This is a class derived from VS.Document() that is specific to rendering a Gantt chart. A Gantt chart can only be rendered as part of a GanttDocument and there can only be one Gantt chart per document.

A line that connects the sides of two arbitrary shapes.

A VisualScript Shape. Each document has one shape that is the parent of all other shapes on the page.

A special arrangement of shapes connected by lines. ShapeConnectors can arrange shapes in a flow arrangement or several tree arrangements.

A special arrangement of shapes in rows and columns not explicitly connected by lines.

A grid arrangement of cells inside a shape.

A specialized grid-like arrangement inside a shape that forms a timeline.

A borderless shape that contains text that is centered above the visual forming a title.

Using the VisualScript SDK

The VisualScript SDK is used to build a VisualScript document. Each visual created with VisualScript is a single VisualScript document.

To create a document, create an instance of the VS.Document Class.

myDocument=new VS.Document();

Every VisualScript document has a single shape that is the parent of all other shapes and lines in the document. Creating a document also creates this shape. You get this shape with the document GetTheShape() method:

theShape=myDocument.GetTheShape();

The rest of the document is created by adding objects to this parent object using the Add class of methods.

VisualScript Object Class Methods

The VisualScript object classes have methods that set properties for the shape, add the shape to an existing object, or get properties:

Property Setting Methods

Property setters set the properties of an instance of a class. They always return the instance being set. This lets you chain calls to them as follows:

myShape.SetTextColor("#FF00FF").SetTextFont("Arial").SetFillColor("#00FF00")

There are many methods that set the color of a property. These pass a "color" variable. A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method.

Add Methods

Almost all the VisualScript classes are created by adding them to an existing object. For example a ShapeConnector is added to a parent shape as a specific type:

myShapeConnector=myShape.AddShapeConnector(myShapeConnectorType)

The "Add" methods all return the object added. You can then call property setters for this new object.

This is a list of typical Add methods

  • AddShapeConnector()
  • AddShapeContainer()
  • AddTable()
  • AddTimeline()
  • AddShape()

Property Getters

With one exception (document.GetTheShape) there are no Property Getters. They are not needed. The only reason you would need getters is if you attempt to use the VisualScript document to organize your data. This is not a good practice. Organize your data independently of VisualScript and then translate your data model into VisualScript.

Defaults

Virtually every property of a VisualScript object has default settings. You can create a Shape, a ShapeConnector, a ShapeContainer, a Table and so on with zero or minimal parameters. Colors, font, line thickness and other properties adopt the defaults of the visual template used to display them.

The following calls using the SDK produce this simple tree:

  • var myDocument=new VS.Document();
  • var theShape=myDocument.GetTheShape();
  • var myConnector=theShape.AddShapeConnector();
  • myConnector.AddShape();
  • myConnector.AddShape();
  • var VSjson=myDocument.toJSON();
  • // call to render the VSjson.
Simple org chart

Inheritance

The properties of the parent shape of a ShapeConnector are inherited by the shapes added to the ShapeConnector. For example, if the parent shape is assigned a border thickness of 4, all of the shapes added to its ShapeConnectors will also have a border thickness of 4 by default.The ShapeConnector itself has a "DefaultShape" property that defines a set of defaults for shapes added to it. The actual default used for shapes added is the union of the parent shape and the DefaultShape. Finally, individual shapes can override any property for that shape alone.

The key takeaway from this is that if you want all of the shapes in a hierarchy of ShapeConnectors to look the same, all you need to do is to set the properties of the parent shape and the remaining shapes will inherit the same look without having to explicitly set their properties.

There are two exceptions to this.

ShapeContainers work in similar way, with the exception that the FillColor property of the parent shape of the ShapeContainer is not inherited by shapes added to it. This is because the FillColor of a the parent of ShapeContainer is set to "None" (transparent) by default unless specifically overridden.

Shapes added to table cells do not inherit properties from the parent shape of the table, since this often has very different properties than what would be desirable for a shape added to a cell.

More Details

The VisualScript Cookbook describes the building blocks of VisualScript (the ingredients) and shows examples of how to use them to build each type of visual: trees, flows, and so on using the SDK. (the recipes).