The VSON Cookbook

Adding Text to Shapes in VSON

By default, shapes contain no text. Setting a Label on a shape causes a text label to appear in the shape by using the default font, text color, and alignment.

{
  "ID": 1,
  "Label": "Hello"
}

Just as the default values for properties like the FillColor of a shape can be overridden by explicitly defining values for them as part of the object record, defaults for text properties can be overridden as well.

Aligning Text in the Shape

The horizontal alignment is specified with the TextAlignH property ("left", "right", "center") and the vertical alignment is specified with the TextAlignV propriety ("top", "bottom", "middle").

{
  "ID": 1,
  "Label": "Left aligned",
  "TextAlignH": "left",
  "TextAlignV": "top"
}

Changing the Appearance of the Text

You can override the default text options with text properties on the shape. TextFont sets the name of the font, TextSize sets the size of the text in points, TextBold, TextItalic, and TextUnderline take boolean values that turn on or off bold, italic, and underline. TextColor sets the color. These properties all apply to the entire label.

{
  "ID": 1,
  "Label": "Hello",
  "TextFont": "Arial",
  "TextSize": 14,
  "TextBold": true,
  "TextColor": "#0000FF"
}

Controlling the Amount of Text Shown in a Shape or Table Cell with Truncate

When the label associated to a shape or a table cell is derived from data and may be longer than can comfortably fit inside the shape, you can truncate it. You do this using the Truncate property, which sets the number of characters after which the label is cut off with an ellipsis.

{
  "ID": 1,
  "Label": "An especially long label that should be truncated mid-sentence",
  "Truncate": 30
}

Showing Multiple Data Values in a Single Shape

When building a diagram from data, a shape often represents a data record and often data records have multiple fields, each with a different value.

The simplest approach is just to show one value that identifies the record in the shape. For example, in a flowchart of a workflow, show the name of the step in the shape as a Label. But what if you want to show two or more field values in a shape? One way to do this is using a table:

Using a Table to Show Multiple Values

Any shape can be subdivided into a table of cells by setting Rows, and Columns on a Table.

{
  "ID": 1,
  "Table": { "Rows": 3, "Columns": 2 }
}

Each of the six cells in this table can have its own "Label", colors, and so on, just like a shape.

{
  "ID": 1,
  "Table": {
    "Rows": 3,
    "Columns": 2,
    "Cell": [
      { "Row": 1, "Column": 1, "Label": "Name" },     { "Row": 1, "Column": 2, "Label": "Jane Smith" },
      { "Row": 2, "Column": 1, "Label": "Role" },     { "Row": 2, "Column": 2, "Label": "CEO" },
      { "Row": 3, "Column": 1, "Label": "Email" },    { "Row": 3, "Column": 2, "Label": "jane@example.com" }
    ]
  }
}

Tables are very flexible and making them look the way you want is explained in the Table section of this cookbook.

Using Concatenation to Show Multiple Values

A second way to show multiple values in a shape is to concatenate the values on separate lines. The \n in a text string creates a new line.

{
  "ID": 1,
  "Label": "Jane Smith\nCEO\njane@example.com"
}

Using Shape Data to Show Multiple Values

If a shape represents a record with many values it becomes less practical to show them all in the shape itself, even using tables. A third alternative is to show some of the values in a tool tip using Shape Data.

Compare this complicated org chart:

with the same example using shape data:

Hovering over the small "i" icon on each shape displays a tool tip that shows the additional data without cluttering up the visual:

Read more about Shape Data with VSON.

Adding a Title

Adding a title to your diagram is accomplished by adding a Title object to your VSON document.

{
  "Version": "1.0",
  "Template": "Flowchart",
  "McpGenerated": true,
  "KeepDocument": true,
  "Title": {
    "Label": "Vendor Payment Process",
    "TextBold": true,
    "TextSize": 16
  },
  "Shape": {
    "ID": 1
  }
}

The Title object contains a Label and can be styled with the standard text properties. Entering \n in the label text causes a line break.

The title is centered above the diagram.