The Chart Canvas element's Series child elements cause a data visualization (the chart) to be rendered in the canvas. This topic discusses the Series.Heatmap element.


About Series.Heatmap

The Series.Heatmap element generates a Heatmap chart, sometimes called a "tree map", which uses a unique arrangement of rectangles to represent data and relationships, using color and size.  

Both the color intensity (shifting within a range) and the size of the rectangles indicate relative performance, helping you to easily spot trends with a glance. This type of chart is very useful for showing hidden trends and relationships.

In the example above, the rectangle's (or cell's) size represents the average order value for each food item. The cell color also represents the average order value, ranked from red (low) to green (high). The relationship isn't linear but we can still see that items with small, red cells produced fewer orders and less revenue than items with large, green cells.

The example above is the same data but now the cell color reflects the number of orders. "Greener" cells have a higher number of orders. This allows us to compare an item's popularity (size) to its average order value (color).

As shown above, the chart is created by adding Series.Heatmap to the canvas, along with a datalayer and, typically, some child elements that may include a Group Filter, and a Group Aggregate Column element. Very few attributes need to be set for the Series element in order to produce a basic chart.

Note that a datalayer element can be used either beneath Series.Heatmap, as shown above, or beneath Chart Canvas. If used as a child of Chart Canvas, its data is available to all child Series elements. This can improve performance if you have several series, all using the same data, beneath the same Chart Canvas element.

Back to top


The Series.Heatmap element has the following attributes:

Heat Map Color Data Column (Required) Specifies the name of a datalayer column whose values will determine the color of the cells, using a high-to-low gradient based on the three Value Color attributes.
Heat Map Label Data Column (Required) Specifies the name of a datalayer column whose values will be used as labels inside the cells.
Heat Map Size Data Column (Required) Specifies the name of a datalayer column whose values will determine the size of the cells.
Cell Border Color Sets the color of the cell borders. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #112233.
Cell Border Color Transparency Specifies the transparency of the Cell Border Color. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.
Cell Border ThicknessSets the thickness of the cell border lines, in pixels, when the related Cell Border Color attribute has a value. The default value is 1 pixel.
Disable Mouse Tracking Disables mouse tracking for the series, when set to True. This affects tooltips and click events on cells. For large datasets, this may improve performance.
The default value is False.
High Value Color Specifies the color for the highest data value. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #D5F484.
Hover Brightness Specifies the amount to change a cell's color when the mouse pointer is hovered over it. Values can be between 0 (no change) and 15 (lighter). The default value is 2.
ID Specifies the unique element ID.
Low Value Color Specifies the color for the lowest data value. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #D5F484.
Medium Value Color Specifies the color for the data values in the middle of the dataset. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #D5F484.

Back to top

Grouping Heatmap Cells

You can also group cells in a Heatmap using the Heatmap Group element:  

In the example above, the products have grouped by category. In order to use grouping, you must ensure that your datalayer includes the appropriate data. The Heatmap Group element allows you to control the appearance of the group title font, title alignment, borders, and background color.

Back to top

Using the Heatmap Label Style Element

The Heatmap Label Style element can be used to control the appearance of the label text that displayed inside the cells:  

By default, labels will appear at the top of the cell, as shown above, top. The Heatmap Label Style element has attributes that allow you to control the font family, color, size, and weight, and positioning of the text. You can also specify different font colors for cells with light and dark backgrounds.

Back to top

Using the Quicktips Element

By default, a "quicktip" is displayed when the mouse hovers near or over a data point:  

The automatically-generated quicktip displays information from the label and size data columns, as shown above, left. However, you may want to display other information or format it differently, perhaps as shown above, right, which can be done by adding a Quicktip child element beneath Series.Heatmap and setting its attributes and child elements. Use @Chart tokens to include chart data in the quicktip. Intrinsic functions are supported in the Quicktip attributes. A default quicktip is also displayed when a Heatmap Group element is used. To customize it, the Quicktip element can also be a child of Heatmap Group.

Back to top

Using the Chart Drill To Element

The Chart Drill To element, a child of the Series element, enhances charts by allowing users to examine the data "behind" the chart.

 The parent Chart Canvas element must have an ID attribute value in order to use the Chart Drill To element with it.

