Image Maps, Hot Spots and CDML Tooltips

A hot spot is a region on an image that can generate mouse events and can have tooltip. For example, on a bar chart, each bar can be a hot spot. The bar can then generate mouse click and other mouse events, and can pop up a tooltip box when the mouse hovers on it.

HTML image maps are a standard way to define hot spots. It defines the hot spot regions and their associate parameters and tooltips. ChartDirector can generate HTML image maps for the charts by using BaseChart.getHTMLImageMap and other similar methods. Many of the examples that come with ChartDirector use this method to configure tooltips for the charts.

Since HTML is an open standard, you can append custom image map entries to define custom hot spots on the chart. For example, if you include your company logo on the chart, you may define a hot spot for the logo to make it clickable.

Although HTML image map comes from web technology, ChartDirector desktop controls, such as WinChartViewer and WPFChartViewer support it as well.

The most common usage of image maps is to define tooltips for the chart objects.

In HTML image maps, tooltips are configured with the "title" attributes. For example, in BaseChart.getHTMLImageMap, the attribute title='{xLabel}: {value}' will configure the tooltip to display the x-axis label associated with the hot spot, followed by a colon and a space, and after that the data value associated with the hot spot.

By default, the tooltip will be displayed using the default tooltip mechanism of the programming framework. For a web application, it will be displayed using the tooltip mechanism provided by the browser. For a desktop application, it will be provided by the desktop GUI framework. Typically, the tooltip will be a small box with a line of text and the style is not configurable.

ChartDirector also supports enhanced CDML tooltips with rich formatting. The tooltip will be rendered by ChartDirector directly. It can include multiple fonts, colors, images, icons or even another chart, and can be semi-transparent. Unlikely the default tooltip which appears only when the mouse hovers on the hot spot for a short time, the CDML tooltip pops up instantaneously when the mouse enters the hot spot and will follow the mouse as it moves. The CDML Tooltips sample code contains a few examples of using CDML tooltips.

For desktop applications, CDML tooltips can be enabled by starting the tooltip with the <*cdml*> tag. The tooltip can them be formatted by using CDML. A simple example is:

<*cdml*><*font=bold,color=0000FF*>{xLabel}:<*/font*>; {value}

When displaying the tooltip, ChartDirector will substitute the <*cdml*> tag with the following CDML, which represents a container with white background, grey border, rounded corners and charcoal grey font color.

<*block,bgColor=F0F0F0,edgeColor=808080,margin=5,roundedCorners=3*><*font,color=222222*>

To customize the container, you may use WinChartViewer.CDMLToolTipPrefix or WPFChartViewer.CDMLToolTipPrefix to configure an alternative container. You can also omit the <*cdml*> tag. In this case, the tooltip should start with a CDML tag that defines its own container. This allows different tooltips to have different container styles. ChartDirector will still consider the tooltip to be a CDML tooltip as long as it starts with a CDML tag.

For web applications, CDML tooltips can be enabled by starting the tooltip with the <*cdml*> tag. The tooltip can them be formatted by using modified HTML, which is the same as HTML with the "<" and ">" changed to "<*" and "*>". A simple example is:

<*cdml*><*b*>{label}:<*/b*> {value}

For backwards compatibility, in tooltips, the "<" and ">" characters are treated as normal tooltip text, not HTML tags. That's why all HTML tags must be modified to use "<*" and "*>".

The standard CDML tooltip will use a tooltip box with white background, grey border and rounded corners. You can customize the tooltip box style by adding a style attribute or class attribute to the <*cdml*> tag. An example :

<*cdml style="background:#000; color:#fff; padding:3px" *>{label}: {value}

If you add a "class" attribute, you can set the style using an style sheet just similar to styling a normal HTML tag.

Note that to use CDML tooltips, the web page must include the ChartDirector Javascript library "cdjcv.js". On the server side, WebChartViewer or RazorChartViewer must be used to represent the chart on the web page.