Custom properties are a flexible
means for storing additional data with the elements of a graph.
By default, however, they are not visible in the diagram.
The Properties Mapper dialog lets you change the visible properties of the nodes
and edges in a graph according to their custom properties.
As a simple example, you can map text stored in a custom node property ("My Node
Text Property") to the label text of the corresponding nodes.
But it is also possible to turn integral values of a custom property into different
colors for nodes.
You can open the Properties Mapper dialog by selecting the menu entry Edit >> Properties Mapper...
The Properties Mapper lets you define mappings that describe how to turn (values of) custom properties into (values of) visual properties of the nodes and edges of a graph. The visual properties cover nearly all properties that can be seen in the Properties View tool window of a graph element.
Mappings are part of configurations, which can contain virtually any number
of mappings.
Changing the visual properties according to a configuration is called applying
the configuration in the following.
Applying a configuration is a one-time change of the diagram like adding a node
or changing a label.
It is possible to undo the Apply configuration action.
A configuration is a set of mappings either for the nodes or for the edges of a
graph.
All available configurations are listed on the left of the Properties Mapper dialog
and are appropriately marked as applying to nodes or edges.
If you select a configuration from the list, the mappings of the configuration are
displayed in the Mappings table in the middle of the dialog.
To create a new configuration for nodes or for edges, click the plus icon over the Configurations list in the top left corner of the Properties Mapper dialog and select the corresponding option. In the Name text field in the Selected Configuration section you can assign a suitable name to your configuration.
A mapping is always part of a configuration. It is defined by three parameters which are listed in the Mappings table in the middle of the dialog:
There are different kinds of conversions possible, which depend on the type of the custom property in Data Source (for example, number or text) and the visual property in Map To (see below).
Although a mapping uses (the values of) a single custom property, you may have several mappings in a configuration that the use same custom property, if you want to change different aspects of the presentation based on the same information.
Normally, a mapping only changes aspects of the current representation of a graph element, like the line color of an edge or the border color of a node, but not the node (edge) representation itself. A template mapping, in contrast, is a special mapping that is intended to do just this.
A template mapping allows to change the template for the visual representation of
an element.
A configuration may have at most one template mapping.
Whether a configuration uses a template mapping or not can be specified by means
of the radio buttons of the Template option below the Name text
field.
The following options are available:
To create a mapping, click the plus icon to the right of the Mappings table. This creates a new row in the table that shows
By choosing from a drop-down combo box which opens upon clicking in the corresponding cell, you can change each of these default values.
Creating a mapping is also shown in the example below.
The possible conversion types for a mapping depend on its Data Source and Map To parameters. The following kinds of conversions are available for suitable mappings:
#a4feb000
"
(RGBA) or "#a4feb0
" (RGB), or numbers, like "12", which enables
mapping "Text" to "Line Color" and "Font Size", respectively.
All but the "Automatic" kind of conversion need further definition, which you can carry out in the Conversion Details section that is below the Mappings section.
In the Conversion Details section of the dialog you can define further details for specific conversion types, like "Distinct Values", "Range of Values", "Linear Scaling", and "Regular Expression".
First select the row in the Mappings table that contains the conversion for which you would like to define further details. The Conversion Details section adjusts according to the actual conversion type:
$n
, n
a number,
denotes a reference to the n
-th capturing group and will be replaced by
the group's value.
You can include a literal dollar sign in the replacement text by preceding it with a
backslash (\$
).
Similarly, a literal backslash is included by preceding it with a second backslash
(\\
).
\n
to include a line
break in the replacement text.
In the first two cases the values of the custom property can be chosen from a drop-down combo box (opens upon clicking in the input field/the table cell) that also allows to edit presented values/enter new values.
Creating conversion details is also shown in the example below.
If you map to a label property like "Label Text" or "Label Background Color", you can additionally specify the number of the label with the Map To Label No. spinner, since a node or an edge may have several labels. Label 1 is the main node or edge label.
Additionally, if you map to a node label with internal "Placement", you can automatically adjust the size of the node to the size of the label by enabling the Fit Node to Label check box.
Click either the "Single" or the "Multiple" radio button to add a template mapping to your configuration. A new row is added at the top of the Mappings table which shows "Template" in its Map To column.
Creating a template mapping is also shown in the example below.
If you want to apply your mappings to the current diagram, press the Ok or Apply button. Both apply the currently selected configuration to the active diagram. Pressing the Ok button also closes the Properties Mapper dialog. You can undo the changes resulting from applying a configuration like any other change.
The properties mapper is aware of new custom properties that are added to the current graph. You can open the Custom Properties dialog (Edit >> Manage Custom Properties...) in parallel to the Properties Mapper dialog. If you add a new property in the Custom Properties dialog you can immediately use it in the Properties Mapper dialog. If you change the active editor tab both the Custom Properties and the Properties Mapper dialog reflect that change.
The Properties Mapper dialog keeps mappings defined for custom properties which are not available in the current diagram. If you apply a configuration with mappings based on unavailable custom properties, they simply have no effect.
Let's have a look at an example to see how the Properties Mapper dialog can help
you turn your custom properties into visual properties of your graph elements.
Let's start with the travel_durations.graphml
graph from the Help menu
(Help >> Example Graphs >> Custom Properties):
These are the custom edge properties defined in this graph:
None of them is visible, however, i.e., we cannot see the values of these custom
properties as annotated with the edges.
We will make them visible with the help of some mappings.
Open the Properties Mapper dialog (if not already open) and arrange it so that you
can also see the example graph.
Let's create a configuration for edges to hold these mappings. Click the plus icon over the Configurations list in the top left corner of the Properties Mapper dialog and select "Configuration for Edges".
With the configuration ready, we can start creating mappings. Let's start with an easy one. Click the plus icon to the right of the Mappings table in the middle of the dialog. This creates a new row in the table with three columns reading: "Duration (minutes)", "Label Text", "Automatic".
This is in fact our first mapping. Click the "Apply" button at the bottom of the dialog and see what happens.
Great, we can see the travel durations between capitals in the diagram!
Let's suppose (but only for a moment), we didn't like the result of applying the
configuration.
How can we go back?
Click the "Undo" button in the yEd tool bar to return to the diagram before the
"Apply" action.
It's this easy to get to the previous state again.
Now let's add a second mapping that also uses the "Duration (minutes)" custom property,
however, this time mapped to the "Line Width" visual property by means of a "Linear
Scaling" conversion.
To specify these settings, you can use the drop-down combo boxes that open upon
clicking into the respective table cells.
Note, however, that the "Linear Scaling" conversion will only be available in the
drop-down combo box in the third column after you have specified the "Line Width"
visual property in the second column!
(This is because the conversion depends on the types of both the custom property
and the visual property that you choose.
See also the description above.)
After choosing the "Linear Scaling" conversion in the third column, the Conversion Details
section below the Mappings table adjusts to show four input fields.
The two to the left are already filled, in the two to the right enter:
"1" (lower bound) and
"10" (upper bound).
This defines the details of our "Linear Scaling" conversion.
Click the "Apply" button to see how longer travel durations have turned into thicker
edges.
Looking at the diagram, it seems a good idea if we could also see the different means of travel more prominently, doesn't it? Let's realize this by adding a mapping where the "Means of Travel" custom property is mapped to the "Line Color" visual property by means of a "Ranges of Values" conversion.
With this third row in the table still selected, we can create conversion details
in the Conversion Details table below the Mappings table:
click the plus icon to the right of the Conversion Details table three
times.
This creates three new rows in the table, each with a color chooser control in the
second column.
For each of the rows choose another "Means of Travel" value from the drop-down combo
box, for example:
"Car"
"Plane"
"Train"
and assign three colors of your liking.
Click the "Apply" button to get something along this:
As a last step in this example, let's create a template mapping.
The template mapping can be used to change the template for the visual representation
of edges.
Click the "Multiple" radio button below the Name text field at the top
of the dialog.
This adds a new row at the top of the Mappings table.
Choose the "Means of Travel" custom property in the first column and the "Distinct
Values" conversion in the last column of the row.
With the row in the table still selected, add a conversion detail in the Conversion Details
table with the value "Car" in the first column.
Then, in the second column, choose from the popup menu the Edge Types >> Arc
as the new edge representation.
Now click the "Apply" button to see that "Car" edges are represented by arc edges
instead of polyline edges.
In this example we have created and applied a configuration for edges with several mappings. Creating a configuration for nodes is very similar.