As shown above, when this element is being used, clicking a rectangle displays a list of columns. Selecting a column re-draws the chart so that only the data representing the clicked data is shown.

After drilling to a column, the user can click a button to "drill back", as shown above. It's also possible to continue drilling further down into the data (assuming the elements are configured for it). For example, we could click on the Germany rectangle next and then select City to drill down to the cities with customers who bought the selected product in that country.

 Chart Canvas Charts that use the Chart Drill To element can only have a single Series.

The Drill Back button only appears when the mouse cursor is hovered over the upper right-hand corner of the chart.  

As shown above, the Chart Drill To element drills into grouped data, so the datalayer used beneath the Chart Canvas Chart or Series element must be grouped using a Group Filter or Sql Group element. The example datalayer has been grouped on the CategoryName column and Keep Grouped Rows = True. The Series itself has been configured so that its Label Data Column = CategoryName and its Size Data Column = avgOrderValue (the Group Aggregate Column that averages the order values). Its Color Data Column = cntOrders (the Group Aggregate Column that counts the orders).  

Next, a Chart Drill To element has been added beneath the Series element, as shown above. Required child Drill To Column elements have also been added; they define the columns the user can select to drill into. They should be added and configured for columns that can be reasonably grouped, such as text-type columns with a limited number of unique values and date-type columns.

 You must also configure a Drill To Column element for the column that's specified as the chart's Label Data Column, in this example the CategoryName column.

The Column Header attribute specifies the text that will appear in the Drill to Column drop-down list options. The vertical order of the drop-down list options will match the vertical order of the Drill To Column elements in the definition. Year, Quarter, and Month options will be added automatically for Drill To Columns with Data Type = Date. You do not need to add any filter or additional grouping elements to achieve the results shown in the example above.

The Drill Back button displayed on the chart after drilling has occurred can be styled using the Drill Back Button Style element.

Back to top

Using Action Elements

Action elements initiate processing of a report or process task definition, redirection to a link, or other processing when a data point in the series is clicked.

In the example above, an Action.Report element has been added as a child of the Series, along with its Target.Report and Link Parameters child elements. To reference chart data in parameters, use the @Chart token, as shown above.

A variety of Action elements are available for use with the Series, including Action.Link, Action.Process, and Action.Refresh Element. Additional Action elements will be added in future releases.

Action elements can be also used beneath the Heatmap Group element to provide drill-down and drill-through functionality when group titles are clicked.

Back to top

Using the Refresh Series Timer

The Refresh Series Timer, added as a Series child element, updates charts automatically, based on a time interval. When the interval is reached, a request is sent back to the web server for updated data. Series are updated with a smooth animation.  

The Refresh Interval attribute specifies the number of seconds to wait before refreshing the series data. A value is required and must be an integer greater than 0.

Refresh Mode

Series may be refreshed in two ways: either all of the data is refreshed with each request, or the series data automatically slides to the left one data interval per refresh. The refresh mode is selected in the Chart X Axis element's Axis Type attribute. When the Axis Type is not set to DateTimeLinear, all of the data will be refreshed.

When the Axis Type value is DateTimeLinear, newer values are added to the right side of the chart, previous values slide left, and older values disappear as they reach the left edge of the chart. In this case, the Refresh Series Timer element's Time Span attribute is used to specify the age of the data included. This value must be in hh:mm:ss format (for example "00:02:00" for two minutes) and must be larger than the Refresh Interval attribute value.

When a Time Span attribute is set, the series' datalayer can make use of a special timestamp token, @Chart.rdTimeSpanStart~, in a query to retrieve just the rows necessary to update the chart. On the initial request, this token returns the current time minus the Time Span value. For subsequent refreshes, when Axis Type = DateTimeLinear and the X-axis will be sliding, the token returns the last time the chart was updated, so only the newest rows are retrieved. Here's an MS SQL Server query example:

    SELECT * FROM MyTable WHERE UpdateTime BETWEEN '@Chart.rdTimeSpanStart~' AND '@Function.DateTime~'
For best performance, avoid setting a very short refresh interval if a very large number of users will be displaying the report.

Back to top