The VSDX Model
As you can see in the following figure, the abstract VSDX model consists of the following building parts: Page, Master, StyleSheet and Shape. These are conflated by the container objects Pages, Masters, StyleSheets and Shapes. The root of the model is the VsdxPackage.
Shapes are the basic parts out of which diagrams are constructed. They have properties like width, height, pinX and pinY which determine the size and location and style properties like fillForeground. Shapes are organized on pages and masters. There is also a special type of shapes that can hold child shapes, the GroupShape.
If you are familiar with the VSDX format you might expect the properties to be organized in ShapeSheets with sections, rows and cells. The model of the VSDX Export does not explicitly mirror this structure. Instead, the sections, rows and cells are represented by specific classes and objects. You will find, however, that the overall structure is very similar.
For more information regarding the original VSDX model please refer to the documentations listed in the Introduction chapter.
Property Inheritance
Shapes on pages can inherit properties from shapes on masters by setting the master property (see the dotted edges in the model graph). Should the shape and its master shape be a group shape, the exact mapping between the shapes and their respective master shapes is described by the masterShape property. All properties that are not defined on the shape itself will be inherited from its master shape.
All shapes (also the ones defined on masters) can inherit properties from style sheets, too. Each shape may inherit from up to three style sheets: lineStyle, fillStyle and textStyle.
Style sheets themselves can also inherit from other style sheets via the corresponding properties, i.e., fillStyle, lineStyle and textStyle.
When inheriting from both style sheets and a master shape, properties on the style sheets always have a higher priority (in their category) over properties on the master shape. When the master shape itself inherits from style sheets, the properties defined locally on the master shape have priority over the (transitively) inherited style sheets.
Formulas
In the VSDX file format, relationships between different objects are expressed by formulas. Each Value property, or "cell", might have a formula that calculates the value. Unfortunately, when opening files, VSDX viewers don’t recalculate all formulas. For this reason, each cell with a formula also requires a value. In order to reduce the overhead of calculating all values manually, the VSDX Export comes with a formula interpreter that automatically evaluates all formulas in their respective contexts and assigns the values to the corresponding cells. It also automatically duplicates all inherited cells where the calculated values deviate from the inherited values due to different contexts.
Another difficulty with formulas is referencing other cells, especially across shapes or pages. To handle this, we added a convenience method that makes use of EcmaScript 2015 tagged template strings. When typing formulas you use JavaScript expressions for references. Consider this example:
import { fun, Value } from '@yfiles/vsdx-export'
let page // a Page
const groupShape = page.shapes.createGroupShape()
const childShape = groupShape.shapes.createShape()
groupShape.width = Value.scalar(5)
// sets the width of childShape to the width of the groupShape
childShape.width = Value.formula(fun`${groupShape.width}*1`)Note that the referenced cells need to be defined before they are referenced. If you need a reference to a cell that has not been defined yet, you can call Value.fetch.