Using Macros to Dynamically Position Annotations

Annotation macros enable you to position annotation items relative to certain identifiable objects on a chart or a gauge. These macros are applicable on all positional attributes of annotations - x, y, toX, toY, radius, etc. Macros are predefined variables which assume values at run-time. These values are generated dynamically based on the positions of various visual elements of a chart or gauge. For example, setting "x": "$captionStartX" for an annotation item will set the value of x to the starting x-coordinate of chart or gauge caption.

In our previous section advanced-charting-annotations-basics, we had added two annotations to highlight the annual summation of the monthly revenue of Harry's Supermart. The annotations were carefully positioned to be on top-right corner of the chart. Under most circumstances, positioning them would be a visual inference process and would cause unexpected if the chart is resized. Using annotation macros can circumvent these two hindrances. 

"annotations": {
    "groups": [{
        "id": "total-label",
        "items": [{
            "id": "total-label-bg",
            "type": "rectangle",
            "radius": "3",
            "x": "$chartEndX - 120",
            "y": "$captionStartY",
            "toX": "$chartEndX - 20",
            "toY": "$captionStartY + 30",
            "fillColor": "#0075c2",
            "alpha": "70"
        }, {
            "id": "total-label-value",
            "type": "text",
            "fontColor": "#ffffff",
            "fontSize": "10",
            "x": "$chartEndX - 70",
            "y": "$captionStartY + 15",
            "wrapWidth": "90",
            "wrapHeight": "25",
            "text": "Total: $7.5M"
        }]
    }]
}

FusionCharts should load here..

The data used to create the chart above, is as follows:

...

In this example, we vertically positioned the blue rectangle (total-label-bg annotation) with respect to the top of the chart caption by setting the value of its y attribute to $captionStartY. Notice how we used a dollar prefixed variable name instead of a numeric value. Similarly, we set "x": "$chartEndX - 120" to horizontally position the rectangle 120 pixels left to the end of the chart.

One can use any number of macros as variables in the macro-supported attributes of annotations and add or subtract them with each other or fixed number using + or - operators. For example, "x": "$canvasStartX + $chartLeftMargin - 2" on an annotation will set its horizontal position with respect to the starting x-position of the canvas with the value of chart's left margin and a fixed 2 pixels added to it.

List of Macros Supported by Charts and Gauges

Macro Name Usage
$chartStartX, $chartStartY, $chartEndX, $chartEndY, $chartCenterX, $chartCenterY, $chartWidth, $chartHeight These macros allows the annotation position - x, y, toX, toY, etc attributes to be relative to the chart.
$chartTopMargin, $chartBottomMargin, $chartLeftMargin, $chartRightMargin These macros allows the annotation position to calculation to include the chart margins.
$captionStartX, $captionStartY, $captionEndX, $captionEndY, $captionWidth, $captionHeight, $subCaptionStartX, $subCaptionStartY, $subCaptionEndX, $subCaptionEndY, $subCaptionWidth, $subCaptionHeight Annotations can be positioned relative to chart caption and subcaption using these macros.
$canvasStartX, $canvasStartY, $canvasEndX, $canvasEndY, $canvasWidth, $canvasHeight For charts that have a canvas (primarily cartesian charts,) these attributes allow an annotation to be positioned around the canvas.
$legendStartX, $legendStartY, $legendEndX, $legendEndY, $legendWidth, $legendHeight For charts that have a legend (primarily cartesian charts, pie, doughnut, funnel, and pyramid) these attributes allow an annotation to be positioned around the legend.
$gaugeStartX, $gaugeStartY, $gaugeEndX, $gaugeEndY, $gaugeCenterX, $gaugeCenterY Gauge drawing positions.
$gaugeStartAngle, $gaugeEndAngle Start angle and end angle of angular gauge.
$gaugeRadius Radius of a bulb gauge.
$plotWidth Width of the whole Funnel or Pyramid plot
$plotSemiWidth Half-width of the whole Funnel or Pyramid plot

Positioning macros with respect to Dataset and Axes

Macro Name Subtokens Applicable Description Notes
dataset dataset_index [separator] "set" [separator] set_index [separator] position_key Using this macro we can now add the position information of the plots in a dataset to the annotation possible position_key values are STARTX, STARTY, ENDX, ENDY, CENTERX, CENTERY,
yaxis yaxis_index [separator] "label" [separator] label_index [separator] position_key Using this macro we can now add the position information of the yaxis labels to the annotation same possible values for the position_key
xaxis "label" [separator] label_index [separator] position_key Using this macro we can now add the position information of the xaxis labels to the annotation same possible values for position_key

You can only use + or - operators to create a macro expression. You are required to use at least one macro name to create a macro expression. Common mathematical expressions like 30 + 10 - 5, which do not contain a macro, will not work.

While a chart or a gauge is resized, the values provided by macros are not scaled. Rather, these values are re-set with the new values provided by the resized chart. However, the numeric values present in the macro expressions are scaled. For example, the value 10 in the expression $chartStartY + 10 is scaled while using dynamic resizing. If do not want this numeric part to be scaled while using the dynamic resizing feature, you need to prefix the number with $. For example, the value 10 in the expression $chartStartY + $10 is NOT scaled while using dynamic resizing.

Creating Annotations on a Chart or Gauge
Attribute Reference for Annotations