The yFiles.NET Viewer component 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 generic IMapper<K, V> type defines a general interface to bind instances of value type V to instances of a key type K. Using the model item type INode as the key type K, for example, supplemental data can easily be associated with the nodes of a graph.

// Store custom data for the nodes of a graph.
void CreateRectanglesForNodes(IGraph graph, object tag) {
  // Bind some data to each node in the graph.
  IMapper<INode, IRectangle> result = new DictionaryMapper<INode, IRectangle>();
  foreach (INode node in graph.Nodes) {
    result[node] = CreateRectangleForNode(node);
  }
  
  graph.MapperRegistry.AddMapper<INode, IRectangle>(tag, result);
}

// Later retrieve the data stored for the nodes.
void GetRectanglesForNodes(IGraph graph, object tag) {
  IMapperRegistry registry = graph.MapperRegistry;
  IMapper<INode, IRectangle> result = 
      registry.GetMapper<INode, IRectangle>(tag);
  if (result != null) {
    foreach (INode node in graph.Nodes) {
      IRectangle rect = result[node];
      // ...
    }
  }
}

Interface IMapperRegistry enables registration of IMapper instances with a graph by tag. It is accessible through the MapperRegistry property defined in interface IGraph and can be used to add, remove, and retrieve IMapper instances.

Generic class DataProviderAdapter<K, V> can be used to conveniently encapsulate IMapper instances for use as a data provider with layout algorithms. Writing back the results of a yFiles graph analysis algorithm, for example, to an IMapper instance can be done using the services of class YGraphAdapter as described in the yFiles.NET Developer's Guide (Analysis and Layout Part).

Interface IModelItem, the base type for all model items, inherits from interface ITagOwner, which enables a very convenient way to associate data with model items. Through the Tag property a user-defined object, the so-called user tag, can be stored with a model item and can be easily retrieved later on.

Example 5.6, “Setting and retrieving the user tag of a model item” shows both setting and retrieving the user tag of a model item.

// 'item' is an INode, IEdge, IBend, ILabel, or IPort.

// Setting the user tag.
item.Tag = new MyCustomDataObject(item);
// Retrieving the user tag.
MyCustomDataObject userData = item.Tag as MyCustomDataObject;

How the user tag can be used to associate a business model object to a label, for example, is presented in the Custom Styles tutorial; see especially step 13.