C

GraphBuilder

Show Usages
Populates a graph from custom data.
Inheritance Hierarchy

Remarks

This class can be used when the data consists of one or more collections of nodes, edges, and optionally, groups. The methods createNodesSource, createGroupNodesSource, and createEdgesSource bind the data to source objects from which nodes, groups, and edges will be created.

Generally, using the GraphBuilder class consists of a few basic steps:

  1. Create a GraphBuilder and optionally, provide an IGraph on which it should operate.
    const graphBuilder = new GraphBuilder(graph)
  2. Create one or more sources from which the GraphBuilder should create the graph structure (createNodesSource, createGroupNodesSource, createEdgesSource).

    To create edges from the data, provide sourceIdProvider and targetIdProvider with createEdgesSource and a respective idProvider for the NodesSource<TDataItem> to tell the GraphBuilder how the data is structured.

    const nodesData = getNodesData()
const nodesSource = graphBuilder.createNodesSource(
  nodesData, // nodes data
  (nodeDataItem) => nodeDataItem.nodeId, // node id provider
)
const edgesData = getEdgesData()
const edgesSource = graphBuilder.createEdgesSource(
  edgesData,
  (edgeDataItem) => edgeDataItem.sourceNodeId,
  (edgeDataItem) => edgeDataItem.targetNodeId,
)
  3. Each NodesSource<TDataItem> provides a NodeCreator<TDataItem> that allows for further specification of how the items from this source should be created. You can provide defaults for the default styling but also bind more specific styling based on the actual data item with the styleProvider and styleBindings.
    nodesSource.nodeCreator.defaults.shareStyleInstance = false
nodesSource.nodeCreator.defaults.style = new ShapeNodeStyle({
  stroke: 'darkOrange',
  fill: 'lightYellow',
  shape: 'round-rectangle',
})
nodesSource.nodeCreator.styleBindings.addBinding(
  'stroke',
  (employee) =>
    employee.position.includes('Chief') ? 'darkRed' : 'darkOrange',
)
nodesSource.nodeCreator.styleBindings.addBinding('shape', (employee) =>
  employee.freelancer ? 'hexagon' : 'roundRectangle',
)

    It also allows for applying layout information from the data item ( layoutProvider), as well as further specification of the created node's tag ( tagProvider).

  4. Similarly, each EdgesSource<TDataItem> provides an EdgeCreator<TDataItem> that allows for specifying the styling of the created items (defaults, styleProvider, and styleBindings).
    edgesSource.edgeCreator.defaults.style = new PolylineEdgeStyle({
  smoothingLength: 20,
})

    Furthermore, it allows for obtaining bend locations from the data item ( bendsProvider), as well as further specification of the created edge's tag ( tagProvider).

    edgesSource.edgeCreator.bendsProvider = (edgeDataItem) =>
  edgeDataItem.bendPoints
  5. Optionally, labels can be added by providing one or multiple label bindings. If there is a varying number of labels per node, createLabelsSource can be used, instead. Similar methods are also available on the EdgeCreator<TDataItem>.

    The LabelsSource<TDataItem> provides a LabelCreator<TDataItem> that allows for adjusting all aspects of the label creation, like style, text, size, and tag.

    const edgeLabelCreator = edgesSource.edgeCreator.createLabelBinding(
  (edgeDataItem) => edgeDataItem.name,
)
edgeLabelCreator.defaults.style = new LabelStyle({
  backgroundFill: 'rgb(225,242,253)',
  backgroundStroke: 'lightskyblue',
  textSize: 8,
})
  6. Call buildGraph to populate the graph. You can apply a layout algorithm afterward to make the graph look nice.
    // Build a graph initially
graphBuilder.buildGraph()
// Apply a layout in a subsequent step
graph.applyLayout(new OrganicLayout())
  7. If your items or collections change later, call updateGraph to make the changes visible in the graph. If the data item instances have changed, you can call setData or setData.
    // Set the new data collections:
graphBuilder.setData(nodesSource, getNodesData())
graphBuilder.setData(edgesSource, getEdgesData())
// Update a graph after the business data has changed
graphBuilder.updateGraph()
// Apply a layout in a subsequent step
graph.applyLayout(new OrganicLayout())

Group nodes can be defined in three ways depending on the data:

  • As a separate list, with each entry in the list defining a group node and an ID. The child nodes belonging to a group node define the ID of their group node as the parent ID.
    graphBuilder.createGroupNodesSource(
  groupNodesData,
  (groupNodeData) => groupNodeData.nodeId,
)

