Migration to newer versions

5.0 -> 6.0

Diagram Editor structure

The main parts of the Diagram Editor are renamed:

Left panel -> Shapebar
Right panel -> Editbar is provided with a flexible configuration

The default Toolbar structure has been modified. It became highly configurable as well, so you can also add custom Toolbar elements.

Diagram Editor API

The view object is introduced for configuring the Diagram Editor panels:

view?: {
    toolbar?: boolean | obj,
    shapebar?: boolean | obj,
    editbar?: boolean | obj
}

Check the related API overview guides to explore the new possibilities of managing panels:

Deprecated methods

The setViewMode() method of Diagram Editor is deprecated and no longer supported. Instead, use the show()/hide() methods of the view object.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container");
editor.parse(data);

editor.setViewMode("preview"); // "preview" or "edit"

From v6.0
const editor = new dhx.DiagramEditor("editor_container");
editor.parse(data);

editor.view.hide("shapebar"); 
editor.view.hide("editbar");

Deprecated properties

The reservedWidth property of Diagram Editor is deprecated and no longer supported.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    reservedWidth: 150
});

Instead, use the following syntax:

From v6.0
editor.diagram.config.margin.x = 40; 

The editMode property of Diagram Editor is deprecated and no longer supported. Instead, use the corresponding property of the view object (toolbar, shapebar, editbar).

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    editMode: false
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    view: {
        toolbar: false,
        shapebar: false, // only for "default" mode
        editbar: false
    }
});

The controls property of Diagram Editor is deprecated and no longer supported. Instead, use the items property of the view.toolbar configuration.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    controls: { 
        // ...
    }
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    view: {
        toolbar: {
            items: []
        }
    }
});

The shapeBarWidth property of Diagram Editor is deprecated and no longer supported. Instead, use the width property of the view.shapebar configuration.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    shapeBarWidth: 190
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    view: {
        shapebar: {
            width: 400 // 300 by default
        }
    }
});

The shapeSections property of Diagram Editor is deprecated and no longer supported. Instead, use the sections property of the view.shapebar configuration.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    shapeSections: {
        "Swimlane": [{ swimlane: true }],
        "Groups": [{ group: true }],   
        "Flowchart shapes": [{ flowShapes: true }],
        "Org shapes, text, topic": [{ org: true }, "text", "topic"]
    }
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    view: {
        shapebar: {
            sections: {
                "Swimlane": [{ swimlane: true }],
                "Groups": [{ group: true }],   
                "Flowchart shapes": [{ flowShapes: true }],
                "Org shapes, text, topic": [{ org: true }, "text", "topic"]
            }
        }
    }
});

The gapPreview property of Diagram Editor is deprecated and no longer supported. Instead, use the gap property of the preview object of the view.shapebar configuration.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    gapPreview: 10
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    view: {
        shapebar: {
            preview: {
               scale: 0.65,
               gap: 8
            }
        }
    }
});

The scalePreview property of Diagram Editor is deprecated and no longer supported. Instead, use the scale property of the preview object of the view.shapebar configuration.

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    gapPreview: 10
});

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    view: {
        shapebar: {
            preview: {
               scale: 0.65,
               gap: 8
            }
        }
    }
});

Deprecated events

The following events of Diagram Editor are deprecated and no longer supported, since there are no corresponding buttons in the toolbar: resetButton, applyButton, visibility, exportData, importData, autoLayout. Instead, you can listen to the click event of the toolbar object of Diagram Editor:

editor.toolbar.events.on("click", id => console.log(id));

note

The names of the service elements ids start from the $ symbol.

The changeGridStep event of Diagram Editor is deprecated and no longer supported.

Diagram API

The properties property of the addShape method is deprecated and no longer used. The configuration of a custom shape in the editbar of the Editor is implemented via the properties property of the Editbar panel:

Before v6.0
const editor = new dhx.DiagramEditor("editor_container", { 
    type: "default"  
});
editor.parse(data);

editor.diagram.addShape("network", {
    template: config => (
        `<section className='template'>
            <h3>${config.title}</h3>
            <ul><li>${config.text.join("</li><li>")}</li></ul>
        </section>`
    ),
    properties:[
        { type:"arrange" },
        { type:"size" }
    ]
});   

From v6.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    view: {
        shapebar: {
            sections: {
                "Network shapes": [
                    { type: "network", text: "Core", img: src + "core.svg" },
                    { type: "network", text: "Server", img: src + "server.svg" }
                ],
                "Flow shapes": [{ flowShapes: true }]
            }
        },
        editbar: {
            properties: {
                network: [
                    { type: "arrange" },
                    {
                        type: "fieldset",
                        label: "Network information",
                        rows: [
                            { type: "avatar", key: "img", circle: true, readOnly: true },
                            { type: "textarea", key: "text", label: "Description" },
                            { type: "input", key: "ip", label: "IP" }
                        ]
                    }
                ]
            }
        }
    }
});

editor.parse(data);

