Class Model

This also calls raiseChangedEvent to notify all listeners about the ChangedEvent.Insert.

If you want to add a new node or part to the diagram, call addNodeData.

This registration does not raise a ChangedEvent. In case a Diagram's Model may be replaced, you may prefer calling Diagram.addModelChangedListener instead of this method.

Event listeners are not written out by toJson.

Do not add or remove Changed listeners during the execution of a Changed listener.

To remove a node from the diagram, you can remove its data object by calling removeNodeData.

To add or remove an object or value from an item array, call insertArrayItem or removeArrayItem.

This requires the "incremental" property to be present and to be a number, as specified by toIncrementalJson. All of the top-level properties in the JSON, such as nodeKeyProperty, must be the same as for this model. Note that if the model is a GraphLinksModel, you will have to have set GraphLinksModel.linkKeyProperty to the name of a property, the same both in the Diagram.model as well as in the data that you pass to this method.

This conducts a transaction.

Instead of calling this method, you may prefer to set nodeDataArray to an empty JavaScript Array. If this model is a GraphLinksModel, you would also want to set GraphLinksModel.linkDataArray to a separate empty JavaScript Array.

If you do not have a reference to the particular data object that is in the nodeDataArray, you may need to search for it by iterating through that Array, or by finding the desired Node or simple Part in a Diagram and getting that node's Panel.data, or most likely by calling findNodeDataForKey.

However when copiesArrays is true, this will make a copy of property values that are JavaScript Arrays. This is useful when you do not want the Arrays to be shared between the node data objects. Note that if you want to copy some property values that are Arrays but not other properties that are Arrays, you cannot use copiesArrays but must implement your own copyNodeDataFunction.

In addition when copiesArrayObjects is true, if items in the Array being copied are JavaScript Objects, those objects are copied, recursively. This is useful when the items in copied Arrays are themselves objects that need to be copied. Note that if you want to share references to some but not all of the objects in copied Arrays you cannot use copiesArrayObjects but must implement your own copyNodeDataFunction.

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.

Models should not have any references to Diagrams or GraphObjects or Tools or Layouts or other objects that form a Diagram.

Warning: there should not be any cyclical references within the model data, unless you either do not turn on copiesArrays or copiesArrayObjects or unless you have supplied your own copyNodeDataFunction that can handle cyclical references.

It is possible to change the key for a node data object by calling setKeyForNodeData.

This also calls raiseChangedEvent to notify all listeners about the ChangedEvent.Insert.

If you want to add a new node or part to the diagram, call addNodeData.

The key value should be unique within the set of data managed by this model: nodeDataArray. If the key is already in use, this will assign an unused number to the nodeKeyProperty property on the data.

If you want to customize the way in which node data gets a unique key, you can set the makeUniqueKeyFunction functional property.

If the node data object is already in the model and you want to change its key value, call setKeyForNodeData and give it a new unique key value.

For node data objects that have the same key value, this makes calls to setDataProperty to update the existing node data object. For new keys, this calls cloneDeep to copy the data and then addNodeData to add a new node to the model. For existing nodes that have keys that are not present in the given Array, this calls removeNodeData to remove the existing node from the model.

This method is typically used when GoJS is being used within an application that is maintaining state related to the diagram model. When state is updated, this method can be called to keep the GoJS model synchronized. Any updates to the data should use new references since this method will use reference equality to check if a node data object needs to be updated.

This method does not conduct a transaction.

You should call this method only if the property value actually changed. This method is called by setDataProperty.

This also calls raiseChangedEvent to notify all listeners about the ChangedEvent.Remove.

If you want to remove a node from the diagram, call removeNodeData.

Note that there is no version of this method that takes an item value instead of an index into the array. Because item arrays may hold any JavaScript value, including numbers and strings, there may be duplicate entries with that value in the array. To avoid ambiguity, removing an item from an array requires an index.

This deregistration does not raise a ChangedEvent. In case a Diagram's Model may be replaced, you may prefer calling Diagram.removeModelChangedListener instead of this method.

If you do not have a reference to the particular data object that is in the nodeDataArray, you may need to search for it by iterating through that Array, or by finding the desired Node or simple Part in a Diagram and getting that node's Panel.data, or most likely by calling findNodeDataForKey.

Removing a node data from a model does not automatically remove any connected link data from the model. Removing a node data that represents a group does not automatically remove any member node data or link data from the model.

To add a node to the diagram, you can add its data object by calling addNodeData.

To add or remove an object or value from an item array, call insertArrayItem or removeArrayItem.

Changing the node template for a node data will cause the existing Node, Group, or Part to be replaced with a new instance of the same class created by copying the new node template and applying any data-bindings. That means that the templates in the Diagram.nodeTemplateMap or Diagram.groupTemplateMap must be instances of the same class -- one cannot convert a Node into a Group or vice-versa by setting the category.

Binding sources should not be (or depend in a conversion function on) the category of the data if you might be modifying the category, because then some bindings might be evaluated before or after the category has been changed.

