JointJS+ Visio

The document property holds an instance of VisioDocument of an imported vsdx archive.

The source property holds the original archive used to create the VisioArchive instance. It's being stored as an ArrayBuffer.

async visioArchive.toVSDX([opt]])

Use data stored in the VisioArchive instance to generate a vsdx file. This method will return a promise resulting in a vsdx file in a chosen format.

The toVSDX([opt]) method takes an object opt with the following parameters:

const blob = await archive.toVSDX({
    type: 'blob'
    compression: 'DEFLATE',
    compressionOptions: {
        level: 9
    }
});

Usage

const blob = await visioArchive.toVSDX({ type: 'blob' });
joint.util.downloadBlob(blob, 'project.vsdx');

A basic example of export process using default converter can be found in the plugin usage section.

visioCell.eval()

Return a calculated result based on cell value, units and formula.

Return a formula that the cell uses to calculate the value.

Return a cell name (one of VisioCellName enum values).

Return a unit type of the cell. Used by Visio and visioCell.eval() to properly evaluate the value.

Return a raw cell value. Raw cell value is given in the cell.units and returned as a string.

String name of the VisioCell from which the connection originates.

Identifies the part of the Visio Shape from which a connection is made.

INT id of the source VisioShape.

visioConnect.getShape()

Return a VisioShape representing the connection itself.

visioConnect.getSource()

Return a VisioShape representing the connection source shape. In case there is no source shape, method will return null.

visioConnect.getTarget()

Return a VisioShape representing the connection target shape. In case there is no source shape, method will return null.

String name of the VisioCell to which the connection is made.

visioConnect.toLinkAttributes(sourceElement, targetElement)

Return JointJS Link attributes, based on the VisioConnect properties and a provided sourceElement and targetElement.

Identifies the part of the VisioShape to which a connection is made.

INT id of the target VisioShape.

visioDocument.getMasters()

Return an array of VisioMaster instances present in the document.

visioDocument.getMastersIdMap()

Return a Map of VisioMaster instances present in the document, using master id as the key.

visioDocument.getMastersMameMap()

Return a Map of VisioMaster instances present in the document, using master name as the key.

visioDocument.getPage(pageId)

Return a VisioPage metadata object describing a single page with the given pageId. If page with given id doesn't exist, method will return undefined.

Metadata does not contain page contents. To load contents, use page.getContent() method.

Examples

To fetch metadata of a particular page do:

const archive = await VisioArchive.fromURL('./assets/vsdx/archive.vsdx');
const { document: vsdDocument } = archive;

const page1 = vsdDocument.getPage(0);

To fetch a page that's used as a background for a particular page, simply do:

const archive = await VisioArchive.fromURL('./assets/vsdx/archive.vsdx');
const { document: vsdDocument } = archive;

const page1 = vsdDocument.getPage(0);
const bgPage = vsdDocument.getPage(page1.backPage);

visioDocument.getPages()

Return an array of VisioPage metadata objects present in the loaded vsdx document. Metadata does not contain page contents. To load contents of a particular page, use page.getContent() method.

getPages() can be useful i.e. for building project page listing.

visioGeometrySection.addRow(geometryRowType)

Add a named VisioRow to a geometry section rows collection. Provided geometryRowType must be one of VisioRowType enum values. If no geometryRowType is provided, a row of type VisioRowTyp.RelMoveTo will be added in case it's the first row, or VisioRowType.RelLineTo for any consecutive rows.

Usage

const [geometry0] = vsdShape.getGeometry();
geometry0.addRow(VisioRowType.MoveTo);

visioIndexedSection.addRow()

Appends a VisioRow to an indexed section rows collection.

Usage

const scratch = vsdShape.getSection(VisioSectionType.Scratch);
scratch.addRow(); // add a row with next available index

visioIndexedSection.getRow(index)

Return a VisioRow with a given index in a section with indexed structure. If row doesn't exist, return null.

visioIndexedSection.removeRow(index)

Remove a row with the given index from an indexed section.

visioMaster.getIconBase64()

Return a base64 data string containing a stencil item icon.

Return a unique, integer master id.

Return a name that by design in Visio is unique. Multiple instances of a same name in a stencil receive an additional ID appended to the name (i.e. "Master.12").

visioNamedSection.addRow(rowName)

Add a VisioRow to a named section rows collection. Can not add a row with a given rowName if a row with such name already exists.

Usage

const properties = vsdShape.getSection(VisioSectionType.Property);
properties.addRow('NewPropertyRow');

visioNamedSection.getRow(rowName)

Return a VisioRow in a named section with a given rowName. If row doesn't exist, return null.

visioNamedSection.removeRow(rowName)

Remove a row with the given rowName from a named section.

Return true if the page is marked as a background page. Background pages are oftentimes used to show repetitive content on many foreground pages.

