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"
}]
}]
}
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.