All docs
V20.1
20.2 (CTP)
20.1
19.2
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
17.1
The page you are viewing does not exist in version 17.1. This link will take you to the root page.
16.2
The page you are viewing does not exist in version 16.2. This link will take you to the root page.

Data Binding

The Diagram can load external tree-like and graph structures. The supported data structures are listed below.

  • Node and Edge Arrays: the information about nodes is maintained separately from the information about edges.
  • Linear Array: nodes are maintained in a linear data structure and are connected by Key - Parent Key reference.
  • Hierarchical Array: nodes are maintained in hierarchical data structure.

When you bind a Diagram widget to a data source, you should specify options that allow the widget to create the diagram structure. The supported data structures differ in required options.

Required Options Node and Edge Arrays Linear Array Hierarchical Array
nodes.keyExpr
edges.keyExpr
nodes.parentKeyExpr
nodes.itemsExpr

Node and Edge Arrays

View Demo

Use the nodes.dataSource and edges.dataSource options to bind the Diagram widget to plain lists of nodes and edges.

Specify the following required options: nodes.keyExpr, edges.keyExpr.

Do not specify the parentKeyExpr and itemsExpr options, because they are a part of another binding mode.

During the binding process, the widget creates a shape for every bound node and a connector for every bound edge. To attach a start or end of a connector to a shape, use the edges.fromExpr and edges.toExpr options. These expressions should return keys of attached nodes.

index.js
data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "this",
                    data: orgItems
                }),
                keyExpr: "id",
                textExpr: "text",
            },
            edges: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "this",
                    data: orgLinks
                }),
                keyExpr: "id",
                fromExpr: "from",
                toExpr: "to"
            },
        });
    });
    var orgItems = [{  
        "id":"101",
        "text":"Development",
    },{  
        "id":"102",
        "text":"Javascript\nTeam",
    },{  
        "id":"103",
        "text":"ASP.NET\nTeam",
    }];

    var orgLinks = [{  
        "id":"121",
        "from":"101",
        "to":"102",
    },{  
        "id":"122",
        "from":"101",
        "to":"103",
    }];

Diagram - Node and Edge Arrays

Linear Array

View Demo

Use the nodes.dataSource option to bind the widget to a list of nodes where each record specifies a node's key value and includes a parent node's key value reference.

Specify the following required options: nodes.keyExpr, nodes.parentKeyExpr.

Do not specify the nodes.itemsExpr and edges options because they are a part of another binding mode.

During the binding process, the widget creates a shape for every bound node and a connector between every pair of nodes linked by the Key - Parent Key reference. Note that edges are not maintained as entities in a data source, thus a detached connector disappears after rebinding.

index.js
data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "this",
                    data: employees
                }),
                keyExpr: "ID",
                parentKeyExpr: "Head_ID",            
                textExpr: "Title",
                heightExpr: function() {return 0.4} 
            },
        });
    });
    var employees = [{
        "ID": 3,
        "Full_Name": "Arthur Miller",
        "Title": "CTO",
    }, {
        "ID": 6,
        "Head_ID": 3,
        "Full_Name": "Brett Wade",
        "Title": "IT Manager",
    }, {
        "ID": 9,
        "Head_ID": 3,
        "Full_Name": "Barb Banks",
        "Title": "Support Manager",
    }, {
        "ID": 18,
        "Head_ID": 9,
        "Full_Name": "James Anderson",
        "Title": "Support Assistant",
    }, {
        "ID": 21,
        "Head_ID": 6,
        "Full_Name": "Taylor Riley",
        "Title": "Network Admin",
    }, {
        "ID": 23,
        "Head_ID": 6,
        "Full_Name": "Wally Hobbs",
        "Title": "Programmer",
    }, {
        "ID": 24,
        "Head_ID": 6,
        "Full_Name": "Brad Jameson",
        "Title": "Programmer",
    }];

Diagram - Node and Edge Arrays

Hierarchical Array

View Demo

Use the nodes.dataSource option to bind the widget to a hierarchical object.

Specify the following required options: nodes.keyExpr, nodes.itemsExpr.

Do not specify the nodes.parentKeyExpr and edges options because they are a part of another binding mode.

During the binding process, the widget creates a shape for every bound node and all connectors that are between a node and its children. Note that the edges are not maintained as entities in a data source, thus the detached connector disappears after it is rebound.