If the page uses a background page, return its id

async visioPage.fromPaper(paper [,opt])

page.fromPaper() method is used when exporting a JointJS project to a vsdx file format. Before the vsdx archive is built, its pages should be updated with new content. This new content is built using JointJS paper.

Example

The below example updates visio archive with the contents of JointJS paper and uses default converter to create a VisioShape for each JointJS Cell, as well as update project configuration. Lastly, the updated archive is exported as a vsdx file.

const archive = await VisioArchive.fromURL('./project.vsdx');
const { document: vsdDocument } = archive;
const [page1] = vsdDocument.getPages();

await page1.fromPaper(paper);
const blob = await archive.toVSDX({ type: 'blob' });

util.downloadBlob(blob, 'project.vsdx');

For a more robust example on the export flow with mapping, view demos/bpmn-export demo files.

Options

The fromPaper(paper, [opt]) method takes JointJS paper, and an object opt with the following parameters:

exportElement: async(elementView) => {
    const { model, paper } = elementView;

    let master;
    // perform relevant logic to find chosen master shape
    // ...

    // create a raw shape based on a stencil Master
    const vsdShape = await VisioShape.fromMaster(master, vsdDocument);

    // perform vsdShape manipulations based on the given elementView
    // ...

    // return modified vsdShape
    return vsdShape;
}

exportLink: async(linkView) => {
    let master;
    // perform relevant logic to find chosen master shape
    // ...

    return await VisioShape.fromMaster(master, vsdDocument);
}

async visioPage.getContent()

Return a VisioPageContent instance containing page shapes.

Return page height in pixels.

Return a unique, integer page id.

Return page name as configured in Visio project.

Return page universal name as configured in Visio project.

Return page height in pixels.

visioPageContent.getConnect(shapeId)

Return a VisioConnect associated with the provided shapeId. If no such shape exists, return undefined.

As VisioConnect contains connection metadata, it always points to the actual VisioShape that is a visual representation of the connection.

visioPageContent.getConnects()

Return all VisioConnects present in the page content.

visioPageContent.getElementShapes()

Return all VisioShape's that would be identified as Element in JointJS.

visioPageContent.getFonts()

Return an array of fonts used by shapes on the page. If no fonts are defined, return an empty array.

visioPageContent.getForeignShape(path)

Return VisioShape considered foreign (i.e. image), with the given path within the VisioArchive document. If there is no shape for the given path, method will return undefined

visioPageContent.getForeignShapes()

Return all VisioShapes considered foreign (i.e. images) from the page content.

visioPageContent.getLinkShapes()

Return all VisioShape's that would be identified as Link in JointJS.

visioPageContent.getRootShape(id)

Return a top-level VisioShape with the given id from the page content. Return undefined if shape does not exist or is not a root shape.

visioPageContent.getRootShapes()

Return all top-level VisioShape instances from the page content. Omit all the sub-shapes.

visioPageContent.getShape(id)

Return a VisioShape with the given id.

visioPageContent.getShapes()

Return all VisioShape instances from the page content.

visioPageContent.getUnsupportedFonts()

Return an array of fonts that are used by shapes on the page, however are not supported by the application. If all fonts are supported, return an empty array.

visioPageContent.toGraphCells([,opt])

Method used to convert contents of a Visio project page to JointJS Graph Cells. Its main usage is in the import process of a vsdx file into a JointJS application.

Options

The toGraphCells([,opt]) method takes an object opt with the following parameters:

importShape: (vsdShape) => {
    let element;
    // .. perform logic creating an Element
    // using the vsdShape as the source of information

    return element;
}

importConnect: (vsdConnect, sourceElement, targetElement) => {
    let link;
    // .. perform logic creating a Link from vsdConnect

    return link;
}

importLabels: (vsdShape, link) => {
    const data = vsdShape.getSection(VisioSectionType.Property);
    const name = data.getProperty('BpmnName');
    if (name) {
        link.appendLabel({
            attrs: {
                body: {
                    fill: '#F4F7F6'
                },
                label: {
                    text: name,
                    fontWeight: 'bold',
                    fontSize: 10
                }
            },
            position: 0.5
        });
    }
}

importImage: (vsdShape, element, image) => {
    element.attr('image/xlinkHref', image.base64);
}

onImagesLoad: (images) => {
    // i.e. finish preloading
}

A full example of usage can be found in demo/bpmn-import directory.

If the row is part of a indexed VisioSection, returns an integer index of the row.

If the row is part of a named VisioSection, returns a name of the row.

Return type of the row or undefined if there is no type set.

As an example, type is used by Geometry section rows to indicate what kind if drawing action it describes, i.e. 'LineTo'.

visioSection.getRows()

Return an array of VisioRows the section contains. If none exist, return an empty array.

Return type of the section. Each section type has one of the two row structures, either 'Indexed' or 'Named'.

