Class GraphLinksModel
Extends Model. GraphLinksModels support links between nodes and grouping nodes and links into subgraphs. GraphLinksModels hold node data and link data in separate arrays. Node data is normally represented in a Diagram by instances of Node, but they could be represented by simple Parts or by Groups. Link data should be represented by instances of Link.
Each link data object is assumed to have two values, one referring to the node that the link is coming from and one that the link is going to. The linkFromKeyProperty property names the property on the link data whose value is the key of the "from" node. The linkToKeyProperty property names the property on the link data whose value is the key of the "to" node. The default values for these properties are "from" and "to" respectively.
For example, one can define a graph consisting of two nodes with one link connecting them:
model.nodeDataArray = [
{ key: "Alpha" },
{ key: "Beta" }
];
model.linkDataArray = [
{ from: "Alpha", to: "Beta" }
];
If you want to have subgraphs in your diagram, where a group node contains some number of nodes and links, you need to declare that some node data actually represent groups, and you need to provide a reference from a member node data to its containing group node data. The nodeIsGroupProperty property names the property on a node data that is true if that node data represents a group. The nodeGroupKeyProperty property names the property on a node data whose value is the key of the containing group's node data. The default values for these properties are "isGroup" and "group" respectively.
For example, one can define a graph consisting of one group containing a subgraph of two nodes connected by a link, with a second link from that group to a third node that is not a member of that group:
model.nodeDataArray = [
{ key: "Group1", isGroup: true},
{ key: "Alpha", group: "Group1" },
{ key: "Beta", group: "Group1" },
{ key: "Gamma" }
];
model.linkDataArray = [
{ from: "Alpha", to: "Beta" },
{ from: "Group1", to: "Gamma" }
];
GraphLinksModels also support distinguishing the "port" element of a node to which a link can connect, at either end of the link. This identification is a string that names the "port" element in the node. However, you need to set the linkFromPortIdProperty and/or linkToPortIdProperty properties before the model is able to get the "port id" information from the link data.
For example, one can define a graph consisting of a "subtraction" node and two inputs and one output. The "subtraction" node has two distinct inputs called "subtrahend" and "minuend"; the output is called "difference".
model.linkFromPortIdProperty = "fromPort"; // necessary to remember portIds
model.linkToPortIdProperty = "toPort";
model.nodeDataArray = [
{ key: 1, constant: 5 }, // a constant input node
{ key: 2, constant: 2 }, // another constant node
{ key: 3, operation: "subtract" },
{ key: 4, value: 3 } // the output node
];
model.linkDataArray = [
{ from: 1, to: 3, toPort: "subtrahend" },
{ from: 2, to: 3, toPort: "minuend" },
{ from: 3, to: 4, fromPort: "difference" }
];
In this case links connected to node 3 (which is the subtraction operation)
are distinguished by port id.
The connections to the other nodes do not have any port identification,
presumably because there is only one port on those nodes, representing the node value.
Note that there is no requirement that the link data objects have any kind of unique identifier, unlike for node data. There is no expectation that there be references to link data in the model, so there is no need for such an identifier. When there are multiple links connecting two ports, the only way to distinguish the links in the model is by reference to the particular link data object. This is why there are two methods on the Diagram class for Nodes, Diagram.findNodeForKey and Diagram.findNodeForData, but there is only the one method for Links, Diagram.findLinkForData.
However you may wish to add your own unique identifiers on the link data. One way to implement this is by setting a property on the link data each time one is added to the model:
model.addChangedListener(function(e) {
if (e.change === go.ChangedEvent.Insert && e.modelChange === "linkDataArray") {
var id = e.model.modelData.linkCounter; // keep the counter on the Model.modelData object
if (typeof id !== 'number') id = 0;
e.model.modelData.linkCounter = id + 1;
e.newValue.id = id; // e.newValue is the link data object that was added
}
});
Note how the counter is kept on the Model.modelData object, so that it can be saved and loaded automatically.
Remember to re-establish the listener on a newly constructed model, including those constructed by Model.fromJson.
This model does not support the modification of whether a node data object is a group.
This model cannot detect the modification of the linkDataArray array or the modification of any link data object. If you want to add or remove link data from the linkDataArray, call the addLinkData or removeLinkData methods. If you want to modify the node a link connects to, call the setFromKeyForLinkData and/or setToKeyForLinkData methods. If you want to change the membership of a node data in a group, call the setGroupKeyForNodeData method.
Constructor Summary Details
| Returns | Name | Description |
|---|---|---|
|
GraphLinksModel(nodedataarray, linkdataarray)
|
This constructs an empty GraphLinksModel unless one provides arguments as the initial data array values
for the Model.nodeDataArray and GraphLinksModel.linkDataArray properties. More...
|
Properties Summary Details
| Returns | Name | Description |
|---|---|---|
{Object}
|
archetypeNodeData
1.1
|
Gets or sets a data object that will be copied and added to the model as a new node data each time there
is a link reference (either the "to" or the "from" of a link data) to a node key that does not yet exist in the model. More...
The default value is null -- node data is not automatically copied and added to the model when there is an unresolved reference in a link data. When adding or modifying a link data if there is a "from" or "to" key value for which Model.findNodeDataForKey returns null, it will call Model.copyNodeData on this property value and Model.addNodeData on the result. |
{function(Object, GraphLinksModel):Object | null}
|
copyLinkDataFunction
|
Gets or sets a function that makes a copy of a link data object. More...
You may need to set this property in order to ensure that a copied Link is bound to data that does not share certain data structures between the original link data and the copied link data. This property value may be null in order to cause copyLinkData to make a shallow copy of a JavaScript Object. The default value is null. |
{string|function(Object,string=):string}
|
linkCategoryProperty
|
Gets or sets the name of the data property that returns a string naming that data's category,
or a function that takes a link data object and returns that category string;
the default value is the name 'category'. More...
This is used by the diagram to distinguish between different kinds of links.
The name must not be null.
If the value is an empty string,
getCategoryForLinkData will return an empty string for all link data objects.
See also:
|
{Array.<Object>}
|
linkDataArray
|
|
{string|function(Object,(string|number)=):(string|number)}
|
linkFromKeyProperty
|
Gets or sets the name of the data property that returns
the key of the node data that the link data is coming from,
or a function that takes a link data object and returns that key;
the default value is the name 'from'. More...
The name must not be null.
If the value is an empty string,
getFromKeyForLinkData will return undefined for all link data objects.
See also:
|
{string|function(Object,string=):string}
|
linkFromPortIdProperty
|
Gets or sets the name of the data property that returns
the optional parameter naming a "port" element on the node that the link data is connected from,
or a function that takes a link data object and returns that string. More...
The default value is the empty string indicating that one cannot distinguish
different logical connection points for any links.
The name must not be null.
If the value is an empty string,
getFromPortIdForLinkData will return an empty string for all link data objects.
See also:
|
{string|function(Object,Array.<(string|number)>=):Array.<(string|number)>}
|
linkLabelKeysProperty
|
Gets or sets the name of the data property that returns
an array of keys of node data that are labels on that link data,
or a function that takes a link data object and returns such an array;
the default value is the empty string: ''. More...
The name must not be null. If the value is an empty string, getLabelKeysForLinkData will return an empty array for all link data objects. You will need to set this property in order to support nodes as link labels. See also: |
{string|function(Object,(string|number)=):(string|number)}
|
linkToKeyProperty
|
Gets or sets the name of the data property that returns
the key of the node data that the link data is going to,
or a function that takes a link data object and returns that key;
the default value is the name 'to'. More...
The name must not be null.
If the value is an empty string,
getToKeyForLinkData will return undefined for all link data objects.
See also:
|
{string|function(Object,string=):string}
|
linkToPortIdProperty
|
Gets or sets the name of the data property that returns
the optional parameter naming a "port" element on the node that the link data is connected to,
or a function that takes a link data object and returns that string. More...
The default value is the empty string indicating that one cannot distinguish
different logical connection points for any links.
The name must not be null.
If the value is an empty string,
getToPortIdForLinkData will return an empty string for all link data objects.
See also:
|
{string|function(Object,(string|number)=):(string|number)}
|
nodeGroupKeyProperty
|
Gets or sets the name of the property on node data that specifies
the string or number key of the group data that "owns" that node data,
or a function that takes a node data object and returns that group key. More...
the default value is the name 'group'.
The value must not be null. If the value is an empty string, getGroupKeyForNodeData will return undefined for all node data objects. See also: |
{string|function(Object):boolean}
|
nodeIsGroupProperty
|
Gets or sets the name of the boolean property on node data that indicates
whether the data should be represented as a group of nodes and links or
as a simple node,
or a function that takes a node data object and returns true or false;
the default value is the name 'isGroup'. More...
The value must not be null. If the value is an empty string, isGroupForNodeData will return false for all node data objects. |
- Properties borrowed from class Model:
- copiesArrayObjects, copiesArrays, copyNodeDataFunction, dataFormat, isReadOnly, makeUniqueKeyFunction, modelData, name, nodeCategoryProperty, nodeDataArray, nodeKeyProperty, skipsUndoManager, undoManager
Method Summary Details
| Returns | Name | Description |
|---|---|---|
|
addLabelKeyForLinkData(linkdata, key)
|
Adds a node key value that identifies a node data acting as a new label node on the given link data. More...
This method only works if linkLabelKeysProperty has been set to something other than an empty string. See also:
|
|
|
addLinkData(linkdata)
|
When you want to add a link to the diagram, call this method with a new data object. More...
This will add that data to the linkDataArray and
notify all listeners that a new link data object has been inserted into the collection.
Presumably the link data object will already have its "from" and "to" node key references set, but it is also possible to set them after the link data is in the model by calling setFromKeyForLinkData and setToKeyForLinkData. This operation does nothing if the link data is already part of this model's linkDataArray. See also:
|
|
|
addLinkDataCollection(coll)
1.3
|
Add to this model all of the link data held in an Array or in an Iterable of link data objects. More...
|
|
{boolean}
|
containsLinkData(linkdata)
|
Decide if a given link data object is in this model, using reference equality. More...
If you do not have a reference to the particular data object that is in the linkDataArray, you may need to search for it by iterating through that Array, or (more likely), by finding the desired Link in a Diagram and getting that link's Panel.data. Note that because link data are not assumed to be have a unique key property they cannot be found using an index that this model would maintain. However you may choose to provide such a property on the link data objects and maintain your own index. See also:
|
{Object}
|
copyLinkData(linkdata)
|
Make a copy of a link data object. More...
This uses the value of copyLinkDataFunction to actually perform the copy,
unless it is null, in which case this method just makes a shallow copy of the JavaScript Object.
This does not modify the model -- the returned data object is not added to this model. This assumes that the data's constructor can be called with no arguments. This also makes sure there is no reference to either the "from" or the "to" node of the original data. See also:
|
{Object}
|
copyNodeData(nodedata)
|
This override also makes sure any copied node data does not have a reference to the containing group. More...
See also:
|
{string}
|
getCategoryForLinkData(linkdata)
|
|
{string|number|undefined}
|
getFromKeyForLinkData(linkdata)
|
From a link data retrieve a value uniquely identifying the node data
from which this link is connected. More...
See also:
|
{string}
|
getFromPortIdForLinkData(linkdata)
|
From a link data retrieve a value identifying the port object of the node
from which this link is connected. More...
See also:
|
{string|number|undefined}
|
getGroupKeyForNodeData(nodedata)
|
If there is a container group for the given node data, return the group's key. More...
See also:
|
{Array}
|
getLabelKeysForLinkData(linkdata)
|
Gets an Array of node key values that identify node data acting as labels on the given link data. More...
This method only works if linkLabelKeysProperty has been set to something other than an empty string. See also:
|
{string|number|undefined}
|
getToKeyForLinkData(linkdata)
|
From a link data retrieve a value uniquely identifying the node data
to which this link is connected. More...
See also:
|
{string}
|
getToPortIdForLinkData(linkdata)
|
From a link data retrieve a value identifying the port object of the node
to which this link is connected. More...
See also:
|
{boolean}
|
isGroupForNodeData(nodedata)
|
See if the given node data should be represented as a group or as a simple node. More...
This value must not change as long as the node data is part of the model.
At the current time there is no
|
|
removeLabelKeyForLinkData(linkdata, key)
|
Removes a node key value that identifies a node data acting as a former label node on the given link data. More...
Removing a reference to a node data from the collection of link label keys does not automatically remove any node data from the model. This method only works if linkLabelKeysProperty has been set to something other than an empty string. See also:
|
|
|
removeLinkData(linkdata)
|
When you want to remove a link from the diagram, call this method with an existing link data object. More...
This will remove that data object from the linkDataArray and
notify all listeners that a link data object has been removed from the collection.
If you do not have a reference to the particular data object that is in the linkDataArray, you may need to search for it by iterating through that Array, or (more likely), by finding the desired Link in a Diagram and getting that link's Panel.data. Removing a link data from a model does not automatically remove any associated label node data from the model. This operation does nothing if the link data is not present in the linkDataArray. See also:
|
|
|
removeLinkDataCollection(coll)
1.3
|
Remove from this model all of the link data held in an Array or in an Iterable of link data objects. More...
|
|
|
setCategoryForLinkData(linkdata, cat)
|
Change the category of a given link data, a string naming the link template
that the Diagram should use to represent the link data. More...
Changing the link template for a link data will cause the existing Link to be removed from the Diagram and be replaced with a new Link created by copying the new link template and applying any data-bindings. See also:
|
|
|
setDataProperty(data, propname, val)
|
This override changes the value of some property of a node data, a link data, or an item data, given a string naming the property
and the new value, in a manner that can be undone/redone and that automatically updates any bindings. More...
This override handles link data as well as node data.
This gets the old value of the property; if the value is the same as the new value, no side-effects occur. See also:
|
|
|
setFromKeyForLinkData(linkdata, key)
|
Change the node key that the given link data references as the
source of the link. More...
See also:
|
|
|
setFromPortIdForLinkData(linkdata, portname)
|
Change the information that the given link data uses to identify the
particular "port" that the link is coming from. More...
See also:
|
|
|
setGroupKeyForNodeData(nodedata, key)
|
Change the container group for the given node data, given a key for the new group. More...
See also:
|
|
|
setLabelKeysForLinkData(linkdata, arr)
|
Replaces an Array of node key values that identify node data acting as labels on the given link data. More...
This method only works if linkLabelKeysProperty has been set to something other than an empty string. See also:
|
|
|
setToKeyForLinkData(linkdata, key)
|
Change the node key that the given link data references as the
destination of the link. More...
See also:
|
|
|
setToPortIdForLinkData(linkdata, portname)
|
Change the information that the given link data uses to identify the
particular "port" that the link is going to. More...
See also:
|
- Methods borrowed from class Model:
- addArrayItem, addChangedListener, addNodeData, addNodeDataCollection, clear, commitTransaction, containsNodeData, findNodeDataForKey, getCategoryForNodeData, getKeyForNodeData, insertArrayItem, makeNodeDataKeyUnique, raiseChangedEvent, raiseDataChanged, removeArrayItem, removeChangedListener, removeNodeData, removeNodeDataCollection, rollbackTransaction, setCategoryForNodeData, setKeyForNodeData, startTransaction, toJson, updateTargetBindings