The SDON Cookbook

3/17 Page

Defining Shape Properties with SDON

To make diagrams easy to generate, you won't have to guess how big to make your shape for your diagram. The shapes are sized automatically using SmartDraw's built-in intelligence.

By default a shape is 1.5" wide x 0.75" tall. This is its minimum size. You can place text, tables and other shapes inside a shape. The shape will automatically grow to accommodate its contents.

The way a shape grows to accommodate more text than will fit is determined by its "TextGrow" property. This can be any of the following values:

  • Vertical: The shape grows vertically to accommodate more text.
  • Horizontal: The shape grows horizontally to accommodate more text.
  • Proportional: The shape grows proportionally to maintain its aspect ratio to accommodate more text.

If the property is not defined, the shape will grow vertically by default.

Shape growing

ShapeContainers grow to contain their child shapes plus a border of empty space that is 0.5" by default.

Shapes that contain tables grow to exactly fit their tables. The text in table cells grow the cells based on the TextGrow property for the shape.

If necessary, the minimum size for a shape can also be overridden. Using the MinWidth and MinHeight properties.

Changing the Appearance of Shapes

The first thing to understand about controlling the way a shape is drawn using SDON is that you don't need to! There are smart default values set by SmartDraw. You only need to worry about the properties of the shape, if you'd like something other than the default values.

When the SmartDraw formatting engine generates a diagram it uses a SmartDraw template.

You can control which template is used with the "Template" command, but by default the blank diagram template is used. The template has defaults for all the properties of a newly created shape: color, font, border thickness, and so on.

Because of this, no properties need be defined to create a shape using SDON. The empty object {} is sufficient to add a shape with defaults that match those specified by the template. However, you can override these defaults by specifying property values explicitly.

The shape defined as {} creates the following object on the page:

  • a rectangle
  • 1.5 inches wide and 0.75 inches tall
  • filled with blue
  • has a one pixel dark gray border
  • has no text
SDON shape

The way to change the appearance of a shape from the default is to add properties to the Shape object. For example, you can choose a fill color.

{
   "FillColor": "#FFCC66"
}
SDON red filled box

You can define a border color and thickness.

{
    "LineThick": "4",
    "LineColor": "#CC3333"
}
SDON border box

You can also add text to the shape with a "Label" property.

{
    "Label": "This is a text label"
}
SDON shape with label

The font can be controlled with additional properties like size, style, and weight.

{
    "Label": "This is a text label",
    "TextSize": "18",
    "TextItalic": "True"
}
SDON styled text

You can combine all these properties to fully customize a shape's appearance.

{
    "Label": "This is a text label",
    "TextSize": "18",
    "TextItalic": "True",
    "FillColor": "#FFCC66",
    "LineThick": "4",
    "LineColor": "#CC3333"
}
SDON red box with label

Subdividing Shapes

A shape doesn't have to be restricted to a single fill color or one label. You can divide a shape up into a rows and columns using a table.

You can add a table to a shape object with just a few commands.

{
    Table: {
        "Rows": "2",
        "Columns": "3"
    }
}
SDON rows

Each cell in a table, behaves like an individual shape. It can have its own label, fill color, and so on.

{
    Table: {
        "Rows": "2",
        "Columns": "3",
        "Cells": [{
            "Row": "1",
            "Column": "1",
            "Label": "This is a cell label"
        }, {
            "Row": "2",
            "Column": "2",
            "FillColor": "#FFCC66"
        }]
    }
}
SDON rows with red

You can join cells to make more flexible arrangements. You can join across columns too.

{
    Table: {
        "Rows": "2",
        "Columns": "3",
        "Join": {
            "Row": "1",
            "Column": "1",
            "N": "1"
        }
    }
}
SDON combine cells

Using Different Shape Styles

The property "ShapeType" controls the outline of the shape. There are several built-in shape types:

  • Rounded Rectangle (RRect)
  • Circle
  • Oval
  • Square
  • Rectangle (Rect)
  • Diamond
{
    "ShapeType": "Oval",
    "Label": "This is an oval"
}
SDON oval

In addition to the built-in shape types, you can use any SmartDraw symbol as a shape by defining a "Symbols" array in your SDON object.

"Symbols": [{
    "Name": "Cloud",
    "ID": "368d31f5-f374-48fe-8b29-11e1a43e4c8a"
}], {
    "ShapeType": "Cloud",
    "Label": "Cloud Shape"
}
SDON cloud shape

There can be as many symbols defined in your symbols array as you wish. Each will have to have a name that will also be the new value for "ShapeType".

The ID of a symbol is its SmartDraw ID. The right click menu for a symbol in the SmartDraw interface has a command to copy the symbol ID to the clipboard. Just copy the ID and paste it into your symbols array.

You can use any of the 34,000+ SmartDraw symbols available in SmartDraw

Setting Up a New Default

