Previous
Next

Configuration Options

The VsdxExportConfiguration allows customizing the VSDX Export’s output. It holds a set of customization properties as well as the list of active MasterProviders and ShapeProcessingSteps. You can modify the VSDX output by changing these properties or running different sets of MasterProviders and ShapeProcessingSteps.

VsdxExportConfiguration Properties

The VsdxExportConfiguration holds some general properties like page margins or scale as well as properties that change the behavior of existing MasterProviders or ShapeProcessingSteps.

Such a property is cssStyleSheet where you can set a custom CSS style sheet that will be used when translating SvgVisuals with the SvgProvider. That makes sense when your style implementation uses CSS style sheets. By default, the SvgProvider copies all style sheets available on the page. When you are using nested selectors in your style sheets, they will probably no longer apply since the SVGs are translated in a detached context. Setting this property also is a big performance optimizer since web applications usually use large amounts of CSS while only a small subset is required for the yFiles graph items.

Another performance optimization is to disable the formula interpreter. The formula interpreter, as already mentioned in formula interpreter, will calculate the values of cells that contain formulas. If these values have already been calculated, there is no need to run the interpreter again. Note, that all existing MasterProviders and ShapeProcessingSteps (apart from the VSSXMasterProviderFactory) do not require the formula interpreter. However, the formula interpreter is necessary when the user writes custom MasterProviders or ShapeProcessingSteps in which there exist cells with formulas that do not have pre-calculated values.

If you need to modify the whole VsdxPackage e.g. to add a watermark, company logo or another Page, you can add an ExportFinishedListener. It will be called once the yFiles graph has been fully exported and right before the serialization will start.

Custom MasterProviders and ShapeProcessingSteps

During the export, each yFiles graph item will be processed by two pipelines: First, a master and one or multiple styleSheets will be determined for the new shape by calling the MasterProviders pipeline. Secondly, this shape is processed by the ShapeProcessingSteps pipeline which will configure the necessary properties.

When the VSDX Export encounters a graph item, it determines the master and styles to use by calling one MasterProvider after another until one of them returns an object holding the master and styles based on the style of this item. These will be used to create the shape for the graph item. All MasterProviders that come after the one that returned an object will not be called for this item. So when you add a new MasterProvider you usually prepend it before all other MasterProviders, it has a higher priority:

config.masterProviders.unshift(new MyMasterProvider())

Note that, since most of the common yFiles styles are rendered through SVG elements, it is recommended to register the SvgProvider at the end of the list of MasterProviders so that it handles only styles for which no predefined processing step exists. For example, nodes with ShapeNodeStyle could also be processed by SvgProvider, but it is in general recommended using the corresponding ShapeNodeProvider.

Afterwards, this shape will be piped through all ShapeProcessingSteps in the specified order. They may now modify any properties like setting its location and size. New ShapeProcessingSteps are usually appended after the other ShapeProcessingSteps so they run after them and can rely on properties that are already set:

config.shapeProcessingSteps.push(new MyShapeProcessingStep())

The VSDX Export already comes with a set of MasterProviders and ShapeProcessingSteps that support most of the common yfiles styles. Usually, there is no need to write a custom one by your own. If the export with the default MasterProviders and ShapeProcessingSteps fails or does not produce the desired results you might need to add your own implementations. This is the case if you are using Canvas or WebGl styles or custom styles that make use of unsupported SVG. You can write your own MasterProviders and ShapeProcessingSteps by extending MasterProviderBase or ShapeProcessingStepBase, respectively. For MasterProviders, it usually makes sense to extend the convenience class CachingMasterProvider, which takes care of storing masters and styles for multiple shapes. For edges, it usually makes sense to extend CustomEdgeProvider. Have a look at the demos for example implementations.

The VSDX Export is also capable of employing VSSX stencils and assign its masters and styles to yFiles graph items. This can be done with the VssxStencilProviderFactory. It parses the stencil file and can create master providers that map graph items to masters of the stencil. This requires that the VsdxExportConfiguration.evaluateFormulas property is enabled.

If your stencils depend on user cells that shall reflect the graph items' tags, you can make use of the TagMapperProcessingStep. Label texts can be added through the LabelTextProcessingStep.

const graph = graphComponent.graph
// create a node with a text tag
graph.createNode({
  layout: new Rect(20, 20, 80, 80),
  style: new ShapeNodeStyle(),
  tag: { data: { text: 'Node 1' } }
})

// create the configuration
const config = VsdxExportConfiguration.createEmpty()
config.shapeProcessingSteps.push(new NodeLayoutProcessingStep())
// translate the text stored in the tag of the node
config.shapeProcessingSteps.push(
  new TagMapperProcessingStep((_, item) => item.style instanceof ShapeNodeStyle, {
    'data.text': 'UserText'
  })
)
// the stencil provider requires formula evaluation, which is disabled by default
config.evaluateFormulas = true

// create the stencil factory from a given blob
const stencilProviderFactory = await VssxStencilProviderFactory.fromBlob(blob)
// map the nodes with ShapeNodeStyle to the given style
config.masterProviders.unshift(stencilProviderFactory.createMappedNodeProvider(ShapeNodeStyle, 'ShapeNodeStyle'))
Previous
Next