Associating Data with Graph Elements
It is often necessary to connect the graph items with the data model, or business data, they actually represent. yFiles for HTML provides two options to store the data linked with the graph items:
Most conveniently, business data can be associated with a graph element using the tag property which 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 which bind a value of type V to a given key of type K, the key typically is a graph item, e.g. 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 which 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 which is associated with the key.
The value which is 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. Overwrites existing values.
Note that some IMapper<K,V> implementations are read-only, i.e. calling set won’t have an effect.
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 to define a defaultValue for non-set entries.
The factory method IMapper<K, V>.fromConstant<K,V> creates an IMapper<K,V> implementation
which returns the given instance for all keys.
The factory method IMapper<K, V>.fromDelegate<K,V>
returns an IMapper<K,V> implementation which 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.
The IMapperRegistry
Each IGraph has an IMapperRegistry which provides a means to associate IMapper<K,V>s with that graph. The registry can be obtained from IGraph’s mapperRegistry property. An IMapper<K,V> has to be added to the registry using a unique object, the tag. This object can be used to retrieve the mapper from the registry later.
Depending on the implementation, “unique” means there is no equal tag in the same registry or no tags with the same hash code. Although not mandatory, we recommend using different strings as tags.
Besides adding existing IMapper<K,V> instances the IMapperRegistry provides factory methods to create IMapper<K,V> instances and add them immediately:
- Adding existing mappers
- addMapper<K,V>(keyType: Class<K>, valueType: Class<V>, tag: Object, mapper: IMapper<K, V>): void
- Registers the given mapper with the given tag.
- Creating and adding mappers
- createMapper<K,V>(keyType: Class<K>, valueType: Class<V>, tag: Object): Mapper<K, V>
- Creates a Mapper<K,V>, registers it with the given tag, and returns the newly created instance.
- createConstantMapper<K,V>(keyType: Class<K>, valueType: Class<V>, tag: Object, constant: V): IMapper<K, V>
- Creates an IMapper<K,V> which always returns the given value, registers it with the given tag, and returns the newly created instance.
- createDelegateMapper<K,V>(keyType: Class<K>, valueType: Class<V>, tag: Object, getter: MapperDelegate<K, V>): IMapper<K, V>
- Creates an IMapper<K,V> which delegates to the given
Function
to return a value, registers it with the given tag, and returns the newly created instance. - Retrieving a registered mapper
- getMapper<K,V>(tag: Object): IMapper<K, V>
- Returns the mapper which is registered under the given tag.
The following example summarizes all we have learned in this chapter: