Manipulating Shapes

It is easy to manipulate the shapes of dhtmlxDiagram via the component's API. You can perform a range of operations over shapes, in particular:

add/update/delete shapes
check if an item exists in the diagram and get it
select a certain shape
scroll to a necessary shape to make it visible on the screen, if there are many shapes in the diagram
expand/collapse shapes
find shapes that meet some criteria
filter diagram to render particular shapes

Adding Shape

To add a new shape into a diagram, apply the add method of the data object. It takes a new item object as a parameter:

diagram.data.add({ id: "3.2", text: "New Item", parent: "3" });

A new item object has the following attributes:

id - (string|number) the unique id of a shape
text - (string) the text to be rendered in a shape
parent - (string|number) the id of the parent shape

Check all available properties of shape objects in Diagram and in Org Chart.

Getting Shape

You can get the object of a shape by passing its id to the getItem method of the data object:

var shape = diagram.data.getItem(1);

After getting an item, you can access its original properties, as follows:

var shape = diagram.data.getItem(1);
var text = shape.text;

Getting Shape Id

If the id of a shape is unknown, you can use the getId method to get it. The method takes the index of the item as a parameter:

var id = diagram.data.getId(0); // -> returns "1"

Getting Item Index

You can get the index of a shape by passing its id to the getIndex method:

var id = diagram.data.getIndex("1"); // -> returns 0

Deleting Shapes

Deleting a single shape

To delete an unnecessary shape, make use of the remove method of the data object and pass as a parameter the id of the shape under question:

diagram.data.remove("3.2");

In case of Org Chart, deleting a shape will remove its connectors and all child shapes as well.

Deleting all the shapes

If necessary, you can clear the diagram, by deleting all the shapes at once. For this, apply the removeAll method of the data object:

diagram.data.removeAll();

Updating Shape

You can update the look and content of a shape with the help of the update method of the data object:

diagram.data.update("1", { text: "Some new text" });

As parameters, you need to pass two parameters:

id - (string|number) the id of the shape
config - (object) an object with updated configuration properties

Related sample: Org Chart Update Item

Checking Existence of Shape

You can check whether a shape exists in the diagram via the exists method of the data collection. The method takes the id of the shape as a parameter and returns true, if the shape exists:

var shapeExists = diagram.data.exists("1");

Selecting Shapes

Selecting a shape

To select shapes, you need firstly enable selection for the diagram and then call the add method of the selection object to select a desired shape.

var diagram = new dhx.Diagram("diagram_container", { select: true });
diagram.data.parse(data);
 
diagram.selection.add("2");

The method takes the shape id as a parameter.

Unselecting a shape

To unselect a selected shape, make use of the remove method of the selection object:

diagram.selection.remove("2");

Getting the id of a selected shape

You can get the id of the currently selected shape with the getId method of the selection object:

var selected = diagram.selection.getId();

Getting the object of a selected shape

It is also possible to get the object of a selected shape using the getItem method of the selection object:

var shape = diagram.selection.getItem();

Check all available properties of shape objects in Diagram and in Org Chart.

Expanding/Collapsing Shapes

You can expand and collapse a shape that have child shapes via the corresponding API methods: expandItem and collapseItem. Both methods take the id of the shape as a parameter.

// expanding the item with the id "3"
diagram.expandItem("3");
 
// collapsing the item with the id "3"
diagram.collapseItem("3");

Showing Necessary Shape

In case you have a large diagram with lots of shapes, dhtmlxDiagram provides you with the possibility to make the desired item visible. For this, you need to apply the showItem method, which takes the id of a shape as a parameter:

diagram.showItem("2.1");

Finding Necessary Shape

You can use the API of the Diagram component to find the necessary shape in the diagram. The find method of the data collection will help you to perform this task. The method takes the following parameters:

by - (string|function) the search criterion (either the key of the shape attribute or a function)
match - (string) the value of the shape attribute

and returns the first object of the shape that matches the specified criteria:

// searching for a shape by the attribute key
var shape = diagram.data.find({by:"text",match:"Manager"}); 
// ->{id:"2",text:"Manager",title:"Mildred Kim",img:"../avatar-2.png",type:"card", …}
 
// searching for a shape by the function
var shape = diagram.data.find(function(shape){
    if(shape.text==="Manager"||shape.text==="Marketer"){return true}
});

Related sample: Diagram find

Finding all the shapes that meet the search criteria

You can also find all the shapes that meet the set criteria via the findAll of the data collection method. The method takes the same parameters as the find() method and returns an array of shape objects:

// searching for shapes by the attribute key
var shapes = diagram.data.findAll({by:"text",match:"Manager"});
 
// searching for shapes by the function
var shapes = diagram.data.findAll(function(shapes){
    if(shapes.text==="Manager"||shapes.text==="Marketer"){return true}
});
// ->{id:"2",text:"Manager",title:"Mildred Kim",img:"../avatar-2.png",type:"card", …}
// ->{id:"2.1",text:"Marketer",title:"Charles Little", img: "../avatar-4.png", …}

Filtering Shapes

It is possible to filter the diagram and render only the shapes that meet the filter criteria via the filter method of the data collection. The method takes the parameters listed below:

criteria - (object,function) the filtering criteria (either the key of the shape attribute or a filtering function)
mode - (boolean) optional, true to define that each next filtering will be applied to the already filtered data, not to the initial data

// filtering by the key of the shape attribute
diagram.data.filter({ by: "text", match: "Operation 1" });
 
// filtering by the function
diagram.data.filter(function(shape){
    if(shape.text==="Manager"||shape.text==="Marketer"){return true}
});

The criteria parameter set as object has the following attributes:

by - (string) the key of the shape attribute
match - (string) the value of the shape attribute

The method will show only the filtered shapes, hiding the rest of shapes and connectors.

To revert the diagram to the initial state, call the filter() method without parameters.

diagram.data.filter();

Related sample: Diagram filter