Render different colors for a symbol based on a property

Question

How to render different colors for a symbol based on a property?

Answer

First, you will need a symbol that contains a property allowing you to change its color. Here are the steps to do so in the Symbol Editor:

Use the Symbol Editor to create a symbol and add a parameter of type "Color" to it. Next, create a condition where " "<PARAMETER_NAME> exists and not null". Select the condition in the Symbol Outline and under the "Paint" tab, set the "Fill paint" as an expression to "@ "<PARAMETER_NAME>".

For more details on using expressions in Symbol Editor, please refer to the documentation under the section "Developing with design tools > Using the Symbol Editor > Using more features of the Symbol Editor > Using expressions".

Now that you have a symbol allowing you to change its color, you need to specify a color object to the property to change the symbol's color. There are two main approaches to change the value of the property. You can either change the property through CSS or API.

In CSS:

You can create a rule that matches the node's property equal to a particular value then based on that condition set the color property to a color. For example:

ode {
   class : "@|symbolResource(<resource file>, <entry point>)" ;
   ...
}

node[type="Type1"] 
{
   <PARAMETER_NAME>: "red" ;
}

This rule checks to see if you have a node with a "type" property that is set to "Type1". If there is such a node then the node's property will be set to "red".

Through API:

You can change the property dynamically through code. You can set a property value to the node symbol as a "java.awt.Color" object by calling "IlvDiagrammer.setObjectProperty(Object nodeOrLink, String propertyName, Object propertyValue)". In the second argument, you can set the property name to a name of your choosing. Before you can use your symbol with your new parameter, you need to specify the node rule in CSS like the following:

node {
   class : "@|symbolResource(<resource file>, <entry point>)" ;
   <PARAMETER_NAME>: "@<NAME_OF_PROPERTY_YOU_SET_IN_JAVA>" ;
   ...
}

For more details on using a symbol in CSS, please refer to the documentation under the section "Programmer's documentation > Developing with the JViews Diagrammer SDK > Managing dynamic symbols > How to use a symbol in CSS".

To change the color based on an existing property of a node, you can call "IlvDiagrammer.getObjectProperty(Object nodeOrLink, String propertyName)" to get the current value from a particular property then use that value to determine the color of the node.

Attached is a modified version of the "Maps" sample located in the JViews Diagrammer distribution that demonstrates the above technique.

You need to replace the files in the sample with the files in this FAQ. Also in the sample's build.xml file, add the path to the "Node_Symbols.jar" file to the "jviews.manifest.classpath" property. For example:

<property name='jviews.manifest.classpath'
              value='... ${jviews.manifest.home}/jviews-diagrammer88/samples/diagrammer/map/data/Node_Symbols.jar ${jviews.sample.manifest.classpath}'/>

Finally, rebuild the sample and run the diagrammer-map.jar executable. When you run the sample, click the "Change Node Color" button at the bottom to change the colors of the node symbols based on their "type" property. You can see the properties of the nodes in "/data/map.xml". The sample is located in:

<JVIEWS_DIAGRAMMER_INSTALL>samples\diagrammer\map\

For information on rebuilding the application sample and running it with ant, please refer to the documentation under the section "Samples and code examples > Starting the samples".

Note: In order to run this sample with JViews 8.6, you must comment out the ilog.views.util.IlvProductUtil.DeploymentLicenseRequired method calls (See lines 49-50 and 54-55).

As you can see, CSS is a more static approach while the API approach offers more flexibility allowing you to include some business logic and update the symbol's property based on certain conditions.