The VSON Cookbook

Creating Tables with VSON

Tables are a very powerful feature of VSON. They are used to subdivide a shape into multiple cells that have similar properties to a shape: labels, colors, hyperlinks, and more. A cell can also contain another shape. This can be the root shape of a whole "diagram": a tree, a flowchart, a ShapeContainer and even another table.

Adding a Table to a Shape

A table can be added for any shape using the Table property.

The only required properties of a Table object are the number of rows and columns. This document creates a table inside a shape with three rows and one column, and three cells.

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

This creates a table inside a shape with three columns and one row and three cells.

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

This creates a table inside a shape with three columns and three rows and nine cells.

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

Joining Rows or Columns

More complex arrangements can be achieved using the Join array on the Table. Each join takes a starting Row, a starting Column, the number of cells to join (N), and a direction (Down true or false). When specifying which cells to join, note that the coordinates are 1-based.

{
  "ID": 1,
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "Join": [
      { "Row": 1, "Column": 1, "N": 3, "Down": false }
    ]
  }
}

To join cells, you'll have to define the anchor row and column and the number of cells to add to it.

You can also join down a column.

{
  "ID": 1,
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "Join": [
      { "Row": 1, "Column": 1, "N": 3, "Down": true }
    ]
  }
}

You can define multiple joins in an array.

{
  "ID": 1,
  "Table": {
    "Rows": 4,
    "Columns": 4,
    "Join": [
      { "Row": 1, "Column": 1, "N": 4, "Down": false },
      { "Row": 2, "Column": 1, "N": 3, "Down": true },
      { "Row": 4, "Column": 2, "N": 3, "Down": false }
    ]
  }
}

Setting the Size of a Table

By default, a table is made to fitinside the shape that hosts it, with the caveats that a row cannot be smaller in height than is required for a lineof text in the default font and the width of a column cannot be less than the width of a single character in the default font of the shape. Cells will grow to accommodate the text that they contain based on the TextGrow property of the host shape, but it is sometimes useful to be able to set the minimum width of a column and/or height of a row for the whole table. In this example we set the height of all the rows to 50/100" and the width of all the columns to 1".

{
  "ID": 1,
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "RowHeight": 50,
    "ColumnWidth": 100
  }
}

Defining Cells

The intersection of a row and a column defines a cell. A cell has many of the properties of a shape. You can set cell properties by adding a Cell object to the Cell array a the desired row and column.

{
  "ID": 1,
  "Table": {
    "Rows": 2,
    "Columns": 1,
    "Cell": [
      { "Row": 1, "Column": 1, "Label": "Title" },
      { "Row": 2, "Column": 1, "Label": "Lorem ipsum dolor sit amet, consectetur adipiscing elit." }
    ]
  }
}

For each Cell object, the Row and Column coordinates are required to define the cell. Then each cell may have a label, colors, hyperlinks and even an image.

{
  "Cell": [
    {
      "Row": 1, "Column": 1,
      "Label": "Title",
      "FillColor": "#2C3E50",
      "TextColor": "#FFFFFF",
      "TextBold": true
    },
    {
      "Row": 2, "Column": 1,
      "Label": "Body text here",
      "FillColor": "#FFFFFF",
      "TextColor": "#333333"
    }
  ]
}

Displaying Images in Cells

By default, an image displayed in a cell fills it completely. The image is scaled so that the aspect ratio is preserved and no white space is seen either on the sides or top and bottom.

You can also display an image inside the text area of the cell. This is the cell rectangle indented by the text margin for the shape.

{
  "Cell": [
    {
      "Row": 1, "Column": 1,
      "Image": { "url": "https://www.smartdraw.com/path/to/image.png" },
      "UseTextRectAsFrame": true
    }
  ]
}

Defining Grid Lines and Other Row and Column Properties

The border of a cell is defined by the line for the row and column it is in. Properties that apply to whole rows and columns are set using the RowProperties and ColumnProperties arrays on the Table.

RowProperties has settings for color and thickness of its bottom line.

{
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "RowProperties": [
      { "Index": 2, "LineThick": 0 }
    ]
  }
}

You can remove all of the grid lines this way.

