The VSON Cookbook

Arranging Shapes in Rows and Columns

You can use a ShapeContainer object to arrange a collection of shapes in a row across the page.

For example, if you have a list of tables from a database, you may want to represent them as a list of shapes. You could show this list as a row of shapes across the page using a ShapeContainer.

You add a ShapeContainer to the root shape and then add as many shapes as you need to the ShapeContainer.

{
  "Version": "1.0",
  "Template": "Flowchart",
  "McpGenerated": true,
  "KeepDocument": true,
  "Shape": {
    "ID": 1,
    "ShapeContainer": {
      "Arrangement": "Row",
      "Shapes": [
        { "ID": 2, "Label": "Table 1" },
        { "ID": 3, "Label": "Table 2" },
        { "ID": 4, "Label": "Table 3" },
        { "ID": 5, "Label": "Table 4" },
        { "ID": 6, "Label": "Table 5" },
        { "ID": 7, "Label": "Table 6" },
        { "ID": 8, "Label": "Table 7" }
      ]
    }
  }
}

Note that the ShapeContainer has an Arrangement property which is set to "Row". By default the ShapeContainer Arrangement is "Square" which attempts to make a square matrix arrangement. Omitting the "Arrangement" property, or replacing it with "Square" gives:

You can control the maximum number of shapes in each row using a "Wrap" property combined with the Row Arrangement. Here we set the rows to wrap at every fourth shape:

{
  "ShapeContainer": {
    "Arrangement": "Row",
    "Wrap": 4,
    "Shapes": [ ... ]
  }
}

Setting the Arrangement to "Column" shows all the shapes arranged vertically:

The Wrap property can also be used to control the maximum number of shapes in a column.

Hiding the Parent Shape

In our example of showing a shape for each table in a database you probably don't want to actually display the parent shape as a border around the seven shapes. You can remove the parent shape using the "Hide" property:

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

Controlling the Spacing Between Shapes

By default the space between each shape in a ShapeContainer, and the space between the shapes and their container is 0.5 inches (50/100). The ShapeContainer properties HorizontalSpacing and VerticalSpacing are used to override the default of 50/100.

{
  "ShapeContainer": {
    "Arrangement": "Row",
    "HorizontalSpacing": 25,
    "VerticalSpacing": 25,
    "Shapes": [ ... ]
  }
}

Arranging Shapes that are Different Sizes

In all of our examples so far the shapes in the ShapeContainer were all the same size, but in most applications this will not true.

Rows of shapes with different heights can be arranged so their tops, middles or bottoms align. You control this with the SetAlignV method of the ShapeContainer. This is "Top" by default.

Columns of shapes with different widths can be arranged so the lefts, centers or rights align. You control this with the SetAlignH method of the ShapeContainer. This is "Center" by default.

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);
myContainer.AddShape().SetLabel("Table 1").SetMinHeight(150);
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5").SetMinWidth(300);
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");
var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}

Setting ShapesAlignV to "middle" and ShapesAlignH to "Left" gives this:

{
  "ShapeContainer": {
    "Arrangement": "Row",
    "ShapesAlignV": "middle",
    "ShapesAlignH": "left",
    "Shapes": [ ... ]
  }
}

Drawing Lines Between Shapes in a Container

Extending our example of shapes representing tables in a database, we might want to connect shapes with a line showing relationships between tables. For example suppose there is a one to many relationship between Table 1 and Tables 5 and 7.

You create lines by adding entries to the document's Returns array, supplying the IDs of the shapes you want to connect.

{
  "Returns": [
    { "StartID": 2, "EndID": 6, "EndArrow": 8 },
    { "StartID": 2, "EndID": 8, "EndArrow": 8 }
  ]
}

Note that the "EndArrow" value 8 is CrowsFoot arrowhead. For a detailed list of arrowhead styles available, see the VSON Markup Reference.