Getting Started with Diagram

The Diagram widget provides a visual interface to help you design new and modify existing diagrams.

NOTE
At this time, the Diagram is available as a community technology preview (CTP) version. You can test the component and share your feedback to influence our R&D process. We do not recommend that you use the Diagram in production environments because of possible implementation issues and a high chance of breaking changes in subsequent versions.

View Demo

Add the Diagram Widget to a Page

Add devexpress-diagram resources (scripts and styles) onto the page. You can access the resources through npm or CDN.

  • npm

    Install the devexpress-diagram package.

    npm install devexpress-diagram --save

    Add the dx.diagram.css and dx.diagram.js files to your page.

    HTML
    <link rel="stylesheet" href="node_modules/devexpress-diagram/dx.diagram.css">
    <script type="text/javascript" src="../node_modules/devexpress-diagram/dx.diagram.js"></script>
  • CDN

    Add the dx.diagram.css and dx.diagram.js files to your page.

    HTML
    <link rel="stylesheet" href="https://unpkg.com/devexpress-diagram/dx.diagram.css">
    <script src="https://unpkg.com/devexpress-diagram/dx.diagram.js"></script>

    Initialize the Diagram widget in a DOM element.

    JavaScript
    $(function() {
        $("#diagram").dxDiagram();
    });
    HTML
    <div id="diagram"></div>

Diagram control

Load and Save Diagram Content

To load and save a diagram to a string variable, use the setData and getData methods.

JavaScript
var diagram = $("#diagram").dxDiagram("instance");
var diagramContent = diagram.getData(); // load diagram content to a variable
diagram.setData(newDiagramContent); // replace the existing diagram with a new diagram
NOTE
The Diagram widget stores an opened diagram's data in its own text format. Thereby we recommend you to not modify data returned by the getData method. A manually modified document can be loaded incorrectly.

Data Binding and Auto Layout

