416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
Dashboard v5.0

This site makes extensive use of JavaScript.

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

Text Keywords

Hide navigation
RSS
Modified on Mon, 30 Jul 2012 10:31 AM Categorized as Chart, Design, Gauge, Maps, OLAP, Traffic Lights, Treemap
Click to return to: Documentation | Designing Dashboards


Keyword substitution

Various controls in Dundas Dashboard have text properties that support special keywords. These keywords act as placeholders which are replaced dynamically with actual values at viewing-time. Keywords offer a way for you to customize strings in your dashboard, such as tooltips and labels, without having to write any scripts.

Keywords can be written as #KEYWORD in any text property and their values are replaced at viewing-time by the control.

When setting a property using keywords, you can combine multiple keywords together or combine keywords with other text to include as many details as you like. For example, setting a tooltip text property to:

Sales Rep: #SALES_REP, Total: #SALES_TOTAL{C2}

will display text like this when the tooltip is invoked:

“Sales Rep: Bob, Total: $4,895.11”

Note: Using a script to retrieve the value of a property that has a keyword in it will return text containing the keyword instead of the evaluated result.

KPI/dataset columns

You can also use keywords that specify the names of measure, contextual metric, axis dimension, or data annotation columns returned by a KPI or any column of a dataset. Such keywords evaluate to the corresponding value, such as a metric or dimension value.

Keywords are always in upper case, and non-alphanumeric characters are replaced with underscores (_). For example, to refer to a measure named “Sales Total”, use the #SALES_TOTAL keyword.

  • #COLUMN_NAME — The value for the specified KPI or dataset column. This works even if the column is not otherwise displayed in the control itself.

Formatting keyword values

Numeric and date/time values displayed using keywords can be formatted to display a certain numeric of decimal places, a currency or percentage symbol, or a specific combination of date and time components (such as year, month, and day). Keywords support Microsoft .NET formatting options, which are documented separately for numeric values and date/time values.

To format a keyword value, add the formatting string in braces immediately after the keyword. For example:

#SALES_TOTAL{C2}

Entering keywords

To use a keyword in a text property, you can simply type it inline in the property grid.

Using a keyword in the Tooltip Text property of a chart series.

Using a keyword in the Tooltip Text property of a chart series.


Or, click the property's ellipsis (...) button to launch the Keywords Editor, which makes it easy to choose a supported keyword and format it the way you want.

Keywords Editor.

Keywords Editor.


In the Keywords Editor:

  • Use the dropdown list at the top to insert an available keyword at the cursor position, or replace the current underlined keyword.
  • Type the keyword character (#) to get a popup menu that lists the available keywords you can choose from. Select a keyword, and then double-click with your mouse, press TAB, or press ENTER.
  • Use the Index control to increment or decrement the index for keywords such as YVALUE that correspond to a collection property of the control. Note that index values begin at 1.
  • Click the Format button to access the Text Format dialog which helps you to compose the desired formatting string for a keyword.

Supported keywords

The following sections describe the keywords supported by various data controls.

Chart

In the Dashboard chart, you can use keywords on data point text properties to automatically insert the values of other properties or data columns. You can set the following properties using keywords on a data point, or on a data series to affect all points within that series:

  • Label Text (LabelText)
  • Legend Text (LegendText, when displaying a legend item for each data point)
  • Tooltip Text (ToolTipText)
  • X Axis Label Text (XAxisLabelText)

The following keywords are available in addition to the KPI keywords:

  • #LABELTEXT — The point's label text (LabelText property).
  • #LEGENDTEXT — The point's legend text (LegendText property).
  • #TOOLTIP — The point's tooltip text (ToolTipText property).
  • #XVALUE — The point's X axis value (XValue property).
  • #YVALUE or #YVALUE1, #YVALUE2, &etc; — The point's Y value(s) (YValues property).
  • #FORMATTEDXVALUE — When using a KPI with a time dimension, the formatted date/time value as specified in the dimension.
  • #XAXISLABELTEXT — The text specified as the point's X axis label text, if any. (XAxisLabelText property).
  • #PERCENT — Displays the percentage of the data point's Y value relative to the series total.
  • #STACKEDTOTAL — Displays the total of values stacked on top of others up to the data point (stacked charts only).
  • #STACKEDPERCENT — Displays the percentage of the data point's Y value relative to the stack total (100% stacked charts only).
  • #TOTAL — Total of all Y values in the series.
  • #AVG — Average of all Y values in the series.
  • #MIN — Minimum data point of all Y values in the series.
  • #MAX — Maximum data point of all Y values in the series.

Examples:

If you set the tooltip text for a data series to (assuming there are KPI/dataset columns named Date and Sales):

  1. DATE{MMMM} Sales: #SALES{C2}


The tooltip on each data point will look something like this:

November Sales: $23,512.67

Setting the label text to:

  1. YVALUE (#PERCENT{P1})


Will display a label like the following on each data point:

791 (46.7 %)

Data Grid

The Data Grid control's column text and tooltips can be customized by using keywords with the following properties on a column:

  • Data ToolTip (DataToolTipText)
  • Text (DataText)
  • Total ToolTip (TotalDataToolTipText)

In addition to data columns, the following keywords are supported:

  • #AGGREGATORTYPE — Displays the aggregator type set for the column, used to display values in the totals row.
  • #HEADERTEXT — Displays the column header text.
  • #VALUE or #VAL — The value displayed by the column for each row.

For a walkthrough on setting keywords in the data grid, see Using the Data Grid.

Display Indicator

The Display Indicator control supports these keywords in the Tooltip property of the indicator:

  • #TEXT — The text displayed by the indicator.
  • #VALUE or #VAL — The KPI/metric value displayed by the indicator.

Gauge

In addition to several keywords, gauge pointers that are bound to a KPI or dataset also support keywords for that KPI's or dataset's data result columns.

Pointers support the following keywords in the LegendText and ToolTipText properties:

  • #LEGENDTEXT — The pointer's legend text (LegendText property).
  • #TOOLTIP — The pointer's tooltip (ToolTipText property).
  • #VAL — The pointer's current value.
  • #VALUE — A synonym for #VAL.

Ranges support the following keywords in the LegendText and ToolTipText properties:

  • #ENDVAL — The range's ending value.
  • #ENDVALUE — Same as #ENDVAL.
  • #LEGENDTEXT — The range's legend text (LegendText property).
  • #STARTVAL — The range's starting value.
  • #STARTVALUE — Same as #STARTVAL.
  • #TOOLTIP — The range's tooltip (ToolTipText property).

Scales support the following keywords on the ToolTipText of their Labeling, MajorTick and MinorTick properties:

  • #VAL — The scale's current value for the property.
  • #VALUE — A synonym for #VAL.

Examples:

If you set the tooltip for a pointer to:

Avg Sales: #VALUE{N2} (#DATE{MMM yyyy})

Will set the pointer's tooltip to something like this:

Avg Sales: 20,200.55 (May 2010)

Setting a pointer's legend text to:

Avg Sales = #VALUE"

Will give you an entry like this in your legend:

Avg Sales = 20,200.55

Map

Map elements such as Shapes, Symbols, and Paths support keywords on the:

  • Text of their Label properties
  • ToolTipText property.

Valid keywords include:

  • #NAME — Displays the name of the map element.
  • #_DATASETNAME — Displays the dataset column value that has been data-binded to the map element.
  • #_KPINAME — Displays the KPI measure value that has been data-binded to the map element.

The _DATASETNAME keyword must contain the name of a dataset and use uppercase letters, exclude any spaces, and begin with an underscore (_). For example, if your dataset is named “My Dataset”, use the keyword #_MYDATASET.

The _KPINAME keyword must contain the name of a KPI and use uppercase letters, exclude any spaces, and begin with an underscore (_). For example, if your KPI is named “Sales By Region”, use the keyword #_SALESBYREGION.

It's possible to bind a dataset or KPI to a map more than once (⪚ each time with a different value column). In this case, to reference the second or third data value, append a numbered suffix to the keyword as shown in the example below:

  • Name of first dataset added: World Map Data
    • Keyword to use: #_WORLDMAPDATA
  • Name of second dataset added: World Map Data
    • Keyword to use: #_WORLDMAPDATA_2_
  • Name of third dataset added: World Map Data
    • Keyword to use: #_WORLDMAPDATA_3_

Note: The #COLUMN_NAME keyword is not supported by the map control.

Example:

The figure below shows how to set the ToolTipText property on a United States shape element, which has been data-binded to a population value from a dataset called World Map Data.

Using the Shape collection editor to set the ToolTipText property.

Using the Shape collection editor to set the ToolTipText property.


Viewing the tooltip on the map:

A tooltip on a shape that uses keywords.

A tooltip on a shape that uses keywords.


When you add a dataset or KPI to a map, you have the option of defining one or more map states, which specify how data values should be mapped to properties of a map element (⪚ shape color, or symbol size). Each map state can generate text for a legend that is associated with your map.

A map state's LegendText property accepts the following keywords:

  • #NAME — Displays the name of the state.
  • #STATENAME — Displays the name of the state.
  • #MIN — Displays the minimum data value for the state or data group.
  • #MAX — Displays the maximum data value for the state or data group.
  • #DESCRIPTION — Displays the default description text provided by the legend.

For more details on map states and map data-binding, see Using the Map Control.

Using keywords in the legend text of a state.

Using keywords in the legend text of a state.


The corresponding map legend.

The corresponding map legend.


Sparkline

The Sparkline control supports a single keyword in its First Point Text, Last Point Text, High Point Text and Low Point Text properties:

  • #YVALUE — Displays the Y (metric) value for the data point.

Note: The #COLUMN_NAME keyword is not supported by the sparkline control.

State Indicator

The State Indicator control supports these keywords in the Tooltip property of an indicator state:

  • #STATE — Displays the name of the state.
  • #VALUE — Displays the KPI/metric value.

Note: The #COLUMN_NAME keyword is not supported by the state indicator control.

Traffic Light

The Traffic Light control supports these keywords in its ToolTip property:

  • #MEASURE — Displays the measure used for this traffic light.
  • #VALUE — Displays the value of this traffic light.

Note: The #COLUMN_NAME keyword is not supported by the traffic light control.

TreeMap

The TreeMap control supports several keywords to substitute values from its states in the LegendText property:

  • #STARTVAL or #STARTVALUE — Displays the minimum data value for the state or data group.
  • #ENDVAL or #ENDVALUE — Displays the maximum data value for the state or data group.
  • #NAME or #STATENAME — Displays the name of the state.

TreeMap nodes support the following keywords on their Child Text and Child Tooltip properties:

  • #SIZENAME — Displays the name of the measure or metric that determines the size of nodes.
  • #COLORNAME — Displays the name of the measure or metric that determines the color of nodes.
  • #SIZE or #SIZEVALUE or #MEASURE1 — Displays the value of the measure or metric that determines the size of nodes.
  • #COLOR or #COLORVALUE or #MEASURE2 — Displays the value of the measure or metric that determines the color of nodes.
  • #DIMENSION — Displays the dimension value that corresponds to the tree map node.

Analytical Controls

The Analytical Combo and Analytical Chart controls support the following keywords on the Tooltip Text and Label Text properties of their chart series:

  • #MEASURES — Displays the name and value of each measure (from the Measures pane) for the data point.
  • #MEASUREi — Displays the value of the measure for the data point, as specified by the index, i. Note that keywords such as #MEASURE2 and above only apply to series with chart types that accept multiple Y values.

  • #CATEGORICALMEMBERS — Displays the name and value of each categorical dimension (from the Categorical pane) for the data point.
  • #CATEGORICALMEMBERi — Displays the value of the categorical dimension for the data point, as specified by the index, i.
  • #CATEGORICALMEMBER — Displays the value of the last categorical dimension for the data point (⪚ same as #CATEGORICALMEMBER2, if there are two categorical dimensions).

  • #SERIESMEMBERS — Displays the name and value of each grouping dimension (from the Grouping pane) for the data point.
  • #SERIESMEMBERi — Displays the value of the grouping dimension for the data point, as specified by the index, i.
  • #SERIESMEMBER — Displays the value of the last grouping dimension for the data point.

Setting the Tooltip Text property on the Chart Series for an analytical control.

Setting the Tooltip Text property on the Chart Series for an analytical control.


Viewing the default tooltip on a data point.

Viewing the default tooltip on a data point.


Related topics



Click to return to: Documentation | Designing Dashboards

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.