editor.diagram.addShape("network", {
    template: ({ img, text, ip }) => {
        return `
            <section className="dhx_diagram_template_d">
                <img className="dhx_diagram_template_d__image" src="${img}" alt="${text}"/></img>
                <span className="dhx_diagram_template_d__title">${text}</span>
                <span className="dhx_diagram_template_d__text">${ip}</span>
            </section>
        `;
    },
    defaults: {
        width: 160, height: 160,
        preview: { scale: 0.7 },
        ip: "127.0.0.1"
    }
});

Diagram Selection API

The getId() method of the Selection object of Diagram is deprecated and no longer supported. Instead you can use the getIds() and getItem() methods of the Selection object. Check the examples below:

Before v6.0
// diagram must be created with the "select:true" option
const diagram = new dhx.Diagram("diagram_container", { 
    select: true 
});
diagram.data.parse(data);

const id = diagram.selection.getId(); // -> "2"

From v6.0
// a diagram must be created with the "select:true" option
const diagram = new dhx.Diagram("diagram_container", { 
    select: true 
});
diagram.data.parse(data);

// returning the last selected element
let id = diagram.selection.getIds().at(-1);
id = diagram.selection.getItem().id;

Shape properties

The usage of the text property of the Shape configuration object is limited to the string value only. Its usage as an array of string values while configuring a custom shape is deprecated and no longer supported.

Line titles

The titles of Lines are moved from the line objects to the common data structure on the same level with Lines and defined as lineTitles objects.

Before v6.0 titles of lines have been specified inside the line object as follows:

Before v6.0
const data = [
    // line object
    {
        // line object properties
        title?: {
            fontSize?: number | string, // 14 by default
            lineHeight?: number | string, // 14 by default
            textAlign?: "center" | "left" | "right", // "center" by default
            textVerticalAlign?: string,
            fontStyle?: "normal" | "italic" | "oblique", // "normal" by default
            fontColor?: string, // "#4C4C4C" by default
            fontWeight?: string, // "500" by default
            fill?: string,
            editable?: boolean, // true by default
            hidden?: boolean,
            draggable?: boolean,
            autoPosition?: boolean,
            text?: [
                {
                    id?: string | number,
                    type?: "$linetext",
                    width?: number,
                    height?: number,
                    distance?: number,
                    autoPosition?: boolean,
                    hidden?: boolean,
                    editable?: boolean, // true by default
                    draggable?: boolean,
                    fill?: string,
                    text?: string,
                    fontSize?: number | string, // 14 by default
                    lineHeight?: number | string, // 14 by default
                    fontStyle?: "normal" | "italic" | "oblique", // "normal" by default
                    fontColor?: string, // "#4C4C4C" by default
                    fontWeight?: string, // "500" by default
                    textAlign?: "center" | "left" | "right", // "center" by default
                    textVerticalAlign?: "center" | "top" | "bottom" // "center" by default
                },
                // more objects for text items of a line
            ]
        }
    },
    // more line objects
]

From v6.0 line titles are defined in separate objects with the "lineTitle" type. The lineTitle object has the following configuration properties:

From v6.0
const data = [
    // line title object
    {
        type: "lineTitle",
        id?: string | number,
        text: string,
        parent: string | number, 

        distance?: number, // 50 by default
        autoPosition?: boolean, // true by default
        editable?: boolean, // true by default
        fixed?: boolean, // false by default
        hidden?: boolean, // false by default

        fill?: string,
        fontSize?: string | number, // 14 by default
        lineHeight?: string | number, // 14 by default
        fontStyle?: "normal" | "italic" | "oblique", // "normal" by default
        fontColor?: string, // "#4C4C4C" by default
        fontWeight?: string, // "500" by default
        textAlign?: "center" | "left" | "right" // "center" by default
    },
    // more objects
];

Check the details in the LineTitles API and guides.

Localization

Due to the modifications in the Diagram editor interface, the locale settings have been updated. Check the Localization guides for details.

4.2 -> 5.0

Diagram API

The lineGap property of Diagram is deprecated and no longer supported. Instead, use the lineGap parameter of the lineConfig property.

Before v5.0
const diagram = new dhx.Diagram("diagram_container", { 
    type: "default",
    lineGap: 30
});

From v5.0
const diagram = new dhx.Diagram("diagram_container", { 
    type: "default",
    lineConfig: {
        lineGap: 30
    },
    // other config parameters
});

Editor API

The lineGap property of Diagram Editor is deprecated and no longer supported. Instead, use the lineGap parameter inside the lineConfig property.

Before v5.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    lineGap: 30
});

From v5.0
const editor = new dhx.DiagramEditor("editor_container", {
    type: "default",
    lineConfig: {
        lineGap: 30
    },
    // other config parameters
});

4.1 -> 4.2

Diagram API

In v4.2, the defaultLinkType property is deprecated.

Starting from v4.2, you need to apply the new lineConfig property to specify the default type for connector lines.

Before v4.2
const diagram = new dhx.Diagram("diagram_container", { 
    defaultLinkType: "dash"
});

From v4.2
const diagram = new dhx.Diagram("diagram_container", { 
    lineConfig: {
        lineType: "dash",
    },
    // other config parameters
});

Editor API

The syntax of specifying basic sets of items for sections in the left panel of the editor has been changed.

Before v4.2, you could set boolean true value to the array of the section's items to display all available flow-chart shapes in the section:

Before v4.2
const editor = new dhx.DiagramEditor("editor_container", {
    shapeSections: {
        "flowchart shapes": [true],
        "text": ["text"],
        "mind map shape": ["topic"]
    },
});

Starting from v4.2, you need to use the different syntax for this purpose:

From v4.2
const editor = new dhx.DiagramEditor("editor_container", {
    shapeSections: {
        "flowchart shapes": [{ flowShapes: true }],
        "text": ["text"],
        "mind map shape": ["topic"]
    },
});

Besides, it became possible to specify other basic sets of items via the related key:value pairs. For more details, check the shapeSections article.

3.1 -> 4.0

API

The shapeHover event has been deprecated in v4.0. Starting with v4.0, use the new itemMouseOver event instead.

Before v4.0
diagram.events.on("shapeHover", (id,e) => {
    console.log("An item"+ diagram.data.getItem(id).text +"has been hovered over");
});

From v4.0
diagram.events.on("itemMouseOver", (id, event) => {
    console.log(id, event);
});
// For diagram editor
editor.diagram.events.on("itemMouseOver", (id, event) => {
    console.log(id, event);
});

3.0 -> 3.1

Editor API

The shapeMove event of the editor object has been deprecated in v3.1. Starting with v3.1, use the new BeforeShapeMove and AfterShapeMove events instead.

Before v3.1
editor.events.on("shapeMove", () => {
    console.log("The shape is moved");
});

From v3.1
// BeforeShapeMove event
editor.events.on("BeforeShapeMove", (e) => {
    console.log("Before the shape is moved:", e);
    return true;
});

// AfterShapeMove event
editor.events.on("AfterShapeMove", (e) => {
    console.log("After the shape is moved:", e);
});

2.2 -> 3.0

Creating custom shapes

The way of creating custom shapes has been changed, simplified and improved.

Starting from v3.0, in order to create your own types of shapes, the new addShape method should be used instead of the diagram.flowShapes object. The method provides you with the ability to create HTML templates that will work in different browsers. Besides, the method allows creating and editing custom shapes in Diagram Editor.

Despite the diagram.flowShapes object has been deprecated, it will still continue working.

Before version 3.0 you were able to show/hide toolbar buttons in Diagram Editor via the related showApply, showReset, showExport configuration properties of the Editor.

In the version 3.0 these properties are deprecated and removed. Instead, the controls config property that contains a set of control_name:value pairs is added. Thus, the properties are replaced with:

showApply -> controls.apply
showReset -> controls.reset
showExport -> controls.export

const editor = new dhx.DiagramEditor("editor_container", {
    controls: { 
        apply: false,
        reset: false,
        export: true
    }
});

To enable/disable a toolbar button you need to specify the value of the control to true (by default) or false.

See the full list of the available controls in the Toolbar article.

1.1 -> 2.0

Removed API

diagram.eachChild

Changed API

diagram.addItem -> diagram.data.add
diagram.attachEvent -> diagram.events.on
diagram.callEvent -> diagram.events.fire
diagram.clearAll -> diagram.data.removeAll
diagram.deleteItem -> diagram.data.remove
diagram.detachEvent -> diagram.events.detach
diagram.eachItem -> diagram.data.map
diagram.getItem -> diagram.data.getItem
diagram.getSelectedId -> diagram.selection.getId
diagram.load -> diagram.data.load
diagram.parse -> diagram.data.parse
diagram.selectItem -> diagram.selection.add
diagram.serialize -> diagram.data.serialize
diagram.unselectItem -> diagram.selection.remove
diagram.updateItem -> diagram.data.update

5.0 -> 6.0​

Diagram Editor structure​

Diagram Editor API​

Deprecated methods​

Deprecated properties​

Deprecated events​

Diagram API​

Diagram Selection API​

Shape properties​

Line titles​

Localization​

4.2 -> 5.0​

Diagram API​

Editor API​

4.1 -> 4.2​

Diagram API​

Editor API​

3.1 -> 4.0​

API​

3.0 -> 3.1​

Editor API​

2.2 -> 3.0​

Creating custom shapes​

Toolbar buttons in Editor​

1.1 -> 2.0​

Removed API​

Changed API​

5.0 -> 6.0

Diagram Editor structure

Diagram Editor API

Deprecated methods

Deprecated properties

Deprecated events

Diagram API

Diagram Selection API

Shape properties

Line titles

Localization

4.2 -> 5.0

Diagram API

Editor API

4.1 -> 4.2

Diagram API

Editor API

3.1 -> 4.0

API

3.0 -> 3.1

Editor API

2.2 -> 3.0

Creating custom shapes

Toolbar buttons in Editor

1.1 -> 2.0

Removed API

Changed API