const nodesSource = graphBuilder.createNodesSource(
  nodesData,
  (nodeData) => nodeData.nodeId,
)
nodesSource.parentIdProvider = (nodeData) => nodeData.parentId
  • As a recursive hierarchical structure. That is, a group's data also includes a list of its children's data which is defined as createChildNodesSource. Note that a child can have children on its own.
    const topLevelNodesSource = graphBuilder.createNodesSource(
  topLevelNodesData,
  (data) => data.nodeId,
)
const childNodeSource = topLevelNodesSource.createChildNodesSource(
  (data) => data.children,
)
childNodeSource.addChildNodesSource(
  (child) => child.children,
  childNodeSource,
)
  • As a group node which is implicitly defined on one or more of its children. Parent nodes can be defined as createParentNodesSource.
    const leafNodesSource = graphBuilder.createNodesSource(
  leafNodesData,
  (data) => data.nodeId,
)
const parentSource = leafNodesSource.createParentNodesSource(
  (data) => data.parent,
)

You can further customize how nodes, groups, and edges are created by adding event handlers to the various events and modifying the items there. This can be used to modify items in ways that are not directly supported by the available bindings or defaults. There are creation and update events for all items, which allow for separate customization when nodes, groups, and edges are created or updated. For completely static graphs, where updateGraph is not needed, the update events can be safely ignored.

See Also

The different graph builders are discussed in the section Creating a Graph from Business Data. Class GraphBuilder, in particular, is topic of section GraphBuilder.

Developer's Guide

API

TreeBuilder

Members

Show:

Constructors

GraphBuilder

(graph?: IGraph)
Initializes a new instance of the GraphBuilder class that operates on the given graph.
The graph will not be cleared when buildGraph is called. To clear the graph beforehand, call clear.

Parameters

graph?: IGraph
An IGraph instance on which this builder operates. If omitted, a new Graph will be created.

Properties

graph

: IGraph
readonly
Gets the graph used by this builder.
The style defaults of this graph are considered in the NodeCreator<TDataItem>, EdgeCreator<TDataItem> and LabelCreator<TDataItem> of the sources that are created on this GraphBuilder.
readonlyfinal

See Also

Developer's Guide

Methods

addEdgesSource

<TDataItem> (data: any, edgesSource: EdgesSource<TDataItem>)
Binds a collection of data items to the given edgesSource.
final

Parameters

data: any
The collection of objects that is bound to the source.
edgesSource: EdgesSource<TDataItem>
The source to which the data is bound.

addNodesSource

<TDataItem> (data: any, nodesSource: NodesSource<TDataItem>)
Binds a collection of data items to the given nodesSource.
final

Parameters

data: any
The collection of objects that is bound to the source.
nodesSource: NodesSource<TDataItem>
The source to which the data is bound.

buildGraph

(): IGraph
Populates the graph with items generated from the bound data.
This graph is not cleared before the new items are added. To clear the graph, explicitly call clear beforehand.

Return Value

IGraph
The graph of this builder populated by the defined sources.

See Also

Developer's Guide
API
updateGraph

createEdgesSource

<TDataItem> (
data: any
sourceId: function(TDataItem): any
targetId: function(TDataItem): any
id?: function(TDataItem, any): any
): EdgesSource<TDataItem>
Creates a new EdgesSource<TDataItem> and binds a collection of edge data items to it.
The EdgeCreator<TDataItem> of the returned EdgesSource<TDataItem> can be used to further specify creation properties of these items, e.g. style, tag, etc.
If an optional ID provider is used, the identifiers created by said function have to be unique for the elements in the given data set. Otherwise, the behavior of the buildGraph and the updateGraph methods is undefined.
final

Parameters

data: any
The collection of objects to iterate and create the edges from.
sourceId: function(TDataItem): any
A provider that defines the source of the edge in the graph structure. Must resolve to the specified node id.
targetId: function(TDataItem): any
A provider that defines the target of the edge in the graph structure. Must resolve to the specified node id.
id?: function(TDataItem, any): any
An optional function that yields an id for each element in the data. This id is used to identify the edges during updateGraph.

Return Value

EdgesSource<TDataItem>
A new EdgesSource<TDataItem> instance that can be used to further customize the creation of edges, e.g. provide specific style defaults.

See Also

Developer's Guide

createGroupNodesSource

<TDataItem> (data: any, id: function(TDataItem, any): any): NodesSource<TDataItem>
Creates a new NodesSource<TDataItem> and binds a collection of group node data items to it.

The NodeCreator<TDataItem> of the returned NodesSource<TDataItem> can be used to further specify creation properties of these items, e.g. style, layout, etc.

Data items of this collection are created as group nodes in the graph.

If an optional ID provider is used, the identifiers created by said function have to be unique for the elements in the given data set. Otherwise, the behavior of the buildGraph and the updateGraph methods is undefined.
final

Parameters

data: any
The collection of objects to iterate and create the group nodes from.
id: function(TDataItem, any): any
A function that yields an ID for each element in the data. If the data has no associated IDs, null may be used as well in which case the builder uses the objects themselves as identifiers internally.