This gets the old value of the property; if the value is the same as the new value, no side-effects occur. This calls raiseDataChanged to notify about the change.

Note that it is insufficient to modify an item Array (for example by pushing a new item onto the Array) and then calling setDataProperty(data, "items", data.items) because the value of data.items is still the same reference. Instead you will want to call insertArrayItem, addArrayItem, or removeArrayItem.

If you modify the property that is the nodeKeyProperty, this will call setKeyForNodeData.

If you modify the property that is the nodeCategoryProperty or the GraphLinksModel.linkCategoryProperty, this will call setCategoryForNodeData or GraphLinksModel.setCategoryForLinkData. But if the category might change, Binding sources should not be (or depend in a conversion function on) the category of the data, because then some bindings might be evaluated before or after the category has been changed.

This operation will check all data objects in the model and replace all references using the old key value with the new one.

If this is called on a node data object that is not (yet) in this model, this unconditionally modifies the property to the new key value.

Note that these incremental changes include the results of undo and redo operations.

For GraphLinksModels, this method requires that GraphLinksModel.linkKeyProperty is not an empty string.

Any node or link data objects contained in the "modified..." properties will be deep copies of the data in the model. The objects will contain proper copies of certain GoJS classes, and some common built-in objects such as Dates and RegExps. Other classes will just be copied as plain Javascript objects, so it is best to avoid using special classes in one's data.

This method is most commonly used when GoJS must communicate with some external data source and maintain integrity between the two while avoiding serialization/deserialization.

  myDiagram.addModelChangedListener(function(e) {
    if (e.isTransactionFinished) {
      var dataChanges = e.model.toIncrementalData(e);
      ... update React state/save to database ...
    }
  });

Caution: don't call JSON.stringify on the resulting object, because that will not properly handle any instances of JavaScript classes that are referenced by the object's properties. Instead call toIncrementalJson, which will produce a more compact textual serialization.

The "modifiedNodeData" Array holds JavaScript objects. The "insertedNodeKeys" and "removedNodeKeys" Arrays hold keys (numbers or strings) of data, not whole objects, that have been added and/or deleted. The "modelData" property holds the Model.modelData object, if it was modified.

Note that it is entirely plausible for the same object be in or referenced by all three Arrays, because a single Transaction can include adding a node, modifying it, and removing it.

The purpose of this method is to make it easier to send incremental changes to the server/database, instead of sending the whole model. Whereas it has always been easy to perform "batch" updates or "file saves":

  myDiagram.addModelChangedListener(function(e) {
    if (e.isTransactionFinished) {
      var json = e.model.toJson();
      // save the whole model upon each transaction completion or undo/redo
      ... send to server/database ...
    }
  });

You can now easily send "incremental" updates:

  myDiagram.addModelChangedListener(function(e) {
    if (e.isTransactionFinished) {
      var json = e.model.toIncrementalJson(e);
      // record each Transaction as a JSON-format string
      ... send to server/database ...
    }
  });

Note that these incremental changes include the results of undo and redo operations. Also, when you might call applyIncrementalJson, you will need to disable your Changed listener, so that it does not send spurious changes to your database during the process of apply incremental changes from the database.

For GraphLinksModels, this method requires that GraphLinksModel.linkKeyProperty is not an empty string. The incremental JSON for GraphLinksModels will include "modifiedLinkData", "insertedLinkKeys", and "removedLinkKeys" properties that are non-empty Arrays.

The same restrictions on data property names and data property values applies to this method as it does to toJson.

Object properties that are not enumerable or whose names start with "_" are not written out.

Functions are not able to be written in JSON format, so any properties that have function values will not be saved in the JSON string.

There must not be any circular references within the model data. Any sharing of object references will be lost in the written JSON.

Most object classes cannot be serialized into JSON without special knowledge and processing at both ends. The toJson and Model.fromJson methods automatically do such processing for numbers that are NaN and for objects that are of class Point, Size, Rect, Margin, Spot, Brush (but not for brush patterns), and for Geometry. For instances of those classes, special objects are written out with a property named "class" whose value will be one of the special cases that will be substituted by Model.fromJson: "NaN", "Date", "go.EnumValue", "go.Point", "go.Size", "go.Rect", "go.Margin", "go.Spot", "go.Brush", "go.Geometry".

However, we recommend that you use Binding converters (static functions named "parse" and "stringify") to represent Points, Sizes, Rects, Margins, Spots, and Geometries as string values in your data, rather than as Objects. This makes the JSON text smaller and simpler and easier to read.

As a special case when serializing an object, if the property is named "points" and the property value is a List of Points, it will write an Array of numbers.

Note that this is a method on the Model class. It cannot render unmodeled Parts such as the background grid or any Parts that you have added directly to a Diagram.

Typical usage:

var modelAsText = myDiagram.model.toJson();
// now save this text string by sending it to your database

Caution: setting a data property without calling setDataProperty and then calling this updateTargetBindings method will update GraphObjects that are bound to the property, but such data settings will not be recorded in the UndoManager and therefore will not be undone/redone, causing an inconsistency between the GraphObjects and the part data.