The Diagram can load external treelike and graph structures. The supported data structures are listed below.

  • A graph constructed from two plain lists of nodes and edges. The Diagram binds its nodes and edges collections to the appropriate lists.

    index.js
    data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: orgItems
            },
            edges: {
                dataSource: orgLinks
            },
            layout: "tree"
        });
    });
    var orgItems = [
        {  
            "id":"106",
            "text":"Development",
            "type":2
        },
        {  
            "id":"108",
            "text":"WPF\nTeam",
            "type":2
        },
        {  
            "id":"109",
            "text":"Javascript\nTeam",
            "type":2
        },
        // ...
    ];
    
    var orgLinks = [  
        {  
            "id":"124",
            "from":"106",
            "to":"108",
        },
        {  
            "id":"125",
            "from":"106",
            "to":"109",
        },
        // ...
    ];
  • A tree constructed from a list where each record specifies its IDs and includes a parent node ID reference. Use the dataSource option to bind the widget to the list. You should specify the keyExpr and parentKeyExpr options because of the data's plain structure. The Diagram uses information from the key fields to transform plain data into a tree.

    index.js
    data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "ID",
                    data: employees,
                }),
                keyExpr: "ID",
                textExpr: function(item, value) {
                    if(value !== undefined)
                        item.Title = value;
                    else
                        return item && item.Title.replace(" ", "\n");
                },
                parentKeyExpr: "Head_ID"
            },
            layout: "tree"
        });
    });
    var employees = [{
        "ID": 1,
        "Full_Name": "John Heart",
        "Prefix": "Mr.",
        "Title": "CEO",
        "City": "Los Angeles",
        "State": "California",
        "Email": "jheart@dx-email.com",
        "Skype": "jheart_DX_skype",
        "Mobile_Phone": "(213) 555-9392",
        "Birth_Date": "1964-03-16",
        "Hire_Date": "1995-01-15"
    }, {
        "ID": 2,
        "Head_ID": 1,
        "Full_Name": "Samantha Bright",
        "Prefix": "Dr.",
        "Title": "COO",
        "City": "Los Angeles",
        "State": "California",
        "Email": "samanthab@dx-email.com",
        "Skype": "samanthab_DX_skype",
        "Mobile_Phone": "(213) 555-2858",
        "Birth_Date": "1966-05-02",
        "Hire_Date": "2004-05-24"
    },
    // ...
    ];
  • A tree constructed from a hierarchical object. Use the dataSource option to bind the widget to the object. You should set the itemsExpr option to the name of the field that provides data for nested items because the data has a hierarchical structure.

    index.js
    data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "this",
                    data: employees,
                }),
                textExpr: function(item, value) {
                    if(value !== undefined)
                        item.Title = value;
                    else
                        return item && item.Title.replace(" ", "\n");
                },
                itemsExpr: "items"
            },
            layout: "tree"
        });
    });
    var employees = [{
        "Full_Name": "John Heart",
        "Prefix": "Mr.",
        "Title": "CEO",
        "City": "Los Angeles",
        "State": "California",
        "Email": "jheart@dx-email.com",
        "Skype": "jheart_DX_skype",
        "Mobile_Phone": "(213) 555-9392",
        "Birth_Date": "1964-03-16",
        "Hire_Date": "1995-01-15",
        "items": [{
            "Full_Name": "Samantha Bright",
            "Prefix": "Dr.",
            "Title": "COO",
            "City": "Los Angeles",
            "State": "California",
            "Email": "samanthab@dx-email.com",
            "Skype": "samanthab_DX_skype",
            "Mobile_Phone": "(213) 555-2858",
            "Birth_Date": "1966-05-02",
            "Hire_Date": "2004-05-24",
        }, {
            "Full_Name": "Arthur Miller",
            "Prefix": "Mr.",
            "Title": "CTO",
            "City": "Denver",
            "State": "Colorado",
            "Email": "arthurm@dx-email.com",
        "Skype": "arthurm_DX_skype",
            "Mobile_Phone": "(310) 555-8583",
        "Birth_Date": "1972-07-11",
            "Hire_Date": "2007-12-18",
            "items": [{
                "Full_Name": "Brett Wade",
                "Prefix": "Mr.",
                "Title": "IT Manager",
                "City": "Reno",
                "State": "Nevada",
                "Email": "brettw@dx-email.com",
                "Skype": "brettw_DX_skype",
                "Mobile_Phone": "(626) 555-0358",
                "Birth_Date": "1968-12-01",
                "Hire_Date": "2009-03-06",
    // ...

Use the layout option to specify an auto-layout algorithm ("sugiyama" or "tree") that widget uses to build a diagram.

Data Toolbox

The Diagram widget allows you to import data from a data source into a data toolbox.

Use the createDataSource method to create data toolbox items based on an external data source. End users can drag data items from the toolbox and drop them onto a canvas to build a diagram.

Diagram control data toolbox

If a data source provides information about nodes' relations, specify the layout option, to auto-generate a diagram.

index.js
data.js
$(function() {
    var diagram = $("#diagram").dxDiagram()
        .dxDiagram("instance");
    diagram.createDataSource({
        key: "0",
        title: "Employees",
        nodes: {
            dataSource: employees,
            keyExpr: "ID",
            textExpr: function(item) {
                return item && item.Full_Name.replace(" ", "\n");
            },
            parentKeyExpr: "Head_ID"
        },
        layout: "tree"
    });
});
var employees = [{
    "ID": 1,
    "Head_ID": 0,
    "Full_Name": "John Heart",
    "Prefix": "Mr.",
    "Title": "CEO",
    "City": "Los Angeles",
    "State": "California",
    "Email": "jheart@dx-email.com",
    "Skype": "jheart_DX_skype",
    "Mobile_Phone": "(213) 555-9392",
    "Birth_Date": "1964-03-16",
    "Hire_Date": "1995-01-15"
}, {
    "ID": 2,
    "Head_ID": 1,
    "Full_Name": "Samantha Bright",
    "Prefix": "Dr.",
    "Title": "COO",
    "City": "Los Angeles",
    "State": "California",
    "Email": "samanthab@dx-email.com",
    "Skype": "samanthab_DX_skype",
    "Mobile_Phone": "(213) 555-2858",
    "Birth_Date": "1966-05-02",
    "Hire_Date": "2004-05-24"
// ...

Custom Shapes

The Diagram widget provides a collection of built-in shapes. Use the customShapes option to extend this collection with custom shapes.

Diagram control custom shapes

NOTE
Shape images should be supplied as SVG files.
JavaScript
$(function() {
    var diagram = $("#diagram").dxDiagram({
        customShapes: [{
            id: 0,
            title: "Internet",
            svgUrl: "images/shapes/internet.svg",
            defaultWidth: 1.27,
            defaultHeight: 1.27,
            allowHasText: false
        },
        {
            id: 1,
            title: "Laptop",
            svgUrl: "images/shapes/laptop.svg",
            defaultWidth: 1.27,
            defaultHeight: 1.27,
            allowHasText: false
        },
        // ...
        ]
    }).dxDiagram("instance");
    // ...
});