Supported mutation operations

As Changing data from a plug-in describes, the i2 Notebook Web API provides the ability to write data to the chart and to change the state of the i2 Notebook application.

The types of changes that you can make through the API are:

• Record creation
• Record editing
• Record removal
• Selection changes
• Node position changes
• Node and edge style changes
• View changes

A single mutation can contain any number of these changes, in any combination. The changes are typically applied when the mutation itself is committed.

The i2 Notebook SDK includes a mutations tutorial that demonstrates how to make some of these changes.

Creating and editing records

The mutation handler that you pass to IApplication.runTrackedMutations() can create entity and link records through the addEntityRecord() and addLinkRecord() methods of the ITrackedMutations object that it receives. To each method, you provide the features of the new record including its item type, its notes, its security settings, and values for its properties.

Both add methods return a "pending" record object that represents the new record in the mutation, before it is added to the chart. This object implements the IRecordEditor interface, which allows you to make further edits before you commit.

To make changes to a record that is already on the chart, you can use the ITrackedMutations.editRecord() method, which also returns an object that implements IRecordEditor.

Note: New records, and changes to existing records, do not exist on the chart (and will not be seen in IChart collections) until you commit the mutation. Pending records and record editors are only valid in the mutation handler where they were created.

Value factories

When you create or edit a record from a mutation handler, you can provide values for its properties. Some of these values - temporal and geospatial ones, for example - have reasonably complex structures. To help you construct valid values, ITrackedMutations.valueFactory provides an IValueFactory object that contains helper methods for creating objects of the following types:

• IGeopoint
• IDecimal
• ILocalDate
• ILocalDateTime
• ILocalTime
• ISecuritySettings
• IZonedDateTime

Removing records and elements

Just as a mutation handler can create and edit records, it can also remove them from the chart, through the ITrackedMutations.removeRecords() method.

You can also remove visual nodes and edges from the chart by calling the ITrackedMutations.removeElements() method. Doing so implicitly removes any records that an element contains, while removing a node also removes any connected edges.

Changing selection

You can change the selection state of the chart through tracked and untracked mutation handlers. ITrackedMutations and IUntrackedMutations both inherit IMutationsBase.selection, which provides an implementation of the ISelectionEditor interface.

Note: Selection changes in untracked mutations are not explicitly added to the undo stack, but the next tracked mutation can capture the current selection as part of its undoable state.

Moving nodes on the chart

From a tracked mutation handler, you can arrange the nodes on the chart by changing their positions one-by-one, or as a group:

• Set the position of a single node directly by using the ITrackedMutations.setNodeCenter() method.

• Move a selection that includes nodes by an offset through the ITrackedMutations.moveSelectedNodesRelative() method.

Changing the style of nodes and edges on the chart

You can change the visual appearance of node and edges displayed on a chart by using the ITrackedMutations.editNode() and ITrackedMutations.editEdge() methods.

• Change the size of a node by calling INodeEditor.setSize()

• Change the colors of edges and nodes by calling INodeEditor.setColor() or IEdgeEditor.setColor().

Changing the view

Finally, you can use tracked or untracked mutations to change the current view of the chart by moving its center point or changing the zoom level.

ITrackedMutations and IUntrackedMutations both inherit IMutationsBase.view, which provides an implementation of the IViewEditor interface.

Validation

The parameters of all calls to mutation methods are validated to ensure that the correct value types are passed, and that any record and type identifiers are associated with existing objects.

A validation failure results in an error notification in the i2 Notebook user interface that provides information about which argument was incorrect.