Binding Data to Graph Elements

Mapping Data to Graph Elements

yFiles FLEX provides an elegant mechanism to associate custom information with instances of arbitrary type. Most notably, this mechanism can be used to conveniently bind data to graph elements, i.e., model items from an IGraph.

The IMapper interface defines a general means to bind a value V to a given key K. Using INode instances as key K, for example, supplemental data can easily be associated with the nodes of a graph.

Example 9.6. Using IMapper to store and retrieve custom data for nodes

// Store custom data for the nodes of a graph.
function createRectanglesForNodes(graph:IGraph, tag:Object):void {
  // Bind some data to each node in the graph.
  var result:IMapper = new DictionaryMapper();
  for (var it:Iterator = graph.nodes.iterator; it.hasNext(); ) {
    var node:INode = it.next();
    result.mapValue(node, createRectangleForNode(node));
  }
  
  // Retrieve the graph mapper registry.
  var registry:IMapperRegistry = graph.mapperRegistry;
  // Add the mapper.
  registry.addMapper(tag, result);
}

// Later retrieve the data stored for the nodes.
function getRectanglesForNodes(graph:IGraph, tag:Object):void {
  var registry:IMapperRegistry = graph.mapperRegistry;
  var result:IMapper = registry.getMapper(tag);
  if (null != result) {
    for (var it:Iterator = graph.nodes.iterator; it.hasNext(); ) {
      var node:INode = it.next();
      var rect:IRectangle = result.lookupValue(node);
      // ...
    }
  }
}

Interface IMapperRegistry enables registration of IMapper instances with a graph by tag. The registry can be retrieved using the IGraph property mapperRegistry().

See Chapter 5, Communicating with the Server and the section called “Using Simple Data Types” for information on how to add graph model item attributes registered in a mapper registry for GraphML input/output operations.

Adding custom mapper attributes for server roundtripping is also covered in a Knowledge Base article.

User Tags

The ITagOwner interface offers a very convenient way to associate arbitrary data with model items. The default implementations of all model items return an ITagOwner instance when their look-up is queried. The tag property can be used to store a user-defined object, the user tag.

API Excerpt 9.6. Interface ITagOwner

// tag associated with this instance.
function get tag():Object;
function set tag( tag:Object ):void;

The ITagOwner of a model item can be retrieved by querying the item's look-up as shown in Example 9.7, “Retrieving the user tag of a model item”.

Example 9.7. Retrieving the user tag of a model item

// 'item' is an INode, IEdge, ILabel, or IPort.
var tagOwner:ITagOwner = item.lookup(ITagOwner) as ITagOwner;
if (tagOwner != null) {
  var userData:Object = tagOwner.tag;
}

Client-Server Communication and User Tags

(De)serialization

(De)serialization of user tags has to be enabled before reading or writing a graph.

Using a RoundtripHandler, reading and sending user tags can be enabled using the updateOptions and sendOptions as listed in Table 5.1, “Constants to be used with updateOptions and sendOptions”.

Using a GraphMLIOHandler, reading and writing can be enabled by setting the supportUserTags property to true.

API Excerpt 9.7. GraphMLIOHandler properties to support user tags

// Whether to support user tags at ModelItems automatically.
function get supportUserTags():Boolean;
function set supportUserTags( value:Boolean ):void;

Strings will be handled by the serializing/deserializing mechanism automatically. If the user object is not a String, a matching serializer and deserializer has to be registered at the RoundtripHandler / GraphMLIOHandler. the section called “Reading and Writing Custom Styles” describes how to create a custom serializer / deserializer.

Handling User Tags on a Server
  • Java: User tags can be handled on a Java server as described in the section called “Class StyledLayoutGraph”. Support for reading / writing user tags has to be enabled on the GraphRoundtripSupport with setSupportUserTags(true).
  • .NET: yFiles .NET supports user tag handling via the ITagOwner interface using a similar API as yFiles FLEX. Support for reading / writing user tags has to be enabled on the GraphRoundtripSupport by setting the property SupportUserTags to true.

The TemplateStyleDemo demonstrates how to use user tags to hold the user data for a TemplateNodeStyle.