These docs are for v1.0. Click to read the latest docs for v1.2.

Definitions

Definitions can be used to simplify complex calculations by storing data to be referenced in formulas. These definitions act like shape data properties that are not editable and are purely calculated using other values.

For example, if a shape data property named @Value was defined, and the square root of that property was calculated multiple times, a definition called @ValueSquareRoot could be created to simplify the formulas for the geometry that needed the square root of @Value. This usage prevents the need to constantly reference SQRT(@Value) in formulas and allows the formula to be changed in the future in a single spot, instead of multiple places.

Definitions can be defined in the top-level of the shape definition, making it available to all geometry and sub-shape, or within a sub-shape, which would be available to that sub-shape's geometry and further sub-shapes.

DefinitionSchema

PropertyTypeDescription
namestring
valueformula

Types

Definitions must be defined with a data type, using one of the data types described in the shape data properties section.

Scope and evaluation order

As definitions are created, they are available for use within the shape they are defined in or any sub-shapes below that shape. This is referred to as the scope of the variable, which describes where the variable may be used. The scope for sub-shapes in called a child scope or a lower scope, and the scope of the parent sub-shape (or top-level shape definition) is called a parent scope or a higher scope.

As an example, in the following figure there are 3 scopes (A, B, and C):

  • A is the top-level scope and the parent scope of B.
  • B is a child scope of A and a parent scope of C.
  • C is a only a child scope of B.
  • Scope B is a higher scope than scope C, and a lower scope than scope A.

Scopes

There are some exceptions to the general rule that definitions are available within the shape they are defined in, when working with sub-shapes. This is due to the order in which formulas are evaluated when generating the geometry to render the shape definition.

Formulas in a shape definition are evaluated in the following order:

  • Conditions - The sub-shapes condition is evaluated first and do not use the local definitions.
  • Repeat - Repeat fields do not use the local definitions. The repeat definitions (for index / value) are evaluated and added to a new local scope.
  • Definitions - Definitions are evaluated and added to the current local scope.
  • Bounds - Bounds are evaluated, using both repeat and definitions.
  • Text Areas - Text areas are evaluated, using both repeat and definitions.
  • Link Points - Link points are evaluated, using both repeat and definitions.
  • Geometry - Geometry are evaluated, using both repeat and definitions.
  • Sub-Shapes - Sub-shapes are evaluated using the same evaluation order (with the current scope becoming the new parent scope).

Built-in definitions

When using formulas in the custom shape format, there are some properties that are pre-filled with metadata about the shape. These can be used anywhere in the custom shape format and will always be available (unless overridden with a definition of the same name).

DefinitionDescription
@WidthThe width of the shape in pixels.
@HeightThe height of the shape in pixels.