Common Features
This section describes the common features of all data binding classes.
Throughout the graph builder API collections of business data objects are called "data" and single data objects are called "data items".
Binding the Business Data to the Graph Builders
So called source objects bind a collection of data items to the graph builder. There are different factory methods to create source objects, e.g. createNodesSource<TDataItem> and createEdgesSource<TDataItem>. It is possible to create multiple nodes and edges sources, where each source may represent differently structured data collections and data items. This is especially useful when having different types of nodes or when the business data originates from multiple different sources. All sources end up in the same graph and nodes of different sources may be connected by edges.
The data binding module for yFiles for HTML accepts different types of data collections. Data
collections may be JavaScript arrays
, JavaScript objects
,
iterables,
or instances of an EcmaScript 2015 Map
. Since IEnumerable<T> implements the iterable
protocol, all yFiles for HTML collections are accepted, as well.
Each data item may be identified by a unique id. The default
id of a data item depends on the type of the data collection. If the collection is an instance of Map
or a
JavaScript object
the default id is the associated key in the Map or object. Otherwise, the item itself is the
default id.
Each source type has an idProvider property (e.g.
idProvider) that can provide a different id for a data item. The key in a Map
or object
or the index in an array
or iterable
is passed to the idProvider as second canonicalId
parameter.
Configuring the Visual Appearance of Graph Items
Each source object has a creator property, e.g. nodeCreator. While the source objects are responsible for building the graph structure, the creator objects manage the visual appearance of single items.
The appearance of a node is controlled by the NodeCreator<TDataItem>'s defaults and its providers, e.g. layoutProvider. The defaults determine the default properties that are shared among all nodes created by this NodeCreator<TDataItem>. The defaults cascade with the GraphBuilder’s graph meaning that all properties that are not explicitly set on the NodeCreator’s defaults are inherited from the graph’s defaults. The providers allow for binding specific properties of a data item to properties of the node, such as its location or tag.
Similarly to nodes, edges are created by an EdgeCreator<TDataItem>.
Both node and edge creators allow for defining one or multiple labels that depend on the node or edge data items. Label creation is explained in more detail below.
Both the sources and the creators have a generic type that is bound to the data item type. The data items are passed to the various provider functions. The following tables give an overview over the available properties:
Property | Description |
---|---|
Configuring a NodeCreator shows how to configure a NodeCreator<TDataItem> to use a specific node style that is not shared between the created nodes and set several style properties depending on the node data item:
In addition to the properties shared by all creator types, there are further properties available on NodeCreator<TDataItem>, EdgeCreator<TDataItem> and LabelCreator<TDataItem>:
Property | Description |
---|---|
x and y on the layout provided by the defaults or the layout
provider. | |
Property | Description |
---|---|
Property | Description |
---|---|
Note that NodeCreator<TDataItem>, EdgeCreator<TDataItem>, and LabelCreator<TDataItem> can be used independently of any graph builder. This might come in handy if the business data structure does not fit any of the graph builders' requirements.
Adding labels
Labels can be added using the node and edge creators. When the number of labels per node or edge is known beforehand and the labels do not have their own data objects, createLabelBinding will create a LabelCreator<TDataItem> with the node’s or edge’s data item. Otherwise, createLabelsSource<TLabelDataItem> creates a LabelsSource<TDataItem> that allows for creating a dynamic amount of labels per node or edge with their own data objects.
createLabelBinding returns a LabelCreator<TDataItem> whose textProvider is preconfigured with the text provider passed as parameter to createLabelBinding.
The LabelCreator<TDataItem> can be configured further to adjust the styling and position according to the given data item. Note that with createLabelBinding the data item is of the same type as the item of the owning node or edge.
createLabelsSource<TLabelDataItem> returns a LabelsSource<TDataItem> whose labelCreator has to be configured further. Note that the data provider which is passed as parameter is expected to return an enumerable of data items where each item represents one label.
Labels can also be used to provide icons instead of text, using an IconLabelStyle and configuring the LabelCreator<TDataItem> accordingly:
Creating And Updating Graphs
Each graph builder manages an IGraph instance that can be passed as a constructor parameter. If no graph is passed, the graph builder creates a new DefaultGraph. The initial graph creation as well as updating the graph for changed data doesn’t happen automatically, it has to be triggered explicitly:
- buildGraph populates the maintained graph instance with the items generated from the bound data. It does not clear the graph and preserves existing items.
- updateGraph updates the graph. It reflects changes in the bound data by adding new elements and removing obsolete elements. Updated data collections can be set via the various setData<TDataItem> methods. This is only required if the instances of the data collections have changed.
Note that neither method triggers an automatic layout. If required, the layout has to be applied in a subsequent step.
The updateGraph methods per default only perform structural updates on the graph.
In cases where the data for existing nodes might change and require updating e.g. style or labels,
one has to update the graph item explicitly. The NodeCreator<TDataItem> raises an NodeUpdated
event for each node which has been kept in the graph and hence might require updating.
Developers can use the various update
methods provided by NodeCreator<TDataItem> to use the binding
mechanism for node and edge creation for updating various properties on existing nodes.
For edges, EdgeCreator<TDataItem> provides similar methods which can be called upon the
EdgeUpdated event.
Note that it is only necessary to add update methods for properties which might change. Properties which are known not to change or which are not affected by the data do not need to have their update method called.
The same applies for labels: if the text, style, or other properties of an existing label might change,
developers have to add update
methods to eachLabelCreator<TDataItem> instance.
Note that only properties which might change have to be updated.
Grouping
All graph builders fully support the creation of group nodes from data. Group nodes may appear at all places where regular nodes may appear. This especially means that group nodes can be recursively nested and edges may be connected to group nodes.
The isGroupPredicate determines if a node shall be created as group node. On each graph
builder there is a group source factory method, that conveniently creates a source object for only group nodes
(e.g. createGroupNodesSource<TDataItem>). These sources have the isGroupPredicate
set to a function that always returns true
and have defaults that cascade with the
groupNodeDefaults.
A custom isGroupPredicate can be set when the NodesSource<TDataItem> shall create a mix of group and normal nodes. Note however that all nodes share the same defaults of their NodesSource<TDataItem>.
Similar to the IGraph API the relationship between a node and its group is determined by the parentIdProvider property which determines the id of a node’s parent group node.