{
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "RowProperties": [
      { "Index": 1, "LineThick": 0 },
      { "Index": 2, "LineThick": 0 },
      { "Index": 3, "LineThick": 0 }
    ],
    "ColumnProperties": [
      { "Index": 1, "LineThick": 0 },
      { "Index": 2, "LineThick": 0 },
      { "Index": 3, "LineThick": 0 }
    ]
  }
}

You can change the color of the lines too:

{
  "RowProperties": [
    { "Index": 1, "LineColor": "#FF0000" },
    { "Index": 2, "LineColor": "#00AA00" }
  ]
}

You can use RowProperties and ColumnProperties to define the minimum height and width of a row and column. "Height":"75" and "Width:"100" sets the row to 75/100 of an inch tall and width of a column to 1" wide.

{
  "RowProperties": [
    { "Index": 1, "Height": 75 }
  ],
  "ColumnProperties": [
    { "Index": 1, "Width": 100 }
  ]
}

Finally, you can apply cell properties to an entire row or column using RowProperties and ColumnProperties. For example if you want to set the color of the first row of table to be white, while the rest remains blue (the default shape color):

{
  "RowProperties": [
    { "Index": 1, "FillColor": "#FFFFFF" }
  ]
}

RowProperties are applied before ColumnProperties so if the properties of a cell are changed by both, the ColumnProperties setting will "win". Cells are processed last, so any setting of property using a Cell will override the same property with RowProperties or ColumnProperties.

Alternating Row Colors

The "AlternateRows" property of a table makes the rows alternate between two colors:

{
  "Table": {
    "Rows": 5,
    "Columns": 3,
    "AlternateRows": { }
  }
}

The default colors are shown above. You can override the defaults:

{
  "Table": {
    "Rows": 5,
    "Columns": 3,
    "AlternateRows": {
      "Color1": "#F4F6F8",
      "Color2": "#FFFFFF"
    }
  }
}

Alternating Column Colors

The same approach can alternate column colors using Color1 and Color2 swapped between columns by ColumnProperties.

You can override colors and set a range for the rows affected and which column to begin alternating.

Adding Shapes to Table Cells

You can add a shape to a table cell:

{
  "Cell": [
    {
      "Row": 2, "Column": 2,
      "Shape": {
        "ID": 2,
        "Label": "Nested",
        "FillColor": "#3498DB",
        "TextColor": "#FFFFFF"
      }
    }
  ]
}

Note that cell 2,2 grows to accommodate a default-sized shape.

Positioning the Shape in a Cell

By default, the shape in the cell has a margin of 20/100" separating it from the edge of the cell. You can control this margin with ShapeMarginH and ShapeMarginV on the Table.

{
  "Table": {
    "Rows": 3,
    "Columns": 3,
    "ShapeMarginH": 20,
    "ShapeMarginV": 20,
    "Cell": [
      { "Row": 2, "Column": 2, "Shape": { "ID": 2 } }
    ]
  }
}

If you make the cell larger than the shape plus margin, it is placed according to the text justification in the cell.

Placing Multiple Shapes in Cells

The shape may have all the properties of any shape, including being the root shape for a ShapeContainer, a ShapeConnector or another table:

{
  "Cell": [
    {
      "Row": 1, "Column": 1,
      "Shape": {
        "ID": 2,
        "ShapeContainer": {
          "Arrangement": "Row",
          "Shapes": [
            { "ID": 3, "Label": "Choice A" },
            { "ID": 4, "Label": "Choice B" }
          ]
        }
      }
    }
  ]
}

Note you can hide the parent shape of these two children and get the effect of adding multiple shapes to one cell.

{
  "Shape": {
    "ID": 2,
    "Hide": true,
    "ShapeContainer": { ... }
  }
}

Any ShapeConnector can be used too.

{
  "Cell": [
    {
      "Row": 1, "Column": 1,
      "Shape": {
        "ID": 2,
        "ShapeConnector": [
          {
            "ShapeConnectorType": "OrgChart",
            "Shapes": [{ "ID": 3 }, { "ID": 4 }]
          }
        ]
      }
    }
  ]
}

A shape in a cell can contain another table which may also have a shape in a cell recursively: