{"id":7265,"date":"2020-05-12T12:00:14","date_gmt":"2020-05-12T09:00:14","guid":{"rendered":"https:\/\/dhtmlx.com\/blog\/?p=7265"},"modified":"2025-03-11T12:50:06","modified_gmt":"2025-03-11T09:50:06","slug":"dhtmlx-diagram-3-0-auto-layout-algorithm-smooth-configuration-custom-shapes-fully-customizable-diagram-editors","status":"publish","type":"post","link":"https:\/\/dhtmlx.com\/blog\/dhtmlx-diagram-3-0-auto-layout-algorithm-smooth-configuration-custom-shapes-fully-customizable-diagram-editors\/","title":{"rendered":"DHTMLX Diagram 3.0: Auto-Layout Algorithm, Smooth Configuration of Custom Shapes, and Fully Customizable Diagram Editors"},"content":{"rendered":"

The major release 3.0 delivered a breakthrough in the functionality of DHTMLX JavaScript diagramming library<\/a>. The new version introduced an auto-layout algorithm for automatically arranging randomly placed diagram shapes in a neat order in a matter of seconds. Other novelties include a brand new configuration property for applying default settings to all shapes at once, a convenient way of creating custom diagram shapes, and numerous customization options for JavaScript Diagram and Org Chart editors. Besides, it became possible to easily manipulate multiple shapes with the help of multiselection.<\/p>\n

Get DHTMLX Diagram 3.0 evaluation version<\/a> and try out all the new features free of charge for 30 days.<\/strong><\/p>\n

Diagram Auto Layout Algorithm<\/h5>\n

\"diagramCheck the sample ><\/a><\/p>\n

The highlight of the release is an automatic layout algorithm<\/a>, which turns chaotically located Diagram shapes into a hierarchical structure. <\/p>\n

In order to make it work, you need to add connectors between shapes. The algorithm has two modes, which differ in the way shapes will be connected. The example above demonstrates both the “direct” mode with diagonal lines between shapes and the “edges” mode with shapes with right-angle connectors. <\/p>\n

To enable an automatic arrangement of diagram shapes, you need to apply the autoPlace<\/strong> method with two optional configuration settings for specifying the mode of connecting shapes (“direct”, by default) and distance between separate diagrams in case there are several of them on a page (200px, by default). Alternatively, you can add these settings via the autoplacement<\/strong> config. In the code snippet below, we enable the auto layout in the “edges” mode with 300px distance between diagrams:<\/p>\n

var<\/span> diagram =<\/span> new<\/span> dhx.Diagram<\/span>(<\/span>"diagram"<\/span>)<\/span>;<\/span>
\ndiagram.data<\/span>.parse<\/span>(<\/span>data)<\/span>;<\/span>
\n 
\ndiagram.autoPlace<\/span>(<\/span>{<\/span>    
\n    mode:<\/span> "edges"<\/span>,<\/span>    
\n    graphPadding:<\/span> 300<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n

The diagram layout algorithm is also available in the Diagram editor. The settings of the auto layout can be defined via the autoplacement<\/strong> configuration property as in the example below. Here we have two diagrams: one with square shapes and the other with circle ones situated in random order. The auto-layout algorithm will arrange both diagrams in the “direct” mode with diagonal connectors and 100px distance between diagrams:<\/p>\n

var<\/span> editor =<\/span> new<\/span> dhx.DiagramEditor<\/span>(<\/span>document.body<\/span>,<\/span> {<\/span>
\n    autoplacement:<\/span> {<\/span>
\n        graphPadding:<\/span> 100<\/span>,<\/span>
\n        mode:<\/span> "direct"<\/span>
\n    }<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n

Our brand new hierarchical layout algorithm accelerates the creation of beautiful and complex diagrams from the UI. End-users no longer have to spend time and effort in an attempt to place each shape neatly. Now they just need to choose the necessary shapes from the right panel, connect them to each other, and press the Auto Layout button to achieve an orderly look and feel:<\/p>\n

\"AutoCheck the sample ><\/a><\/p>\n

One Property for the Default Configuration of All Shapes<\/h5>\n

DHTMLX diagramming library 3.0 introduced a new configuration property, which alone is able to save you lots of time and effort when you are creating a complex diagram with a big data set. The new defaults<\/strong><\/a> config can encompass almost all configuration options of different types of shapes significantly reducing the size of your code. <\/p>\n

Let’s take a closer look at it in the following example:<\/p>\n

const<\/span> defaults =<\/span> {<\/span>
\n    start:<\/span> {<\/span>
\n        fill:<\/span> "#FE9998"<\/span>,<\/span>
\n        stroke:<\/span> "#FE9998"<\/span>,<\/span>
\n        fontColor:<\/span> "#FFF"<\/span>,<\/span>
\n        lineHeight:<\/span> 16<\/span>
\n    }<\/span>,<\/span>
\n    end:<\/span> {<\/span>
\n        fill:<\/span> "#FE9998"<\/span>,<\/span>
\n        stroke:<\/span> "#FE9998"<\/span>,<\/span>
\n        fontColor:<\/span> "#FFF"<\/span>,<\/span>
\n        lineHeight:<\/span> 16<\/span>
\n    }<\/span>,<\/span>
\n    process:<\/span> {<\/span>
\n        fill:<\/span> "#478D99"<\/span>,<\/span>
\n        stroke:<\/span> "#478D99"<\/span>,<\/span>
\n        fontColor:<\/span> "#FFF"<\/span>,<\/span>
\n        lineHeight:<\/span> 16<\/span>
\n    }<\/span>,<\/span>
\n    decision:<\/span> {<\/span>
\n        fill:<\/span> "#F7D768"<\/span>,<\/span>
\n        stroke:<\/span> "#F7D768"<\/span>,<\/span>
\n        fontColor:<\/span> "#FFF"<\/span>,<\/span>
\n        lineHeight:<\/span> 16<\/span>
\n    }<\/span>,<\/span>
\n    document:<\/span> {<\/span>
\n        fill:<\/span> "#478D99"<\/span>,<\/span>
\n        stroke:<\/span> "#478D99"<\/span>,<\/span>
\n        fontColor:<\/span> "#FFF"<\/span>,<\/span>
\n        lineHeight:<\/span> 16<\/span>
\n    }<\/span>
\n}<\/span>;<\/span>
\n
\nconst<\/span> diagram =<\/span> new<\/span> dhx.Diagram<\/span>(<\/span>"diagram"<\/span>,<\/span> {<\/span>
\n    defaults:<\/span> defaults
\n}<\/span>)<\/span>;<\/span>
\ndiagram.data<\/span>.parse<\/span>(<\/span>activity)<\/span>;<\/span><\/div><\/div>\n

In the picture above you can see an Activity diagram depicting a flow of business activities. The defaults<\/strong> config contains a set of default configuration options for each flowchart shape used in this diagram. For instance, all Process shapes are colored in cyan (#478D99), with white font, and fixed line-height (16px). Even if we enlarge the data set with hundreds of new activities to be illustrated with Process shapes, our code will still remain as neat and concise as before. <\/p>\n

New Simple Method to Create Custom Shapes<\/h5>\n

V3.0 delivered a new API method for easily creating custom Diagram and Org Chart shapes. The new addShape<\/strong><\/a> method enables developers to specify a unique template for a newly added shape, which can contain any custom elements like images, icons, or other custom content. Optionally, you can set the default configuration of shapes with the help of the defaults<\/strong> property. <\/p>\n

Below you can see a code example of how to create a custom shape with the help of the addShape<\/strong> method for a Network diagram. Here we use an HTML template, according to the ES6+ standard, to define which custom elements to include in a shape: image, text, and string of numbers for IP address. We specify the defaults<\/strong> config to add the default properties of a Network diagram shape such as width, height, image path, text, and IP address. These properties can be overridden in the configuration of each particular shape if needed:<\/p>\n

diagram.addShape<\/span>(<\/span>"networkCard"<\/span>,<\/span> {<\/span>
\n    template:<\/span> config =><\/span> (<\/span>
\n    <<\/span>section class<\/span>=<\/span>'network_template'<\/span>>;<\/span>
\n        <<\/span>img src=<\/span>'${config.img}\u2019 alt='<\/span>${<\/span>config.text<\/span>}<\/span>\u2019'><\/img>
\n        <span>${config.text}<\/span>
\n        <span>${config.ip}<\/span>
\n    <\/section>
\n    ),
\n    defaults: {
\n        width: 160,
\n        height: 160,
\n        img: "..\/common\/img\/network_image\/desktop.svg",
\n        text: "Network Card",
\n        ip: "138.68.41.78",
\n    }
\n});<\/span><\/div><\/div>\n
Adding Custom Shapes into Live Diagram Editors<\/h5>\n

The addShape<\/strong> method also serves to quickly add custom shapes into live Diagram and Org Chart editors. All you need to do is to set the addShape<\/strong><\/a> method in the editor configuration object and apply the desired template with the default settings (if needed). The icing on the cake, all custom shapes will be automatically rendered in the editor\u2019s left panel as shape previews. <\/p>\n

Customization options delivered in v3.0 let you fine-tune the look and feel of Diagram and Org Chart editors. You can tailor-make the editors’ left and right panels entirely to your needs. <\/p>\n

Customizing the Left Panel<\/h6>\n

The new shapeSections<\/strong><\/a> configuration property enables you to categorize all shapes into several groups and show them in corresponding sections in the left panel of the Diagram editor. Additionally, you can control how shapes are previewed there.<\/p>\n

In the example below, we added four sections with previews for Custom, Sticky, Org Chart, and Flowchart shapes. Besides, we made use of the scalePreview<\/strong> configuration option to define the size of a shape preview:<\/p>\n

const<\/span> editor =<\/span> new<\/span> dhx.DiagramEditor<\/span>(<\/span>document.body<\/span>,<\/span> {<\/span>
\n    shapeSections:<\/span> {<\/span>
\n        "custom shapes"<\/span>:<\/span> [<\/span>"networkCard"<\/span>,<\/span> "medCard"<\/span>]<\/span>,<\/span>
\n        "sticky shapes"<\/span>:<\/span> [<\/span>"blue"<\/span>,<\/span> "orange"<\/span>]<\/span>,<\/span>
\n        "org chart shapes"<\/span>:<\/span> [<\/span>"card"<\/span>,<\/span> "img-card"<\/span>]<\/span>,<\/span>
\n        "flowchart shapes"<\/span>:<\/span> [<\/span>true<\/span>]<\/span>,<\/span>
\n    }<\/span>,<\/span>
\n    scalePreview:<\/span> 0.65<\/span>,<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n

Alternatively, it’s possible to add an image instead of an automatically rendered shape preview with the help of the preview<\/strong> property of the defaults<\/strong> attribute for previewing a particular shape. The width and height parameters can be specified to define the size of an image preview.<\/p>\n

Moreover, you can change the distance between shape previews using the gapPreview<\/strong> property and specify the width of the left panel using the shapeBarWidth<\/strong> configuration property.<\/p>\n

Customizing the Right Panel<\/h6>\n

\"JavaScriptCheck the sample ><\/a><\/p>\n

The right panel of the Diagram editor will automatically render sidebar options for editing custom shapes with standard attributes like title, text, fill, stroke, etc. depending on the dataset of a shape, as shown in the example above.<\/p>\n

However, dealing with complex custom shapes you might need to equip the editor with special tools for modifying various custom elements in Diagram and Org Chart editors. For that purpose, we introduced the properties<\/strong><\/a> attribute of the addShape<\/strong> method, which allows changing the sidebar options available for editing by end-users in the right panel.<\/p>\n

For instance, here is an Org Chart editor with custom shapes to illustrate the hierarchy of a medical establishment:<\/p>\n

https:\/\/dhtmlx.com\/blog\/wp-content\/uploads\/2020\/05\/Medichal-hierarchy-org-chart-editor-video.mp4<\/a><\/video><\/div>Check the sample ><\/a><\/p>\n

Custom Org Chart shapes contain several text elements for a doctor’s name and position, fields for a phone number and email address, and a photo. Each element can be edited from the UI due to a range of editing tools in the right panel. As you can see in the code example, the properties<\/strong> attribute includes options for defining the shape’s position and size, doctor’s name, post, phone number, and email address as well as a photo to be loaded into the chosen shape. Editing options are represented in the sidebar exactly in the same order in which they are specified in the properties<\/strong> attribute:<\/p>\n

editor.diagram<\/span>.addShape<\/span>(<\/span>"template"<\/span>,<\/span> {<\/span>
\n    template:<\/span> template,<\/span>
\n    defaults:<\/span> {<\/span>
\n        name:<\/span> "Name and First name"<\/span>,<\/span>
\n        post:<\/span> "Position held"<\/span>,<\/span>
\n        phone:<\/span> "(405) 000-00-00"<\/span>,<\/span>
\n        mail:<\/span> "some@mail.com"<\/span>,<\/span>
\n        photo:<\/span> "..\/common\/big_img\/big-avatar-1.jpg"<\/span>,<\/span>
\n
\n        height:<\/span> 115<\/span>,<\/span> width:<\/span> 330<\/span>
\n    }<\/span>,<\/span>
\n    properties:<\/span> [<\/span>
\n        {<\/span> type:<\/span> "position"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "size"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "text"<\/span>,<\/span> label:<\/span> "name"<\/span>,<\/span> property:<\/span> "name"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "text"<\/span>,<\/span> label:<\/span> "post"<\/span>,<\/span> property:<\/span> "post"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "text"<\/span>,<\/span> label:<\/span> "phone"<\/span>,<\/span> property:<\/span> "phone"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "text"<\/span>,<\/span> label:<\/span> "email"<\/span>,<\/span> property:<\/span> "mail"<\/span> }<\/span>,<\/span>
\n        {<\/span> type:<\/span> "img"<\/span>,<\/span> label:<\/span> "photo"<\/span>,<\/span>  property:<\/span> "photo"<\/span> }<\/span>
\n    ]<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n
var<\/span> editor =<\/span> new<\/span> dhx.DiagramEditor<\/span>(<\/span>document.body<\/span>,<\/span> {<\/span>
\n    controls:<\/span> {<\/span>
\n        import<\/span>:<\/span> true<\/span>,<\/span>
\n        export<\/span>:<\/span> true<\/span>,<\/span>
\n        gridStep:<\/span> true<\/span>,<\/span>
\n        autoLayout:<\/span> true<\/span>,<\/span>
\n        editMode:<\/span> true<\/span>,<\/span>
\n        historyManager:<\/span> false<\/span>
\n        apply:<\/span> false<\/span>,<\/span>
\n        reset:<\/span> false<\/span>
\n    }<\/span>,<\/span>
\n}<\/span>)<\/span>;<\/span><\/div><\/div>\n
New Use Cases for Searching and Zooming in Diagrams<\/h5>\n

We prepared a couple of new samples covering the most popular cases of using JavaScript diagrams, according to our users’ requests.
\nOne of the demanded examples is implementing a search functionality for navigating through vast Diagrams and Org Charts:
\n\"SearchCheck the sample ><\/a><\/p>\n

Another sample demonstrates how Org Chart shapes change their appearance depending on the scale while zooming in and out:
\n\"Zoom\"Check the sample ><\/a><\/p>\n

We do hope that the new functionality and samples of DHTMLX Diagram 3.0 will come in useful in your applications. Dive into the new features by downloading a free 30-day trial version<\/a> and benefit from the assistance of our technical support team if any questions arise.<\/p>\n

We’ll be looking forward to your feedback – leave your comments below!<\/p>\n

Current clients are invited to get the latest version of DHTMLX Diagram in their Client’s Area<\/a>.<\/p>\n

Stay tuned for future updates!<\/p>\n

Related Materials:<\/h5>\n
Multiselection of Shapes<\/h6>\n

Another significant enhancement in the work of editors is the ability to manipulate several shapes and connectors at once. V3.0 brought out the multiselection<\/a> feature for dragging, copying, pasting, and deleting shapes. To select multiple shapes, you can either hover the mouse over them while keeping the left mouse button pressed or left click on each shape while pressing Shift.<\/p>\n

\"Shapes'Check the sample ><\/a><\/p>\n

Additionally, now you can define which controls to make available in the Editor via the controls<\/strong><\/a> property. For instance, you can enable the Import and Export controls, the Grid Step option, which sets the step of moving shapes, the Auto Layout control, and the Edit Mode button, and disable the Undo and Redo, Apply and Reset changes buttons:<\/p>\n

\"LeftCheck the sample ><\/a><\/p>\n

Thus, you can create a slick Network diagram like in the picture below:
\n\"JavaScriptCheck the sample ><\/a><\/p>\n

\"JavaScriptCheck the sample ><\/a><\/p>\n

\"DiagramCheck the sample ><\/a><\/p>\n