ChartDirector Ver 3.1 (PHP Edition Edition)

LegendBox.getHTMLImageMap


Usage

getHTMLImageMap(url[, queryFormat[, extraAttr[, offsetX, offsetY ]]])

Description

Generate an HTML image map for the legend box.

This method should be called only after creating the chart image (eg. using BaseChart.makeChart, BaseChart.makeChart2 or BaseChart.makeSession). The image map cannot be determined without creating the chart image first.

This method accepts a URL as its argument. When generating an image map, it appends query parameters to the URL to indicate which legend entry the user has clicked.

The following is an example image map generated for a legend box with 3 entries.

<area shape="rect" coords="310,20,375,33" href='test.asp?dataSet=0&dataSetName=Web'>
<area shape="rect" coords="310,36,377,49" href='test.asp?dataSet=1&dataSetName=Email'>
<area shape="rect" coords="310,52,377,65" href='test.asp?dataSet=2&dataSetName=FTP'>

The image map consists of multiple <area> tags, one for each legend entry. In the "href" attributes, query parameters are appended to the URL to provide information on the entry clicked.

The image map produces by ChartDirector does not include the <map> and </map> tag. This is intentional so that you can add additional custom <area> tags to the image map.

The format of the appended URL parameters is determined using the queryFormat argument, which by default is:

dataSet={dataSet}&dataSetName={dataSetName}

The texts in curly brackets (i.e. {dataSet}, {dataSetName}) will be replaced by the actual values when generating the image map. For example, {dataSetName} will be replaced by the name of the data set.

Please refer to Parameter Substitution and Formatting on all available parameters and how to format them.

In addition to customizing the query parameters, ChartDirector supports additional HTML attributes in the <area> tags using the extraAttr argument.

For example, the following extraAttr will add an "alt" HTML attribute to every <area> tag. The "alt" attribute will be displayed as "tool tip" when the mouse moves over the image map.

alt='Click me for details on {dataSetName}'

Another common usage of the extraAttr argument is to add "onmouseover" and "onmouseout" HTML attributes to handle user interaction using Javascript on the browser.

Arguments

ArgumentDefaultDescription
url(Mandatory)The URL to be used in the "href" attribute of the image map. Parameter substitution and formatting is supported. If no href attribute is needed (e.g. the image map is for onmouseover events only), use an empty string as the URL.
queryFormat""A text string representing the template of the query parameters to be appended to the URL. Parameter substitution and formatting is supported. An empty string means the default query parameters will be used (see table above). To disable query parameters, use a space chartacter as the queryFormat.
extraAttr""A text string to specify additional attributes to add to the <area> tag. Parameter substitution and formatting is supported.
offsetX0An offset to be added to all x coordinates in the image map. This is useful if the current image will be shifted and inserted into another image. In this case, the image map will need to be shifted by the same offset.
offsetY0An offset to be added to all y coordinates in the image map. See offsetX above for description.

Return Value

A text string containing the image map generated.