Associating Data with Graph Elements

It is often necessary to connect graph items with the data model, or business data, they represent. yFiles for HTML provides two options to store data linked with graph items:

The most convenient way to associate business data with a graph element is by using the tag property. This property is common for all model item types. These so-called user tags are described in the general chapter about the graph model.

An alternative way to bind data to model items or even the graph itself is provided by the IMapper<K,V> interface. IMapper<K,V>s are map-like implementations that bind a value of type V to a given key of type K. The key is typically a graph item, such as a node. IMapper<K,V>s are used to provide additional information for layout algorithms, see section Layout Data. They can also be used to store additional data that is not part of the actual business data.

The serialization and deserialization of IMapper<K,V>s, as well as user tags, to the GraphML file format is supported by the GraphML reading and writing support, see section Adding Custom Data for Serialization.

get(K key): V

Gets the value associated with the key. The value returned for non-set entries is not specified. Most implementations in yFiles for HTML return null. Mapper<K,V> optionally allows defining a defaultValue for non-set entries.

set(key: K, value: V): void

Sets the value for the given key, overwriting existing values.

Note that some IMapper<K,V> implementations are read-only. Calling set will not have an effect in that case.

The default implementation is Mapper<K,V>, which is backed by a map. It is a read/write implementation of IMapper<K,V> and additionally allows defining a defaultValue for non-set entries.

The factory method IMapper<K, V>.fromConstant<K,V> creates an IMapper<K,V> implementation that returns the given instance for all keys. The factory method IMapper<K, V>.fromHandler<K,V> returns an IMapper<K,V> implementation that delegates to the given Function to return values for keys. Note that both implementations are read-only.

IMapper<K,V> is a convertible type that is automatically converted from native JavaScript Map instances. See Automatic Type Conversion.

// creating the default implementation
const defaultMapper = new Mapper()

// creating a mapper providing the same instance for each key
const constantMapper = IMapper.fromConstant('Always the same.')

// creating a mapper using a delegate to return the first label's text
const delegateMapper = IMapper.fromHandler((node) =>
  node.labels.size > 0 ? node.labels.get(0).text : null
)
// creating the default implementation
const defaultMapper = new Mapper()

// creating a mapper providing the same instance for each key
const constantMapper = IMapper.fromConstant('Always the same.')

// creating a mapper using a delegate to return the first label's text
const delegateMapper = IMapper.fromHandler((node: INode): string | null =>
  node.labels.size > 0 ? node.labels.get(0).text : null
)