416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.5

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Visualization Color Codes Control - Dashboard Add-on

Hide navigation
RSS
Modified on Thu, 19 Feb 2015 11:49 AM Categorized as Add-ons, Level-Advanced
Click to return to: Documentation | Dundas Dashboard Add-ons


Go to the Dundas Dashboard Add-ons page for instructions on downloading and installing this add-on.

Overview

The Visualization Color Codes control lets you apply colors to data points or series based on their associated dimension member values. For example, you can use this control to colorize a Sales by Product bar chart such that the data point for Product A (which is a dimension member) is colored red, and the data point for Product B is colored blue. The same colorization can also be applied to other data visualization controls in order to have a consistent, data-driven color scheme across the dashboard.

You generally use the Visualization Color Codes control to:

  • Define the mappings (⪚ color codes) between colors and the members of a dimension.
  • Manage scripts for coloring data points or series according to the color mappings.
  • Specify which data visualization control will be colored by which script.

The Visualization Color Codes control is visible at design-time only. It is not displayed when your dashboard is being previewed or viewed.

Example

The figures below show an example of the type of colorization which can be achieved:

Before: A bar chart with default coloring.

Before: A bar chart with default coloring.


After: The same bar chart, showing colors specific to each product.

After: The same bar chart, showing colors specific to each product.


For reference, the bar chart is displaying a Downloads By Product KPI, which has the following characteristics:

  • KPI name: Downloads By Product
  • KPI measure: Number of Downloads
  • KPI dimension: Product (a two-level standard/full dimension)

Here is a preview of the KPI:

Preview of the Downloads By Product KPI.

Preview of the Downloads By Product KPI.


Installation

To install the Visualization Color Codes add-on:

  1. Start the Dundas Dashboard Deployment Center.
  2. Click Add-Ons and following the instructions for deploying the selected add-on.
  3. Restart the Dundas Dashboard website (⪚ restart IIS).

Once installed, the Visualization Color Codes control appears as an item in the Data Controls section of the Dashboard Designer toolbox. Just drag and drop the item onto the dashboard canvas like you would with any other control.

The Toolbox showing the Visualization Color Codes control.

The Toolbox showing the Visualization Color Codes control.


Usage

Step 1 - Define colors for members

The first step is to associate colors with dimension members. The Visualization Color Codes control lets you define mappings between colors and dimension members in one of two ways:

  1. Define the mappings manually by using the Color Codes property.
  2. Create a two-column dataset that defines the color mappings and bind it to the Color Codes control.

Note: Using a dataset is optional, and needed only if you wish to automatically map the color codes. Without it you can still map the colors manually. Refer to the "Entering color codes manually" section.

Entering color codes manually

The following example shows how to define color mappings manually by entering color codes:

  1. Select the Color Codes control on the dashboard canvas and go to its properties window.
    Color Codes properties.
  2. Locate the Color Codes property and click its ellipsis button. The Color Codes property dialog is displayed.
    Color Codes property dialog.
  3. In the Color Codes property dialog, click the Add button to add a new color code to the list on the left. The properties of the color code appear on the right. Configure the color code as follows:
    • Category Value: Elenci DX
    • Fill: Red
      Fill property.
      Note: Category Values are Case Sensitive.
  4. Add color codes corresponding to other Product dimension values as needed (⪚ Ardintic DL, Pontilo LX, and Orena II).
    3 other color codes added.

Binding to a dataset

The following example shows how to use the color mappings defined in a dataset.

Assume that you have a dataset with two string columns. One column contains dimension member values. The other column contains corresponding color values in the form of a string (⪚ Red or #FF0000). It does not matter what the columns are named or what order they are in:

A dataset with two columns.

A dataset with two columns.


To bind to this dataset:

  1. In the Dashboard Designer, select the Color Codes control and go to the properties window.
  2. Make sure the Color Codes property is empty (&ie; None). This is necessary because manually entered color codes take precedence (over the dataset approach).
  3. Drag the dataset from the toolbox and drop it on top of your Visualization Color Codes control. The Data Settings Configuration Wizard is displayed.
  4. In the wizard, click Next to go to the Dimension Selection tab. Use the dropdown list to choose a column from your dataset to represent the Category Value (&ie; dimension values). Choose a second column to represent the Color, then click Finish.
    Choose dimensions.

By default, the Color Codes control will auto-detect the format of the color string values. You can also choose a specific format using the Color Input Type advanced property, which supports formats such as Hex, Int, and Name.

The Color Input Type advanced property.

The Color Input Type advanced property.


Step 2 - Add scripts

The second step is to use the Scripts property to add one or more scripts which perform the actual colorization of data points displayed by a data visualization control. Each type of data visualization control requires its own kind of script.

The following example shows how to add a script for a chart that displays the Downloads By Product KPI:

  1. Select the Color Codes control and go to its properties window.
  2. Locate the Scripts property and click its ellipsis button. The Scripts property dialog is displayed.
  3. In the Scripts property dialog, click the Add button to add a new script to the list on the left. The properties of the script appear on the right.
    Scripts property dialog.
  4. Each script has a Script Mode property which specifies when the script runs. If the script mode is set to On Start, the script will run once when the dashboard is loaded or when the data changes. If the script mode is set to Row, the script will run once for each color mapping. For this example, set the script mode to On Start.
  5. Click the ellipsis button of the Script property to open the Script Editor dialog. Enter the following script, then click Save.

foreach(DashboardDataSeries series in e.Control.Series) { foreach(DashboardDataPoint point in series.Points) { object xValue = series.DataDescriptor.GetDataPointAxisValue(point.DataSource); point.Fill = series.Fill; if (e.ColorDictionary.ContainsKey(xValue)) { point.Fill = e.ColorDictionary[xValue]; } } }

A script can make use of the following event arguments:

  • e.ColorDictionary – A dictionary of <object, Brush>. The object key will be a dimension member and could be of type string, DateTime or numeric. The value will be a brush. If you used the dataset approach, any colors from the data will be used as part of a solid color brush.
  • e.Control – The control that is specified in the Control Mappings property for the script.
  • e.CurrentRow – Only used if the script mode is Row. In this mode, the script will run once for every key-value pair in the color dictionary, and e.CurrentRow will be the current key-value pair.

If you are using splitters and you need to set the color based on the splitter value, you can use script similar to the one below. Make sure you use your own splitter column name:

foreach(DashboardDataSeries series in e.Control.Series) { foreach(DashboardDataPoint point in series.Points) { object xValue = series.DataDescriptor.GetDataPointColumnValue (point.DataSource, "yoursplittercolumn"); point.Fill = series.Fill; if (e.ColorDictionary.ContainsKey(xValue)) { point.Fill = e.ColorDictionary[xValue]; } } }

To synchronize the Legend's marker fill, you can add the script below:

foreach(DashboardDataSeries series in e.Control.Series) { foreach(DashboardDataPoint point in series.Points) { //... see script above }

//script to color the legend item markers: foreach (DashboardLegendItem legendItem in Legend1.LegendItems) { if (legendItem.Text == series.LegendText) { legendItem.MarkerFill = point.Fill; } } }




Step 3 - Map controls to scripts

The third and last step is to use the Control Mappings property to specify which data visualization control will be colored by which script:

  1. Select the Color Codes control and go to its properties window.
  2. Locate the Control Mappings property and click its ellipsis button. The Control Mappings property dialog is displayed.
  3. In the the Control Mappings property dialog, click the Add button to add a new control mapping to the list on the left. The properties of the control mapping are displayed on the right. Configure the control mapping as follows:
    • Set the Data Control Name property to BarChart1.
    • Set the Script Name property to Script 1.
      Control mapping.


The configuration of the Color Codes control is now complete. Save and preview your dashboard to see the re-colorization of data points:

A bar chart showing product-specific colors.

A bar chart showing product-specific colors.


Release history

This add-on was first released with Dundas Dashboard 2.5.1.

Related topics




Click to return to: Documentation | Dundas Dashboard Add-ons

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2016 Dundas Data Visualization, Inc.