index.js
data.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                dataSource: new DevExpress.data.ArrayStore({
                    key: "this",
                    data: employees
                }),
                keyExpr: "ID",
                textExpr: "Title",
                itemsExpr: "Items",
            },
        });
    });
    var employees = [{
        "ID": 3,
        "Full_Name": "Arthur Miller",
        "Title": "CTO",
        "Items": [{
            "ID": 6,
            "Full_Name": "Brett Wade",
            "Title": "IT Manager",
            "Items": [{
                "ID": 21,
                "Full_Name": "Taylor Riley",
                "Title": "Network Admin",
            }, {
                "ID": 23,
                "Full_Name": "Wally Hobbs",
                "Title": "Programmer",
            }, {
                "ID": 24,
                "Full_Name": "Brad Jameson",
                "Title": "Programmer",
            }]
        }, {
            "ID": 9,
            "Full_Name": "Barb Banks",
            "Title": "Support Manager",
            "Items": [{
                "ID": 18,
                "Full_Name": "James Anderson",
                "Title": "Support Assistant",
            }]
        }]
    }];

Diagram - Node and Edge Arrays

Diagram Layout

The widget creates a diagram layout based on the algorithm specified by the autoLayout.orientation and autoLayout.type options.

index.js
    $(function() {
        $("#diagram").dxDiagram({
            nodes: {
                autoLayout: {
                    orientation: "horizontal"
                    type: "tree",
                },
                ...
            },
        });
    });

You can create a diagram layout based on shape coordinates maintained in a data source. Set the leftExpr and topExpr options to names of data source fields that provide shape coordinates.

If you bind a Diagram to an array of edges, you can specify a shape's connection point where an edge begins (fromPointIndexExpr) and ends (toPointIndexExpr) and provide additional points for connectors with the pointsExpr option.

Shape and edge point coordinates are specified in units.

NOTE

If the autoLayout.type option is set to auto (default value), and both the leftExpr and topExpr options are specified, the autolayout feature is disabled. The widget creates a diagram layout based on the provided coordinates. If the position options are not specified, the auto type denotes the layered layout.

If the autoLayout.type option is set to layered or tree, predefined shape coordinates (leftExpr and topExpr) and edge points (pointsExpr) are ignored.

index.js
data.js
$(function() {
    $("#diagram").dxDiagram({
        nodes: {
            dataSource: new DevExpress.data.ArrayStore({
                key: "this",
                data: orgItems
            }),
            autoLayout: {
                type: "off"
            },
            keyExpr: "key",
            leftExpr: "left",
            textExpr: "text",
            topExpr: "top",
        },
        edges: {
            dataSource: new DevExpress.data.ArrayStore({
                key: "this",
                data: orgLinks
            }),
            keyExpr: "key",
            fromExpr: "from",
            toExpr: "to",
            fromPointIndexExpr: "fromPoint",
            toPointIndexExpr: "toPoint",
            pointsExpr: "points",
        },
        units: "in",
    });
});
var orgItems = [
  {  
        key: "101",
        left: 0.5,
        text: "Product Manager",
        top: 0.875,
  },
  {  
        key: "102",
        left: 2.5,
        text: "Team",
        top: 0.5,
    },
];
var orgLinks = [  
  {  
        key: "1",
        from: "101",
        to: "102",
        fromPoint: 1,
        toPoint: 3,
        points: [{x:1.5,y:1.125},{x:1.75,y:0.875},{x:2.5,y:0.875}],
  },
];

Optional Binding Expressions

The Diagram allows you to bind a number of shape and connector visual properties, like type, size, and style.

NOTE
If a binding option is undefined, the corresponding shape or connector property value is maintained inside the loaded Diagram widget and is lost after a page is reloaded.

Diagram - Data Binding Options

