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 following example demonstrates basic data binding with shapes and connections representing a manufacturing process workflow.
Binding Shapes and Connections
The Diagram component supports two approaches for data binding: direct property mapping and custom field mapping. You can use either approach independently for shapes and connections based on your data structure.
Direct Property Mapping
Bind data to shapes and connections where your object properties directly match the expected Diagram properties.
// Shapes with direct property mapping
public processSteps = [
{
id: 'receiving',
content: { text: 'Receiving Inspection' },
x: 100,
y: 50,
width: 120,
height: 60,
type: 'Rectangle',
fill: { color: '#0078d4' }
}
];
// Connections with direct property mapping
public connections = [
{ from: 'receiving', to: 'assembly' },
{ from: 'assembly', to: 'quality-check' }
];Custom Field Mapping
Use the ShapeModelFields and ConnectionModelFields properties to map custom data properties to Diagram properties. This approach is useful when working with existing data models that use different property names.
import { ShapeModelFields, ConnectionModelFields } from '@progress/kendo-angular-diagrams';
// Custom shape data structure
public processSteps = [
{
stepId: 'receiving',
stepName: { text: 'Receiving Inspection' },
location: { posX: 100, posY: 50 },
dimensions: { w: 120, h: 60 }
}
];
// Map custom shape 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'
};
// Custom connection data structure
public workflowConnections = [
{ sourceStep: 'receiving', targetStep: 'assembly', flowType: 'direct' }
];
// Map custom connection properties
public connectionModelFields: ConnectionModelFields = {
from: 'sourceStep',
to: 'targetStep'
};The following example demonstrates a supply chain logistics workflow using custom field mappings for both shapes and connections.
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.