visioShape.addSection(sectionType)

Add a new VisioSection (either VisioIndexedSection or VisioNamedSection) based on the given sectionType. In case it is a named section that already exists, new one will not be added. New indexed section will be appended at the end of the given collection with an index incremented from the previously highest index.

// add a custom properties section
vsdShape.addSection(types.VisioSectionType.Property);

visioShape.getAncestorShapes()

Return an array of ancestor VisioShapes of the shape, ordered starting with highest level.

visioShape.getComputedGeometry()

Return an array of sections merged from own and inherited geometries. If there is no geometry sections defined on either shape or the master, return an empty array.

visioShape.getComputedSection(type)

Return a section merged from own and inherited from master section data. If section of the type does not exist on either, return null.

If the given type is VisioSectionType.Geometry, return results of visioShape.getComputedGeometry().

visioShape.getConnect()

Return a VisioConnect of the shape. If shape does not have a connect pointing to it, return null.

visioShape.getGeometry()

Return an array shapes own geometry sections. If none is defined, return an empty array.

async visioShape.getImage()

Return an image object containing following properties:

visioShape.getMaster()

Return a VisioMaster for a shape. Return null if the shape was not created from a stencil master.

visioShape.getOwnSectionNames()

Return an array of section names defined for the shape.

visioShape.getPageAngle()

Return a number describing shape angle to the page.

visioShape.getPageBBox()

Return a g.Rect describing the shape bbox on the page.

visioShape.getPagePosition()

Return a g.Point describing position of the shape on the page.

visioShape.getPageZIndex()

Return an int describing the shape z-index on the page.

visioShape.getRootShape()

Return the VisioShape that is a root shape for the given shape, or the visioShape itself if it is a root shape.

visioShape.getSection(type)

If an own section of type exists on the shape, return it. If a section does not exist on the shape, return null

Own sections are defined for the shape and set values override sections inherited from master shape.

If the given type is VisioSectionType.Geometry, return results of visioShape.getGeometry().

visioShape.getSectionNames()

Return an array of all section names available for the shape, including inherited ones.

visioShape.getSubShapes()

Return an array of all shapes nested within the given visioShape.

visioShape.getText()

Return a string representing shape text if one exists. If none is defined, return empty ''.

visioShape.hasImage()

Return true if the shape contains an image.

A unique, integer shape id.

visioShape.isOneDimensional()

Return true if the shape is considered 1-D (one-dimensional) in Visio. Such shapes contain beginX, beginY, endX, endY cells. Return false if shape is considered 2-D.

masterId points to a master given shape was created from.

A string name of the shape.

visioShape.removeSection(sectionName, sectionIndex)

If a named section is being removed, only the sectionName parameter is required. For indexed section, a second parameter, sectionIndex has to be provided. sectionIndex defaults to 0 if none is provided.

// remove property section
vsdShape.removeSection(types.VisioSectionType.Property);

// remove geometry section with index 2
vsdShape.removeSection(types.VisioSectionType.Geometry, 2);

visioShape.setText(text)

Update shape text with given text. Do mind this will override the existing text.

visioShape.toElementAttributes()

Return JointJS dia.Element attributes created from the shape. It's particularly useful when using custom Element instead of the one used by the default converter.

A string type of the shape, i.e. 'Shape' or 'Group'.

sheetObject.getCell(cellName)

Return a cell object with the given cellName. If cell with given name does not exist, return undefined. cellName is case sensitive and should use camel-case naming convention.

Usage

console.log(vsdShape.getCell(VisioCellName.PinX));
// {value: "1", units: "IN", name: "PinX"}

sheetObject.getOwnCellNames()

Return an array of cell names defined as own for the sheet object. Does not include inherited cell names.

sheetObject.removeCell(cellName)

Remove cell with the given cellName from the sheet object. cellName is case sensitive and should use camel-case naming convention.

vsdShape.removeCell(VisioCellName.PinX)

sheetObject.setCell(cellName, cellAttributes)

setCell allows for adding or updating a cell within the sheet object. Important thing to note is that knowledge about Visio Cells is required to properly set cells in certain scenarios, i.e. units might be required to properly evaluate the value in Visio.

Inheriting and overriding attributes

Passing null as any of the cellAttributes will remove the attribute from the cell, which will in return fallback to inherited value. If the intention is to override any attribute, set it to an empty string, i.e. {formula:''}. Not passing any of the attributes will skip them, and existing ones will be kept.

Parameters

Usage

Below code will update width cell (or create it if it doesn't exist), setting value to '1', units to 'IN' and inheriting the formula.

// shape cell
vsdShape.setCell(VisioCellName.Width, { value: '1', units: VisioUnitType.IN });

// property section row cell
vsdRow.setCell(VisioCellName.Value, { value: '1', formula: null, units: VisioUnitType.BOOL });