Positioning Annotations Using Macros
Prerequisites
This article discusses positioning annotations at runtime using macros.
It describes:
-
Dynamic positioning using macros with respect to the canvas, the dataset, and the axes
-
Annotation Macros for positioning with respect to other chart elements
Annotations can also be positioned statically in the chart constructor.
Annotation Macros
Annotation macros are predefined variables used to dynamically position individual annotation items. Macros assume values at run-time and can be used with all annotation positioning attributes to position annotations relative to chart/gauge elements, like the caption, legend, and so on. For example, for an annotation item, if you set "x": "$captionStartX"”", x will be assigned the value of the starting x coordinate of the chart caption.
You can use any number of macros as variables with the positioning attributes. Using the + or - operators, you can add or subtract the macro values from each other or from a fixed number. For example, for an annotation item, assume that you set "x": "$canvasStartX + $chartLeftMargin + 2". The starting x coordinate of the item will now be set to a value that is the starting x coordinate of the chart canvas, the chart’s left margin, and a fixed two pixels added to together.
You can use only the + or - operators to create a macro expression. There should be 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.
When a chart or a gauge is resized, the values provided by macros are not scaled. Instead, they are replaced 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 when the chart is dynamically resized. To avoid this, prefix the number with the $ symbol. For example, the value 10 in the expression $chartStartY + $10 is NOT scaled when you dynamically resize the chart.
Dynamic Positioning using Macros
Annotations can be positioned dynamically with respect to the chart itself and chart elements like the legend, caption, canvas, axes, as well as the datasets.
Positioning Annotations with Respect to the Canvas
A spline chart configured to position annotations with respect to the chart canvas is shown below:
In the chart above, the annotation items (a rectangle and a text label) showing the total footfall at Bakersfield Central are positioned at the top-right corner of the canvas. The values of the attributes x, y,toX, and toY are specified with respect to the canvas start and end position, using annotation macros.
The list of canvas-related macros is given below:
| Macro Name | Usage |
|---|---|
|
For charts that have a canvas (primarily, cartesian charts), these macros are used to position annotations with respect to the canvas. |
The data structure needed to render the above chart is given below:
{
"chart": {
"caption": "Bakersfield Central - Total footfalls",
"subCaption": "Last week",
"xAxisName": "Day",
"yAxisName": "No. of Visitors",
"showValues": "0",
"showBorder": "1",
"showTooltip": "0",
"formatNumberScale": "0",
"theme": "fint"
},
"annotations": {
"origw": "400",
"origh": "300",
"autoscale": "1",
"groups": [
{
"items": [
{
"id": "dyn-labelBG",
"type": "rectangle",
"radius": "3",
"x": "$canvasEndX - 100",
"y": "$canvasStartY",
"tox": "$canvasEndX",
"toy": "$canvasStartY + 30",
"color": "#0075c2",
"alpha": "70"
},
{
"id": "dyn-label",
"type": "text",
"fillcolor": "#ffffff",
"fontsize": "10",
"x": "$canvasEndX - 50",
"y": "$canvasStartY + 15",
"text": ""
}
]
}
]
},
"data": [
{
"label": "Mon",
"value": "15123"
},
{
"label": "Tue",
"value": "14233"
},
{
"label": "Wed",
"value": "25507"
},
{
"label": "Thu",
"value": "9110"
},
{
"label": "Fri",
"value": "15529"
},
{
"label": "Sat",
"value": "20803"
},
{
"label": "Sun",
"value": "19202"
}
]
}Positioning Annotations with Respect to Datasets
A spline chart configured to position annotations with respect to datasets is shown below:
In the chart above, the annotation items (the horizontal dashed line, a text label on a rectangle at extreme left of the dashed line, and the label with the store name and the total number of visitors on the extreme right side of the line) are dynamically positioned such that they appear when you hover the mouse pointer over the corresponding anchor. This is done by specifying values for the x, y,tox, and toy` attributes with respect to the dataset position, using annotation macros.
A brief description of the sub-token macros used to position annotations with respect to datasets is given below:
| Macro Name | Sub Tokens Applicable | Description | Notes |
|---|---|---|---|
$dataset |
dataset_index [separator] set [separator] set_index [separator] position_key |
Lets you add the position information of the plots in a dataset to the annotation. |
Possible position_key values are X, Y, STARTX, STARTY, ENDX, ENDY, CENTERX, CENTERY. For example, to position a rectangle above the second column in a column chart, the possible values could be: |
The data structure to render the above chart is given below::
{
"chart": {
"caption": "Number of visitors last week",
"subCaption": "Bakersfield Central vs Los Angeles Topanga",
"xAxisName": "Day",
"yAxisName": "No. of Visitors",
"theme": "fint",
"animation": "0",
"showValues": "0",
"showTooltip": "0"
},
"categories": [
{
"category": [
{
"label": "Mon"
},
{
"label": "Tue"
},
{
"label": "Wed"
},
{
"vline": "true",
"lineposition": "0",
"color": "#0075c2",
"labelHAlign": "right",
"labelPosition": "0",
"label": "National holiday"
},
{
"label": "Thu"
},
{
"label": "Fri"
},
{
"label": "Sat"
},
{
"label": "Sun"
}
]
}
],
"annotations": {
"groups": [
{
"id": "ds1tips",
"items": [
{
"id": "indicator-line",
"type": "line",
"dashed": "1"
},
{
"id": "tip1_1",
"type": "rectangle",
"visible": "0",
"fillcolor": "#0075c2",
"x": "$dataset.0.set.0.x + 5",
"y": "$dataset.0.set.0.y - 30",
"tox": "$dataset.0.set.0.x + 80",
"toy": "$dataset.0.set.0.y - 10"
}
]
},
{
"id": "dyn-label-grp",
"items": [
{
"id": "dyn-label-bg",
"type": "rectangle",
"radius": "3"
},
{
"id": "dyn-label",
"type": "text",
"fillcolor": "#ffffff",
"fontsize": "11",
"bold": "1"
},
{
"id": "dyn-detail-label",
"type": "text",
"align": "right",
"x": "$canvasendx",
"bgcolor": "#ffffff"
}
]
}
]
},
"dataset": [
{
"seriesname": "Bakersfield Central",
"data": [
{
"value": "15123"
},
{
"value": "14233"
},
{
"value": "25507"
},
{
"value": "9110"
},
{
"value": "15529"
},
{
"value": "20803"
},
{
"value": "19202"
}
]
},
{
"seriesname": "Los Angeles Topanga",
"data": [
{
"value": "13400"
},
{
"value": "12800"
},
{
"value": "22800"
},
{
"value": "12400"
},
{
"value": "15800"
},
{
"value": "19800"
},
{
"value": "21800"
}
]
}
]
}Positioning Annotations with Respect to the Axes
A spline chart with three rectangle and three text annotations positioned with respect to the y-axis is shown below:
The annotation items, showing the low, moderate, and high footfall ranges, are dynamically positioned over the y-axis using annotation sub-token macros.
A brief description of the sub-token macros used to position annotations with respect to the axes is given below:
| Macro Name | Subtokens | Description | Notes |
|---|---|---|---|
$yaxis |
yaxis_index [separator] label [separator] label_index [separator] position_key |
Lets you add the position information of the y-axis labels to the annotation. |
Possible position_key values are X, Y, STARTX, STARTY, ENDX, ENDY, CENTERX, CENTERY. For example, to position a text on the y axis, the possible values could be: |
$xaxis |
xaxis_index [separator] label [separator] label_index [separator] position_key |
Lets you add the position information of the x-axis labels to the annotation. |
Possible position_key values for this macro are the same as that for the For example, to position a text on the x axis, the possible values could be: |
The data structure to render the above chart is given below::
{
"chart": {
"caption": "Bakersfield Central - Total footfalls",
"subCaption": "Last week",
"xAxisName": "Day",
"yAxisName": "No. of Visitors",
"yAxisNamePadding": "20",
"paletteColors": "#008ee4",
"bgAlpha": "0",
"borderAlpha": "20",
"canvasBorderAlpha": "0",
"plotBorderAlpha": "10",
"captionpadding": "20",
"axisLineAlpha": "25",
"divLineAlpha": "10",
"showValues": "0",
"showAlternateHGridColor": "0"
},
"annotations": {
"origw": "400",
"origh": "300",
"autoscale": "1",
"groups": [
{
"items": [
{
"id": "high-labels-zone",
"type": "rectangle",
"x": "$yaxis.0.label.5.startx + 5",
"y": "$yaxis.0.label.5.starty",
"tox": "$yaxis.0.label.3.endx",
"toy": "$yaxis.0.label.3.starty",
"color": "#6baa01",
"alpha": "20"
},
{
"id": "high-label",
"type": "text",
"text": "High",
"x": "$yaxis.0.label.4.startx - 5",
"y": "$yaxis.0.label.4.starty",
"rotateText": "1",
"color": "#6baa01"
},
{
"id": "moderate-labels-zone",
"type": "rectangle",
"x": "$yaxis.0.label.3.startx + 5",
"y": "$yaxis.0.label.3.starty",
"tox": "$yaxis.0.label.2.endx",
"toy": "$yaxis.0.label.1.starty",
"color": "#f8bd19",
"alpha": "20"
},
{
"id": "moderate-label",
"type": "text",
"text": "Moderate",
"x": "$yaxis.0.label.2.startx - 5",
"y": "$yaxis.0.label.2.starty",
"rotateText": "1",
"color": "#f8bd19"
},
{
"id": "low-labels-zone",
"type": "rectangle",
"x": "$yaxis.0.label.1.startx - 3",
"y": "$yaxis.0.label.1.starty",
"tox": "$yaxis.0.label.0.endx",
"toy": "$yaxis.0.label.0.endy",
"color": "#e44a00",
"alpha": "20"
},
{
"id": "low-label",
"type": "text",
"text": "Low",
"x": "$yaxis.0.label.1.startx - 12",
"y": "$yaxis.0.label.0.starty - 5",
"rotateText": "1",
"color": "#e44a00"
}
]
}
]
},
"data": [
{
"label": "Mon",
"value": "15123"
},
{
"label": "Tue",
"value": "14233"
},
{
"label": "Wed",
"value": "25507"
},
{
"vline": "true",
"lineposition": "0",
"color": "#6baa01",
"labelHAlign": "left",
"label": "National holiday"
},
{
"label": "Thu",
"value": "9110"
},
{
"label": "Fri",
"value": "15529"
},
{
"label": "Sat",
"value": "20803"
},
{
"label": "Sun",
"value": "19202"
}
]
}Annotation Macros for Positioning with Respect to Other Chart Elements
Given below is the list and a brief description of the annotation macros used for dynamic positioning with respect to the chart,
| Macro Name | Usage |
|---|---|
$chartStartX, $chartStartY, $chartEndX, $chartEndY, $chartCenterX, $chartCenterY, $chartWidth, $chartHeight |
Define the annotation position attributes - |
$chartTopMargin, $chartBottomMargin, $chartLeftMargin, $chartRightMargin |
Position the annotations with respect to the chart margins.. |
$captionStartX, $captionStartY, $captionEndX, $captionEndY, $captionWidth, $captionHeight, $subCaptionStartX, $subCaptionStartY, $subCaptionEndX, $subCaptionEndY, $subCaptionWidth, $subCaptionHeight |
Position the annotation relative to the chart caption and sub-caption. |
$legendStartX, $legendStartY, $legendEndX, $legendEndY, $legendWidth, $legendHeight |
Position annotations around a legend. These macros are applicable to cartesian charts. |
$gaugeStartX, $gaugeStartY, $gaugeEndX, $gaugeEndY, $gaugeCenterX, $gaugeCenterY |
Position annotations around gauges. |
$gaugeStartAngle, $gaugeEndAngle |
Position annotations with respect to the start angle and end angle of an angular gauge. |
$gaugeRadius |
Position annotations with respect to the radius of a bulb gauge. |
$plotWidth |
Position annotations with respect to the width of the entire funnel or pyramid plot. |
$plotSemiWidth |
Position annotations with respect to half-width of the entire funnel or pyramid plot. |