This ID is used by parentIdProvider and sourceIdProvider and targetIdProvider to resolve the parent, source, or target nodes. The ID is also used to identify nodes during updateGraph.

Return Value

NodesSource<TDataItem>
A new NodesSource<TDataItem> instance that can be used to further customize the creation of nodes, e.g. provide specific style defaults.

See Also

Developer's Guide

createNodesSource

<TDataItem> (data: any, id: function(TDataItem, any): any): NodesSource<TDataItem>
Creates a new NodesSource<TDataItem> and binds a collection of node data items to it.
The NodeCreator<TDataItem> of the returned NodesSource<TDataItem> can be used to further specify creation properties of these items, e.g. style, layout, etc.
If an optional ID provider is used, the identifiers created by said function have to be unique for the elements in the given data set. Otherwise, the behavior of the buildGraph and the updateGraph methods is undefined.
final

Parameters

data: any
The collection of objects to iterate and create the nodes from.
id: function(TDataItem, any): any
A function that yields an ID for each element in the data. If the data has no associated IDs, null may be used as well in which case the builder uses the objects themselves as identifiers internally.

This ID is used by parentIdProvider and sourceIdProvider and targetIdProvider to resolve the parent, source, or target nodes. The ID is also used to identify nodes during updateGraph.

Return Value

NodesSource<TDataItem>
A new NodesSource<TDataItem> instance that can be used to further customize the creation of nodes, e.g. provide specific style defaults.

See Also

Developer's Guide

getDataItem

(node: INode): any
Returns the data item the given node was created for.
The returned data item was processed by one of the added NodesSource<TDataItem>.

Parameters

node: INode
The node that was created for the data item.

Return Value

any
The data item the given node was created for.

getDataItem

(edge: IEdge): any
Returns the data item the given edge was created for.
The returned data item was processed by one of the added NodesSource<TDataItem>.

Parameters

edge: IEdge
The edge that was created for the data item.

Return Value

any
The data item the given edge was created for.

getEdgeById

<TId> (id: TId): IEdge
Returns the IEdge that was created for a data item with the given id.
The id for the data item was provided by the idProvider of one of the added NodesSource<TDataItem>.

Parameters

id: TId
The id the edge was created for.

Return Value

IEdge
The IEdge that was created for a data item with the given id.

getEdgeForItem

<TDataItem> (item: TDataItem): IEdge
Returns the IEdge that was created for the given item.
The data item was processed by one of the added NodesSource<TDataItem>.

Parameters

item: TDataItem
The data item the edge was created for.

Return Value

IEdge
The IEdge that was created for the given item.

getNodeById

<TId> (id: TId): INode
Returns the INode that was created for a data item with the given id.
The id for the data item was provided by the idProvider of one of the added NodesSource<TDataItem>.

Parameters

id: TId
The id the node was created for.

Return Value

INode
The INode that was created for a data item with the given id.

getNodeForItem

<TDataItem> (item: TDataItem): INode
Returns the INode that was created for the given item.
The data item was processed by one of the added NodesSource<TDataItem>.

Parameters

item: TDataItem
The data item the node was created for.

Return Value

INode
The INode that was created for the given item.

onEdgeCreated

(edge: IEdge, dataItem: any)
protected
Triggers the edge-created event.
protected

Parameters

edge: IEdge
The edge that has been created.
dataItem: any
The data item from which the edge has been created.

onEdgeRemoved

(edge: IEdge, dataItem: any)
protected
Triggers the edge-removed event.
protected

Parameters

edge: IEdge
The edge that has been removed.
dataItem: any
The corresponding data item of the removed edge.

onEdgeUpdated

(edge: IEdge, dataItem: any)
protected
Triggers the edge-updated event.
protected

Parameters

edge: IEdge
The edge that has been updated.
dataItem: any
The data item with which the edge has been updated.

onLabelAdded

(label: ILabel, dataItem: any)
protected
Triggers the label-added event.
protected

Parameters

label: ILabel
The label that has been added.
dataItem: any
The data item from which the label has been created.

onLabelRemoved

(label: ILabel, dataItem: any)
protected
Triggers the label-removed event.
protected

Parameters

label: ILabel
The label that has been removed.
dataItem: any
The corresponding data item of the removed label.

onLabelUpdated

(label: ILabel, dataItem: any)
protected
Triggers the label-updated event.
protected

Parameters

label: ILabel
The label that has been updated.
dataItem: any
The data item with which the label has been updated.

onNodeCreated

(node: INode, dataItem: any)
protected
Triggers the node-created event.
protected

Parameters

node: INode
The node that has been created.
dataItem: any
The data item from which the node has been created.

onNodeRemoved

(node: INode, dataItem: any)
protected
Triggers the node-removed event.
protected

Parameters

