Diagram Data Binding
The Kendo UI for Angular Diagram supports comprehensive data binding capabilities that allow you to create dynamic diagrams from your data models. This article demonstrates how to bind shapes and connections to data sources for creating organizational charts, process flows, network diagrams, and other data-driven visualizations.
The Diagram component binds data to shapes and connections by mapping data properties to the expected Diagram format. By default, the component expects the following data structures:
- Shapes—Objects implementing the
ShapeOptionsinterface with properties likeid,content,x,y,width, andheight. - Connections—Objects implementing the
ConnectionOptionsinterface withfromandtoproperties.
The following example demonstrates basic data binding with shapes and connections representing a manufacturing process workflow.
When your data uses different property names, use field mapping to connect your data structure to the Diagram format. For more complex scenarios with nested structures, use the convertToDiagramModel utility function.
Field Mapping
Use the ShapeModelFields and ConnectionModelFields properties to map your data properties to the expected Diagram properties. This approach works with any data model, including those from existing APIs or backend systems.
The following example demonstrates a supply chain logistics workflow using field mappings to bind data with custom property names to the Diagram.
To implement field mapping in your application, define ShapeModelFields and ConnectionModelFields objects that map your property names to the Diagram's expected properties.
// Your existing data structure
public processSteps = [
{
stepId: 'receiving',
stepName: { text: 'Receiving Inspection' },
location: { posX: 100, posY: 50 },
dimensions: { w: 120, h: 60 }
}
];
// Map your data properties to Diagram properties using dot notation for nested properties
public shapeModelFields: ShapeModelFields = {
id: 'stepId',
content: 'stepName',
x: 'location.posX',
y: 'location.posY',
width: 'dimensions.w',
height: 'dimensions.h'
};
// Your connection data structure
public workflowConnections = [
{ sourceStep: 'receiving', targetStep: 'assembly', flowType: 'direct' }
];
// Map connection properties
public connectionModelFields: ConnectionModelFields = {
from: 'sourceStep',
to: 'targetStep'
};Converting Complex Data Structures
When working with complex nested data structures or APIs that return data in formats not directly compatible with the Diagram component, use the convertToDiagramModel utility function to transform your data. This function provides a programmatic way to extract and map data from custom structures into the format expected by the Diagram.
The following example demonstrates converting a complex API response structure representing an organizational hierarchy into diagram format using convertToDiagramModel.
The convertToDiagramModel function accepts two parameters:
- input—The raw data object containing your shapes and connections data.
- mapping—A
DiagramMappingconfiguration that defines how to extract and transform the data.
import { convertToDiagramModel, DiagramMapping } from '@progress/kendo-angular-diagrams';
// Complex nested data structure from an API
const apiResponse = {
organizationData: {
departments: [
{ deptId: 'eng', deptName: 'Engineering', location: { x: 100, y: 50 } },
{ deptId: 'sales', deptName: 'Sales', location: { x: 300, y: 50 } }
],
reporting: [
{ supervisor: 'eng', subordinate: 'sales' }
]
}
};
// Define mapping configuration
const mapping: DiagramMapping = {
shapes: {
source: 'organizationData.departments',
map: {
id: 'deptId',
content: (dept) => ({ text: dept.deptName }),
x: 'location.x',
y: 'location.y'
}
},
connections: {
source: 'organizationData.reporting',
map: {
from: 'supervisor',
to: 'subordinate'
}
}
};
// Convert the data
const result = convertToDiagramModel(apiResponse, mapping);
// Use the converted data with the Diagram
this.shapes = result.shapes;
this.connections = result.connections;The mapping configuration supports:
- Dot notation for accessing nested properties (for example,
location.x). - Function transformers for complex property transformations (for example,
(item) => ({ text: item.name })). - Source paths to specify where in the input object to find the data arrays.
This approach is useful when integrating with backend systems that provide data in specific formats, or when you need to perform data transformations before binding to the Diagram component.
Dynamic Data Updates
The Diagram automatically reflects changes when you modify the bound data arrays. Add new items to your shapes or connections arrays to dynamically insert nodes and links, or remove items to update the diagram structure in real-time. When managing data updates, ensure you maintain referential integrity by updating related connections whenever shapes are added or removed.
The following example demonstrates dynamic data updates where you can add and remove process steps interactively.
Remote Data Binding
Use observables to load diagram data asynchronously from remote services or APIs. This approach is useful when working with backend systems or when data needs to be fetched dynamically.
The following example demonstrates remote data binding for a financial approval workflow that loads data asynchronously from a simulated service.