Getting Started

HTML elements

The DiagramView control relies on the HTML5 Canvas element to render graphics on web page. If you need to display large diagrams, place the Canvas inside a Div element.
Overflow and scrolling will be handled internally by DiagramView.

HTML

<div style="width: 800px; height: 600px;">
    <canvas id="diagram" width="2100" height="2100">
        This page requires a browser that supports HTML5 Canvas element.
    </canvas>
</div>

The MindFusion.Diagramming toolkit includes additional user interface controls such as Ruler, Overview, NodeListView and ZoomControl. If you'd like to use any of them, you will need to add Div and/or Canvas element for each one; for an example, see the Controls sample project.

Modules and namespaces

The diagramming library is available in three different distributions - ES modules, CommonJs modules and UMD. Each of them splits the code into six modules or namespaces. The UMD module exposes a global MindFusion namespace object, containing child namespaces that match the modules from the other two distributions, namely Collections, Controls, Drawing, Diagramming, Animations and Graphs.

For more information on JavaScript modules see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules.

Loading UMD namespaced scripts

UMD is a pattern of universal module definition for JavaScript modules. These modules are capable of working irrespective of the executing environment. In web browsers, it exposes the module functionality to the global scope.

In order to load the UMD scripts, add references to files from diagram distrbution's /umd folder using <script> tags. Note that the order of the scripts matters: controls.js must be loaded after collections and drawing, and diagramming.js must be loaded after animations and graphs.

HTML

<script src="umd/collections.js" type="text/javascript"></script>
<script src="umd/drawing.js" type="text/javascript"></script>
<script src="umd/controls.js" type="text/javascript"></script>

<script src="umd/animations.js" type="text/javascript"></script>
<script src="umd/graphs.js" type="text/javascript"></script>
<script src="umd/diagramming.js" type="text/javascript"></script>

After these scripts are loaded, you can access the global MindFusion namespace object from your code:

JavaScript

var DiagramView = MindFusion.Diagramming.DiagramView;

document.addEventListener("DOMContentLoaded", function () {
    var diagramView = DiagramView.create(document.getElementById("diagram"));
});

Loading ES6 modules via importmap

Diagram's ES6 modules conform to modern JavaScript module definition that supports native import and export statements. You could import these modules directly, without using any additional module/package libraries or tools, by defining your script file as a module via <script type="module"> tag:

HTML

<script src="app.js" type="module"></script>

In order to make the diagram's ES6 modules available for importing, add the following importmap, referencing the scripts, contained in distribution's /esm folder. The purpose of the importmap is to define a map of module names which allow using import specifiers such as import {x} from "@mindfusion/diagramming" (instead of a relative path to the corresponding script file), both internally and in in your code.

HTML

<script type="importmap">
{ 
    "imports":
    {
        "@mindfusion/collections":"./esm/collections.js",
        "@mindfusion/controls":"./esm/controls.js",
        "@mindfusion/drawing":"./esm/drawing.js",
        "@mindfusion/diagramming":"./esm/diagramming.js",
        "@mindfusion/graphs":"./esm/graphs.js",
        "@mindfusion/animations":"./esm/animations.js"
    }
}
</script>

Now you can consume the modules you need by importing them into your app.js:

JavaScript

import * as Diagramming from '@mindfusion/diagramming';
import * as Drawing from '@mindfusion/drawing';

var diagramView = Diagramming.DiagramView.create(
    document.getElementById("diagram"), diagram);

Note that at the time of writing this, support for importmap is yet to be implemented in all browsers (https://caniuse.com/import-maps), but can be added using shims such as https://github.com/guybedford/es-module-shims. Notably, importmap is not yet supported by Firefox (but it is under development from what we know), and is in technology preview version for Safari.

Loading npm packages and bundling

There are six npm packages that provide the functionality of MindFusion.Diagramming, each containing the corresponding module. To use JsDiagram in a project, you only need to install the @mindfusion/diagramming package, the rest will be automatically added as dependencies:

npm install @mindfusion/diagramming

Each of the packages contains three distributions - ES module, CommonJs module and UMD, that you can use depending on your project setup.

To consume a module as a CommonJS module, use the 'require' statement. The CommonJs version of the module will be loaded from the /dist/cjs folder, as specified in the package.json's main field.

JavaScript

const Diagramming = require('@mindfusion/diagramming');
const { DiagramView } = require('@mindfusion/diagramming');

To consume a module as an ES6 module, use the 'import' statement. The ES6 version of the module will be loaded from the /dist/esm folder, as specified in the package.json's module field.

JavaScript

import * as Diagramming from '@mindfusion/diagramming';
import { DiagramView, Diagram } from '@mindfusion/diagramming';

A sample webpack bundle configuration is shown in Samples\MinApp\TypeScript\WebPack folder of distribution:

package.json

...
"dependencies": {
    "@mindfusion/diagramming":"^4.1.0"
},
...

TypeScript support

A d.ts declaration file is available for every package. For more information on declaration files see https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#dts-files.

Set up code completion

The library provides code completion and hints through d.ts declaration files, supported by most popular IDEs. In order to enable the feature, you need to add a commented reference to the TypeScript *.d.ts files that are included in the library distribution. The most commonly used API members are in the diagramming file, but we advise that you add references to the auxiliary files as well:

JavaScript

/// <reference path="Scripts/diagramming.d.ts" />
/// <reference path="Scripts/animations.d.ts" />
/// <reference path="Scripts/collections.d.ts" />
/// <reference path="Scripts/controls.d.ts" />
/// <reference path="Scripts/drawing.d.ts" />

Once the references are loaded, you should be able to see code suggestions for the applicable members together with their type. All members should be visible: methods, properties, classes etc.

The distribution also includes JsDiagram-vsdoc.js file providing IntelliSense documentation in VSDoc format. If your programming environment supports it, you could add a reference to that file instead of d.ts ones:

JavaScript

/// <reference path="Scripts/JsDiagram-vsdoc.js" />

Creating and displaying a Diagram

The Diagram is a model class, while rendering and interactions are handled by the DiagramView control. The Diagram instance can be created first and passed to the view as a second argument of the DiagramView.create method, or if not provided, an empty Diagram will be created and will be accessible through the view's diagram property.

JavaScript

var diagram = new Diagramming.Diagram();
var diagramView = Diagramming.DiagramView.create(document.getElementById("diagram"), diagram);

var diagramView = Diagramming.DiagramView.create(document.getElementById("diagram"));
var diagram = diagramView.diagram;

Add items from code

You can create diagram items programmatically by calling methods of the diagram's Factory object. Alternatively, create an instance of any class derived from DiagramItem by calling its constructor, and call addItem to add it to the diagram:

JavaScript

var node1 = diagram.factory.createShapeNode(0, 0, 10, 10);

var node2 = new Diagramming.ShapeNode(diagram);
node2.bounds = new Drawing.Rect(20, 0, 10, 10);
diagram.addItem(node2);

Draw items interactively

The DiagramView can respond in various way to user input depending on the value of its behavior property. By default, it creates a ShapeNode when the user starts drawing from unoccupied location, or a DiagramLink when the mouse pointer is over a node. See the Behavior enumeration for other supported modes.

Further reading

Browse the topics under Programming Interface Overview for conceptual information. See the tutorial topics and check the sample scripts provided with JsDiagram.zip distribution for sample source code. For integrating the diagram with popular front-end libraries and frameworks, see React, Vue.js and Angular topics.