The VSON Cookbook

Drawing Lines with VSON

VSON relies on some simple, rule-based mechanisms to connect shapes so you can generate even complex diagrams with just a few lines of markup. There are two basic ways you can connect shapes. One uses the ShapeConnector to connect shapes in a hierarchical diagram like an org chart, decision tree, or mind map. The other is a single line called a "return" that can connect any two shapes in a free-form way. This is useful for flowcharts, but can be used for any type of diagram.

Using ShapeConnectors

Lines connecting shapes in tree or flow arrangements are drawn automatically by ShapeConnector objects. The thickness, pattern and color of these lines are the default for the template or can be defined explicitly on the ShapeConnector.

At a basic level, a simple hierarchy is very easy to create.

{
  "Version": "1.0",
  "Template": "OrgChart",
  "McpGenerated": true,
  "KeepDocument": true,
  "Shape": {
    "ID": 1,
    "Label": "Boss",
    "ShapeConnector": [
      {
        "ShapeConnectorType": "OrgChart",
        "Shapes": [
          { "ID": 2, "Label": "Direct Report A" },
          { "ID": 3, "Label": "Direct Report B" }
        ]
      }
    ]
  }
}

You can now specify additional styling if you want.

{
  "ShapeConnector": [
    {
      "ShapeConnectorType": "OrgChart",
      "LineColor": "#FF0000",
      "LineThick": 2,
      "Shapes": [
        { "ID": 2 },
        { "ID": 3 }
      ]
    }
  ]
}

The properties of a ShapeConnector are passed down to ShapeConnector objects on its child shapes.

{
  "ShapeConnector": [
    {
      "ShapeConnectorType": "OrgChart",
      "LineColor": "#FF0000",
      "Shapes": [
        {
          "ID": 2,
          "ShapeConnector": [
            { "ShapeConnectorType": "OrgChart", "Shapes": [{ "ID": 4 }, { "ID": 5 }] }
          ]
        },
        { "ID": 3 }
      ]
    }
  ]
}

Using Returns

A return can be used to connect any two shapes in any type of diagram. The most common use for a return line is to connect back to a previous shape in a flowchart.

{
  "Returns": [
    { "StartID": 3, "EndID": 1 }
  ]
}

The Returns array is defined at the root level of the VSON document. Each return object in the array must have a "StartID" and an "EndID" defined for the line to appear. These IDs are the IDs of the shapes that the line connects. The "ID" is an optional property of any shape:

{ "ID": 3, "Label": "End" }

The ID's are arbitrary but should be unique. If they are not unique, the first shape encountered with a particular ID will be the one that is used.

By default, returns connect to the bottom center of any shape they are attached to. You can control this with the optional parameters StartDirection and EndDirection. Four values are possible: "Top", "Bottom", "Left" and "Right". The default is "Bottom".

{
  "Returns": [
    { "StartID": 3, "EndID": 1, "StartDirection": "Top", "EndDirection": "Top" }
  ]
}

Returns also share the normal line appearance parameters with ShapeConnector objects such as thickness, color, and pattern.

Curved Returns

Setting Curved to "true" changes the shape of the return to a curved line.

{
  "Returns": [
    { "StartID": 3, "EndID": 1, "Curved": true }
  ]
}

Straight Returns

You can draw a straight line between two shapes by setting LineType to "Straight".

{
  "Returns": [
    { "StartID": 3, "EndID": 1, "LineType": "Straight" }
  ]
}

Placing Returns Behind a Shape

Returns are added to a visual after all of the shapes are added. Hence they lie above the shapes in the back-to-front order (z-order). You can control where a return is placed in the z-order by using the BehindID property, where the value is the ID assigned to a shape

This document creates a return that is in front of the shapes:

{
  "Returns": [
    { "StartID": 3, "EndID": 2 }
  ]
}

Adding BehindID moves the return line behind the shape with that ID.

{
  "Returns": [
    { "StartID": 3, "EndID": 2, "BehindID": 1 }
  ]
}

Using Arrowheads

By default, returns have a simple arrowhead at the end of the line. ShapeConnector objects have arrowheads by default if the template used specifies this. You can use StartArrow and EndArrow to specifically enforce the type of arrowhead used on a ShapeContainer or Return.

Setting an arrow to "0" turns off the arrowhead at the end of a line.

{
  "ShapeConnector": [
    {
      "ShapeConnectorType": "Flowchart",
      "EndArrow": 0,
      "Shapes": [{ "ID": 2 }, { "ID": 3 }]
    }
  ]
}

The arrowhead styles are determined by an array of arrowheads referenced by ID or name as shown below. The arrow "4" draws the line with the fifth arrowhead from the left in the top row of the standard selection of arrowheads:

The "6" arrow picks the first arrowhead in the second row and so on. For a detailed list of arrowhead styles available, see the VSON Markup Reference.

{
  "ShapeConnector": [
    {
      "ShapeConnectorType": "Flowchart",
      "StartArrow": 4,
      "EndArrow": 1,
      "Shapes": [{ "ID": 2 }, { "ID": 3 }]
    }
  ]
}

Adding Text to a Line

Both ShapeConnector lines and Return lines can show text labels.

The label for a ShapeContainer line that connects to a shape is specified in the definition of the Shape using the LineLabel property.

{
  "ShapeConnector": [
    {
      "ShapeConnectorType": "Flowchart",
      "Shapes": [
        { "ID": 2, "Label": "Approve", "LineLabel": "Yes" },
        { "ID": 3, "Label": "Deny",    "LineLabel": "No" }
      ]
    }
  ]
}

Note that the label appears on the line going into the shape.

For Returns, text is added using the Label method on the return object.

{
  "Returns": [
    { "StartID": 3, "EndID": 1, "Label": "Loop back" }
  ]
}

You can specify the font, size, color and style of the text on a line (ShapeConnector or Return).

{
  "Returns": [
    {
      "StartID": 3,
      "EndID": 1,
      "Label": "Loop back",
      "TextFont": "Arial",
      "TextSize": 12,
      "TextBold": true,
      "LineColor": "#FF0000"
    }
  ]
}