node: INode
The node that has been removed.
dataItem: any
The corresponding data item of the removed node.

onNodeUpdated

(node: INode, dataItem: any)
protected
Triggers the node-updated event.
protected

Parameters

node: INode
The node that has been updated.
dataItem: any
The data item with which the node has been updated.

setData

<TDataItem> (nodesSource: NodesSource<TDataItem>, data: any)
Binds a new data collection to a NodesSource<TDataItem>, replacing the old one.
This can be used to assign an entirely different collection instance to an existing nodesSource, such that updateGraph considers the new collection.
final

Parameters

nodesSource: NodesSource<TDataItem>
The source whose data source should be reassigned.
data: any
The collection of objects that is specified for the given source.

setData

<TDataItem> (edgesSource: EdgesSource<TDataItem>, data: any)
Binds a new data collection to a EdgesSource<TDataItem>, replacing the old one.
This can be used to assign an entirely different collection instance to an existing edgesSource, such that updateGraph considers the new collection.
final

Parameters

edgesSource: EdgesSource<TDataItem>
The source whose data source should be reassigned.
data: any
The collection of objects that is specified for the given source.

See Also

Developer's Guide

updateGraph

()
Updates the graph after changes in the bound data.
Graph elements corresponding to objects that are still present in the source collections are kept, new graph elements are created for new objects in the collections, and obsolete ones are removed.
updateGraph merely updates the graph structure. Any other bound data must be updated explicitly if necessary. Calling the respective update methods on the creators (e.g. updateStyle), resolves the provider (e.g. styleProvider) and applies the bindings (e.g. applyStyleBindings). The latter can also be applied solely.

For example, to update any aspect of node creation:
// configure the NodeCreator to update non-structural aspects
nodesSource.nodeCreator.addEventListener('node-updated', (evt) => {
  nodesSource.nodeCreator.updateLayout(evt.graph, evt.item, evt.dataItem)
  nodesSource.nodeCreator.updateStyle(evt.graph, evt.item, evt.dataItem)
  nodesSource.nodeCreator.updateTag(evt.graph, evt.item, evt.dataItem)
  nodesSource.nodeCreator.updateLabels(evt.graph, evt.item, evt.dataItem)
})

builder.updateGraph()

See Also

Developer's Guide

Events

'edge-created'

: GraphBuilderItemEventArgs<IEdge, any>
Occurs when an edge has been created by any one of the edges sources.

This event can be used to further customize the created node.

New edges are created either in response to calling buildGraph, or in response to calling updateGraph when there are new items in the edges sources.

Properties of

GraphBuilderItemEventArgs<IEdge, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
edge-updated, edge-removed

'edge-removed'

: GraphBuilderItemEventArgs<IEdge, any>
Occurs when an edge has been removed.

This event can be used to further customize the created node.

Edges are removed in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<IEdge, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
edge-updated, node-removed

'edge-updated'

: GraphBuilderItemEventArgs<IEdge, any>
Occurs when an edge has been updated.

This event can be used to further customize the created node.

Edges are updated in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<IEdge, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
edge-created, node-removed

'label-added'

: GraphBuilderItemEventArgs<ILabel, any>
Occurs when a label has been added to a node or edge.

This event can be used to further customize the created label.

New labels are added in response to calling buildGraph, or in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<ILabel, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
label-updated, label-removed

'label-removed'

: GraphBuilderItemEventArgs<ILabel, any>
Occurs when a node or edge label has been removed.

This event can be used to further customize the created label.

Labels are removed in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<ILabel, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
label-added, label-updated

'label-updated'

: GraphBuilderItemEventArgs<ILabel, any>
Occurs when a node or edge label has been updated.

This event can be used to further customize the created label.

Labels are updated in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<ILabel, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
label-added, label-removed

'node-created'

: GraphBuilderItemEventArgs<INode, any>
Occurs when a node has been created by any one of the nodes sources.

This event can be used to further customize the created node.

New nodes are created either in response to calling buildGraph, or in response to calling updateGraph when there are new items in the nodes sources.

Properties of

GraphBuilderItemEventArgs<INode, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
node-updated, node-removed

'node-removed'

: GraphBuilderItemEventArgs<INode, any>
Occurs when a node has been removed from any one of the nodes sources.

This event can be used to further customize the created node.

Nodes are removed in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<INode, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
node-created, node-removed

'node-updated'

: GraphBuilderItemEventArgs<INode, any>
Occurs when a node has been updated.

This event can be used to further customize the created node.

Nodes are updated in response to calling updateGraph.

Properties of

GraphBuilderItemEventArgs<INode, any>
dataItem: TDataItem
Gets the object the item has been created from.
graph: IGraph
Gets the graph that can be used to modify the item.
item: TItem
Gets the item that is the subject of the event.

See Also

API
node-created, node-removed