GoJS® GraphLinksModel Class

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 have the model maintain string or number identifiers on the link data just as all models do for node data. To get that behavior, so that you can call findLinkDataForKey, you need to set linkKeyProperty to be a non-empty string. Just as with the assignment of node keys, you can customize the assignment of link keys by setting makeUniqueLinkKeyFunction to a function that returns a unique identifier.

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

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... Parameters: {Array.

Properties Summary Details

Name, Value Type	Description
archetypeNodeData {Object} 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.
copyLinkDataFunction {function(Object, GraphLinksModel):Object \| null}	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.
linkCategoryProperty {string\|function(Object,string=):string}	Gets or sets the name of the data property that returns a string naming that data's category, The value may also be a function taking two arguments, where the first argument will be a link data object.More... If the second argument is not supplied, the function should return the category name; if the second argument is supplied, the function should modify the link data object so that it has that new category name. The default value is the name 'category', meaning that it expects the data to have a property named 'category' if it cares to name the category for the Link. 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: getCategoryForLinkData setCategoryForLinkData
linkDataArray {Array.	Gets or sets the array of link data objects that correspond to Links in the Diagram.More... The initial value is an empty Array.
linkFromKeyProperty {string\|function(Object,(string\|number)=):(string\|number)}	Gets or sets the name of the data property that returns the key of the node data that the link data is coming from.More... The value may also be a function taking two arguments, where the first argument will be a link data object. If the second argument is not supplied, the function should return the key of the link's source node; if the second argument is supplied, the function should modify the link data object so that it has that new key (which may be undefined to refer to no node) as the identifier to the "from" node. The default value is the name 'from', meaning that it expects the data to have a property named 'from' to refer to the link's source node. The name must not be null. If the value is an empty string, getFromKeyForLinkData will return undefined for all link data objects. See also: getFromKeyForLinkData setFromKeyForLinkData
linkFromPortIdProperty {string\|function(Object,string=):string}	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.More... The value may also be a function taking two arguments, where the first argument will be a link data object. If the second argument is not supplied, the function should return the string identifier of the link's source port; if the second argument is supplied, the function should modify the link data object so that it has that string as the identifier to the "from" port. 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 nor the value of linkFromKeyProperty or linkToKeyProperty. If the value is an empty string, getFromPortIdForLinkData will return an empty string for all link data objects. See also: getFromPortIdForLinkData setFromPortIdForLinkData
linkKeyProperty {string\|function(Object,(string\|number)=):(string\|number)} 1.6	Gets or sets the name of the data property that returns a unique id number or string for each link data object.More... The value may also be a function taking two arguments, where the first argument will be a link data object. If the second argument is not supplied, the function should return the unique string or number key for that link data object; if the second argument is supplied, the function should modify the link data object so that it has that string or number as the unique key for that link. The default value is the empty string, which means the model will not maintain a key property value on link data objects. The name must not be null. When this property has a value of an empty string (the default value), getKeyForLinkData will return undefined, and findLinkDataForKey will always return null. See also: #getKeyForlinkData
linkLabelKeysProperty {string\|function(Object,Array.<(string\|number)>=):Array.<(string\|number)>}	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.More... The value may also be a function taking two arguments, where the first argument will be a link data object. If the second argument is not supplied, the function should return the array or label node keys for the link; if the second argument is supplied, the function should modify the link data object so that it holds that Array of node keys as references to label nodes. The default value is the empty string: '', meaning that the model does not support links owning label nodes. 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: getLabelKeysForLinkData setLabelKeysForLinkData
linkToKeyProperty {string\|function(Object,(string\|number)=):(string\|number)}	Gets or sets the name of the data property that returns the key of the node data that the link data is going to, The value may also be a function taking two arguments, where the first argument will be a link data object.More... If the second argument is not supplied, the function should return the key of the link's destination node; if the second argument is supplied, the function should modify the link data object so that it has that new key (which may be undefined to refer to no node) as the identifier to the "to" node. The default value is the name 'to', meaning that it expects the data to have a property named 'to' to refer to the link's destination node. The name must not be null. If the value is an empty string, getToKeyForLinkData will return undefined for all link data objects. See also: getToKeyForLinkData setToKeyForLinkData
linkToPortIdProperty {string\|function(Object,string=):string}	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.More... The value may also be a function taking two arguments, where the first argument will be a link data object. If the second argument is not supplied, the function should return the string identifier of the link's destination port; if the second argument is supplied, the function should modify the link data object so that it has that string as the identifier to the "to" port. 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 nor the value of linkFromKeyProperty or linkToKeyProperty. If the value is an empty string, getToPortIdForLinkData will return an empty string for all link data objects. See also: getToPortIdForLinkData setToPortIdForLinkData
makeUniqueLinkKeyFunction {function(GraphLinksModel, Object):(string\|number) \| null} 1.6	Gets or sets a function that returns a unique id number or string for a link data object.More... This function is called by makeLinkDataKeyUnique when a link data object is added to the model, either as part of a new linkDataArray or by a call to addLinkData, to make sure the value of getKeyForLinkData is unique within the model. However it will not be called when linkKeyProperty is the default value, an empty string. The value may be null in order to cause makeLinkDataKeyUnique behave in the standard manner. (The default value is null.) You may want to supply a function here in order to make sure all of the automatically generated keys are in a particular format. Setting this property after setting linkDataArray has no real effect until there is a call to addLinkData. If a link data object is already in the model and you want to change its key value, call setKeyForLinkData with a new and unique key.
nodeGroupKeyProperty {string\|function(Object,(string\|number)=):(string\|number)}	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.More... The value may also be a function taking two arguments, where the first argument will be a node data object. If the second argument is not supplied, the function should return the string or number key for the group data object of which the given data object is a member; if the second argument is supplied, the function should modify the node data object so that it has that new key (which may be undefined to refer to no node) as the containing group key for that node. The default value is the name 'group', meaning that it expects the data to have a property named 'group' to refer to any containing 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: getGroupKeyForNodeData setGroupKeyForNodeData
nodeIsGroupProperty {string\|function(Object,boolean=):boolean}	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.More... The value may also be a function taking two arguments, where the first argument will be a node data object. If the second argument is not supplied, the function should return true if the node data object should be represented by a Group and false otherwise. At the current time the function will not be called to change whether the node is a group or not. The default value is the name 'isGroup', meaning that it expects the data to have a property named 'isGroup' on those node data objects that should be represented by Groups. 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

Name, Return Type	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: removeLabelKeyForLinkData setLabelKeysForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string\|number} key a number or string that is the key of the new label node.
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: removeLinkData Parameters: {Object} linkdata a JavaScript object represented by a link.
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... Parameters: {Iterable.
containsLinkData(linkdata) {boolean}	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: addLinkData removeLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {boolean}
copyLinkData(linkdata) {Object}	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: addLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {Object}
copyNodeData(nodedata) {Object}	This override also makes sure any copied node data does not have a reference to the containing group.More... See also: Model.copyNodeData Parameters: {Object} nodedata a JavaScript object represented by a node, group, or non-link. Returns: {Object}
findLinkDataForKey(key) {Object} 1.6	Given a number or string, find the link data object in this model that uses the given value as its unique key.More... Unless linkKeyProperty is set to a non-empty string, this model will not automatically assign unique key values for link data objects, and thus this method will always return null. See also: containsLinkData getKeyForLinkData Parameters: {(string\|number\|undefined)} key a string or a number. Returns: {Object} null if the key is not present in the model, or if the key is null or undefined or not a string or number.
getCategoryForLinkData(linkdata) {string}	Find the category of a given link data, a string naming the link template that the Diagram should use to represent the link data.More... See also: linkCategoryProperty setCategoryForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {string}
getFromKeyForLinkData(linkdata) {string\|number\|undefined}	From a link data retrieve a value uniquely identifying the node data from which this link is connected.More... See also: linkFromKeyProperty setFromKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {string\|number\|undefined} This may return undefined if the link is not coming from any node.
getFromPortIdForLinkData(linkdata) {string}	From a link data retrieve a value identifying the port object of the node from which this link is connected.More... See also: linkFromPortIdProperty setFromPortIdForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {string} This may return the empty string if there is no particular port parameter information.
getGroupKeyForNodeData(nodedata) {string\|number\|undefined}	If there is a container group for the given node data, return the group's key.More... See also: nodeGroupKeyProperty setGroupKeyForNodeData Parameters: {Object} nodedata a JavaScript object represented by a node, group, or non-link. Returns: {string\|number\|undefined} This returns undefined if there is no containing group data.
getKeyForLinkData(linkdata) {string\|number\|undefined} 1.6	Given a link data object return its unique key: a number or a string.More... This returns undefined if there is no key value. Unless linkKeyProperty is set to a non-empty string, this model will not automatically assign unique key values for link data objects. It is possible to change the key for a link data object by calling setKeyForLinkData. See also: linkKeyProperty setKeyForLinkData findLinkDataForKey Parameters: {Object} linkdata a JavaScript object represented by a link Returns: {string\|number\|undefined}
getLabelKeysForLinkData(linkdata) {Array.<(string\|number)>}	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: linkLabelKeysProperty setLabelKeysForLinkData addLabelKeyForLinkData removeLabelKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {Array.<(string\|number)>} an Array of node keys; an empty Array if the property was not present.
getToKeyForLinkData(linkdata) {string\|number\|undefined}	From a link data retrieve a value uniquely identifying the node data to which this link is connected.More... See also: linkToKeyProperty setToKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {string\|number\|undefined} This may return undefined if the link is not going to any node.
getToPortIdForLinkData(linkdata) {string}	From a link data retrieve a value identifying the port object of the node to which this link is connected.More... See also: linkToPortIdProperty setToPortIdForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. Returns: {string} This may return the empty string if there is no particular port parameter information.
isGroupForNodeData(nodedata) {boolean}	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 `setIsGroupForNodeData` method. See also: nodeIsGroupProperty Parameters: {Object} nodedata a JavaScript object represented by a node, group, or non-link. Returns: {boolean}
makeLinkDataKeyUnique(linkdata) 1.6	This method is called when a link data object is added to the model to make sure that getKeyForLinkData returns a unique key value.More... The key value should be unique within the set of data managed by this model: linkDataArray. If the key is already in use, this will assign an unused number to the linkKeyProperty property on the data. If you want to customize the way in which link data gets a unique key, you can set the makeUniqueKeyFunction functional property. If the link data object is already in the model and you want to change its key value, call setKeyForLinkData and give it a new unique key value. Parameters: {Object} linkdata a JavaScript object represented by a link
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: addLabelKeyForLinkData setLabelKeysForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string\|number} key a number or string that is the key of the label node being removed from the link.
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: addLinkData Parameters: {Object} linkdata a JavaScript object represented by a link.
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... Parameters: {Iterable.
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. Note that the new template must be an instance of the same class as the original link. Thus one cannot change the category of a link from an instance of Link to an instance of a subclass of Link, nor vice-versa. See also: linkCategoryProperty getCategoryForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string} cat Must not be null.
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: Model.setDataProperty Parameters: {Object} data a JavaScript object typically the value of a Panel.data and represented by a Node, Link, Group, simple Part, or item in a Panel.itemArray; or this model's modelData. {string} propname a string that is not null or the empty string. {} val* the new value for the property.
setFromKeyForLinkData(linkdata, key)	Change the node key that the given link data references as the source of the link.More... See also: linkFromKeyProperty getFromKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string\|number\|undefined} key This may be undefined if the link should no longer come from any node.
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: linkFromPortIdProperty getFromPortIdForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string} portname This may be the empty string if the link should no longer be associated with any particular "port".
setGroupKeyForNodeData(nodedata, key)	Change the container group for the given node data, given a key for the new group.More... See also: nodeGroupKeyProperty getGroupKeyForNodeData Parameters: {Object} nodedata a JavaScript object represented by a node, group, or non-link. {string\|number\|undefined} key This may be undefined if there should be no containing group data.
setKeyForLinkData(linkdata, key) 1.6	Change the unique key of a given link data that is already in this model.More... The new key value must be unique -- i.e. not in use by another link data object. You can call findLinkDataForKey to check if a proposed new key is already in use. If this is called when linkKeyProperty is the empty string (i.e. its default value), this method has no effect. If this is called on a link data object that is not (yet) in this model, this unconditionally modifies the property to the new key value. See also: linkKeyProperty getKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link {string\|number} key
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: linkLabelKeysProperty getLabelKeysForLinkData addLabelKeyForLinkData removeLabelKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {Array.<(string\|number)>} arr an Array of node keys; an empty Array if the property was not present.
setToKeyForLinkData(linkdata, key)	Change the node key that the given link data references as the destination of the link.More... See also: linkToKeyProperty getToKeyForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string\|number\|undefined} key This may be undefined if the link should no longer go to any node.
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: linkToPortIdProperty getToPortIdForLinkData Parameters: {Object} linkdata a JavaScript object represented by a link. {string} portname This may be the empty string if the link should no longer be associated with any particular "port".