If you find a style you like and want the same non-default look for all of the shapes in your diagram, there's a way to redefine the defaults for your diagram to avoid explicitly adding overrides to each of potentially hundreds of shapes.

There are two ways to define defaults:

  • Create a root shape whose properties will be inherited by all the children of that shape
  • Explicitly define a "DefaultShape" style for a ShapeConnector

Changing the Root Shape

The first shape in the SDON object (called the "root shape") lets you set the appearance of all of the shapes in a diagram that follow. Any properties you override for the root shape are passed down to all if its children. You can define the root shape to be red with a green border and all of the remaining shapes would inherit these properties.

{
    "Shape": {
        "Label": "This is a text label",
        "TextSize": "18",
        "TextItalic": "True",
        "FillColor": "#FF0000",
        "LineThick": "4",
        "LineColor": "#00FF00",
        "ShapeConnector": [{
            "ShapeConnectorType": "Hierarchy",
            "DefaultShape": {
                "FillColor": "#FFFFFF",
                "TextUnderline": "true"
            },
            {
                "Shapes": [{
                    "Label": "Child Shape"
                }, {}]
            }
        }]
    }
}
SDON change root shape

Defining a Default Shape

A ShapeConnector can also have a property called DefaultShape. This defines defaults for any properties included for all the shapes on the connector. The defaults for shapes on a ShapeConnector is the union of the root shape and the DefaultShape.

Shapes on child ShapeConnectors inherit the defaults from their parent shapes. Each ShapeConnector may override specific properties for the shapes on the connectors and their children.

Individual shapes can always override the defaults inherited from the template, root shape and ShapeDefault.

This script uses a DefaultShape to change the color of shapes on the connector to white.

{
    "Shape": {
        "Label": "This is a text label",
        "TextSize": "18",
        "TextItalic": "True",
        "FillColor": "#FF0000",
        "LineThick": "4",
        "LineColor": "#00FF00",
        "ShapeConnector": [{
            "ShapeConnectorType": "Hierarchy",
            "DefaultShape": {
                "FillColor": "#FFFFFF",
                "TextUnderline": "true"
            },
            {
                "Shapes": [{
                    "Label": "Child Shape"
                }, {}]
            }
        }]
    }
}
SDON change default shape

Default Properties for Shape Containers

Default properties include tables. Define a table for the root shape (or DefaultShape) and it is inherited by all the child shapes too.

The shapes inside a ShapeContainer inherit the properties of the ShapeContainer shape. ShapeContainers may also have a DefaultShape object that applies defaults to all of the shapes in the container (and their children).

Here's a very simple ShapeContainer script:

{
    "Shape": {
        "ShapeContainer": {
            "Shapes": [{}, {}]
        }
    }
}
SDON shapes

This creates two shapes inside a parent shape. Note that the parent shape is transparent. By default all shapes that are parents of a ShapeContainer are transparent unless you specifically set the FillColor to something else.

If we set the border of the ShapeContainer shape, its children inherit it.

{
    "Shape": {
        "LineThick": "4",
        "LineColor": "#CC3333",
        "ShapeContainer": {
            "Shapes": [{}, {}]
        }
    }
}
SDON shapes with red borders

You can also define DefaultShape.

{
    "Shape": {
        "LineThick": "4",
        "LineColor": "#00FF00",
        "ShapeContainer": {
            "DefaultShape": {
                "LineColor": "#0000FF",
                "FillColor": "#FF0000"
            },
            "Shapes": [{}, {}]
        }
    }
}
SDON shapes with blue borders

Defaults are not passed on from tables to the shapes inside cells. The shape in a cell behaves as a new root shape.

Adding a Hyperlink to a Shape

There are two ways to add a hyperlink to a shape: as a text label that's the usual blue underline or a hyperlink icon in a shape.

Text Hyperlink

Setting TextHyperlink to a URL makes a text label a hyperlink (and adds a blue underline style). Clicking on the text label will open the URL.

"TextHyperlink": "https://www.google.com"
SDON text hyperlink

Hyperlink Icon

Setting Hyperlink to a URL places a hyperlink icon in the bottom right of the shape. Clicking on the icon will open the URL.

"Hyperlink": "https://www.google.com"
SDON text hyperlink

Displaying an Image in a Shape

To display image to a shape use the "url" property:

"Shape": {
    "Image":{"url":"https://wcs.smartdraw.com/working-smarter/img/how-to-write-a-desktop-quality-cloud-app.png?bn=1510011133"}
}

This script creates this diagram:

{
    "Shape": {
        "ShapeConnector": [{
            "Shapes": [{
                "Image":{"url":"https://wcs.smartdraw.com/working-smarter/img/how-to-write-a-desktop-quality-cloud-app.png?bn=1510011133"}
            }, {}]
        }]
    }
}
SDON image shape
3/17 Page