Node option Value the option should return Sample return value
containerChildrenExpr A container's nested items. This option is in effect for verticalContainer or horizontalContainer nodes. Excludes containerKeyExpr. [{"id":"112","text":"Ana\nTrujillo"}, {"id":"113","text":"Antonio\nMoreno"}]
containerKeyExpr A parent container node key. The parent container node must be of the verticalContainer or horizontalContainer type. Excludes containerChildrenExpr. "102"
heightExpr A node's height, in units. 0.625
imageUrlExpr A node's image URL or Base64 encoded image. This option is in effect for nodes of the cardWithImageOnLeft, cardWithImageOnTop, or cardWithImageOnRight type. "images/employees/30.png"
leftExpr The x-coordinate of a node's left border, in units. 0.5
lockedExpr A value that indicates whether a node is locked.
Should return true or false.
true
styleExpr A node's style. { "stroke": "red" }
textExpr A node's text. "ASP.NET"
textStyleExpr A node's text style. { "font-weight": "bold", "text-decoration": "underline" }
topExpr The y-coordinate of a node's top border, in units. 0.875
typeExpr A node's shape type. Built-in shape types are shown in the Shape Types section. "horizontalContainer"
widthExpr A node's width, in units. 2
zIndexExpr A node's z-index. 1
NOTE
If you bind a Diagram to a linear or hierarchical array, edge binding options are not in effect, because connectors are not bound to specific edges. This is why the storage of connector styles in a data source is not supported.
Edge option Value the option should return Sample return value
fromExpr An edge's start node key. "101",
fromLineEndExpr An edge's line start tip.
Should return "arrow", "filledTriangle", "outlinedTriangle", or "none".
"none"
fromPointIndexExpr A shape's connection point index where an edge begins. 1
lineTypeExpr An edge's line type.
Should return "orthogonal" or "straight".
"straight"
lockedExpr A value that indicates whether a node is locked.
Should return true or false.
false
pointsExpr An edge's key points. [{x:1.5,y:1.125},{x:1.75,y:0.875},{x:2.5,y:0.875}]
styleExpr An edge's style. {"stroke-dasharray":"4"}
textExpr An edge's text. "text" or { 0.3: "text1", 0.8: "text2" }
textStyleExpr An edge's text style. { "font-weight": "bold"}
toExpr An edge's end node key. "102",
toLineEndExpr An edge's line end tip.
Should return "arrow", "filledTriangle", "outlinedTriangle", or "none".
"filledTriangle"
toPointIndexExpr A shape's connection point index where an edge ends. 11
zIndexExpr A edge's z-index. 0

You can set a binding option to a name of a data source field that provides item values, or to an expression that returns a constant value or calculates a value in runtime based on conditions.

Diagram - Data Bound Diagram

index.js
data.js
$(function() {
    $("#diagram").dxDiagram({
        nodes: {
            dataSource: new DevExpress.data.ArrayStore({
                key: "this",
                data: orgItems
            }),
            autoLayout: {
                type: "off"
            },
            childrenExpr: "children",
            heightExpr: "height",
            imageUrlExpr: "imageUrl",
            keyExpr: "key",
            leftExpr: "left",
            lockedExpr: "locked",
            styleExpr: function(obj) {if (obj.type.includes("Container")) return {"stroke": "red"}},
            textExpr: "text",
            textStyleExpr: "textStyle",
            topExpr: "top",
            typeExpr: "type",
            widthExpr: "width",
            zIndexExpr: "zIndex",
        },
        edges: {
            dataSource: new DevExpress.data.ArrayStore({
                key: "this",
                data: orgLinks
            }),
            fromExpr: "from",
            fromLineEndExpr: function() {return "none"},
            fromPointIndexExpr: "fromPointIndex",
            keyExpr: "key",
            lineTypeExpr: function() {return "straight"},
            lockedExpr: "locked",
            pointsExpr: "points",
            styleExpr: function() {return ({"stroke-dasharray":"4"})},
            textExpr: "text",
            textStyleExpr: "textStyle",
            toExpr: "to",
            toLineEndExpr: function() {return "arrow"},
            toPointIndexExpr: "toPointIndex",
        },
    });
});
var orgItems = [
  {  
        height: 0.625,
        key: "101",
        left: 0.5,
        locked: true,
        text: "Product Manager",
        textStyle: { "font-weight": "bold", "text-decoration": "underline" },
        top: 0.875,
        type: "rectangle",
        width: 1,
        zIndex: 2,
  },
  {  
        height: 1.375,
        key: "102",
        left: 2.5,
        locked: false,
        text: "Team",
        textStyle: { "font-weight": "bold", "text-decoration": "underline" },
        top: 0.5,
        type: "horizontalContainer",
        width: 2,
        zIndex: 1,
        children: [
        {  
            height: 0.5,
            imageUrl: "images/employees/30.png",
            key: "103",
            left: 2.875,
            text: "Team Leader",
            top: 0.625,
            type: "cardWithImageOnLeft",
            width: 1.5,
        },
        {  
            height: 0.5,
            key: "104",
            left: 2.875,
            text: "Developers",
            top: 1.25,
            type: "rectangle",
            width: 1.5,
        },

    ]
    },
];
var orgLinks = [  
  {  
        from: "101",
        fromPointIndex: 1,
        key: "1",
        locked: false,
        points: [{x:1.5,y:1.125},{x:1.75,y:0.875},{x:2.5,y:0.875}],
        text: "Task",
        textStyle: { "font-weight": "bold"},
        to: "102",
        toPointIndex: 11,
  },
];