Annotations References

This article covers the exhaustive set of attributes and macros supported by annotations in FusionCharts Suite XT.

General Configuration Attributes

The root annotations object accepts a number of attributes for configuring generic aspects of annotations globally.

These attributes are defined using the code structure shown below:

{
    "annotations": {
        // Define the general configuration attributes here.
    }
}

Attribute Name	Description
`autoScale`	Specifies whether the annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` disables the automatic scaling of the group, setting it to `1` (default) enables it.
`constrainedScale`	Specifies whether annotations will retain their aspect ratio (the height:width ratio) when scaled. Setting this attribute to `0` will disable constrained scaling, setting it to `1` (default) will enable it.
`scaleText`	Specifies whether text annotations in an annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` (default) disables the automatic scaling of text annotations, setting it to `1` enables it.
`scaleImages`	Specifies whether image annotations in an annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` (default) disables the automatic scaling of image annotations, setting it to `1` enables it.
`xShift`	The value of this attribute is added to the x coordinate position value of the final annotation items on the x-axis. In other words, if an annotation is placed at 100 pixels left and the value of `xShift` is set to 50, then the effective value of the x coordinate for the annotation adds up to 150 pixels. When applying scaling, the value of this attribute is included within the scale factor.
`yShift`	Like the `xShift` attribute, this attribute applies to the y-axis.
`grpXShift`	Shifts all annotation groups along the x coordinate. The difference between `xShift` and this attribute is that, during scaling, `xShift` is included within the scale factor whereas `grpXShift` is excluded.
`grpYShift`	Like the `grpXShift` attribute, this attribute applies to the y-axis.
`origW`	Specifies the original width of the chart, in which the annotation renders as intended. It is used as the reference width while automatically scaling annotations, in the event that a chart is resized.
`origH`	Specifies the original height of chart, in which the annotation renders as intended. It is used as the reference height while automatically scaling annotations, in the event that a chart is resized.

Configuration Attributes for Annotation Groups

Annotation groups accept a number of attributes to uniformly configure all annotation items contained within them. Default values for group attributes are inherited from the ones defined as root-level annotation attributes.

These attributes are defined using the code structure shown below:

{
    "annotations": {
        "groups": [{
            //Define the group configuration attributes here.
        }]
    }
}

Attribute Name	Description
`id`	Specifies a unique identification string for the annotation group.
`x`	Specifies the x coordinate of the starting position of the group with respect to the leftmost position (taken as 0) of the chart. If it is also configured individually for the annotation item(s) within the group, then the value of the `x` attribute for the item is set relative to the value of the `x` attribute for the group.
`y`	Specifies the y coordinate of the starting position of the group with respect to the topmost position (taken as 0) of the chart. If it is also configured individually for the annotation item(s) within the group, then the value of the `y` attribute for the item is set relative to the value of the `y` attribute for the group.
`autoScale`	Specifies whether the annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` disables the automatic scaling of the group, setting it to `1` (default) enables it.
`scaleText`	Specifies whether text annotations in an annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` (default) disables the automatic scaling of text annotations, setting it to `1` enables it.
`scaleImages`	Specifies whether image annotations in an annotation group will automatically scale, if chart dimensions change. Setting this attribute to `0` (default) disables the automatic scaling of image annotations, setting it to `1` enables it.
`constrainedScale`	Specifies whether annotations will retain their aspect ratio (the height:width ratio) when scaled. Setting this attribute to `0` will disable constrained scaling, setting it to `1` (default) will enable it.
`showBelow`	Specifies whether the annotation group will overlap the data plots. Setting this attribute to `0` will enable the group to overlap, setting it to `1` (default) will disable it.
`origW`	Specifies the original width of the chart, in which the annotation renders as intended. It is used as the reference width while automatically scaling annotations, in the event that a chart is resized.
`origH`	Specifies the original height of chart, in which the annotation renders as intended. It is used as the reference height while automatically scaling annotations, in the event that a chart is resized.
`xShift`	The value of this attribute is added to the x coordinate position value of the final annotation items on the x-axis. In other words, if an annotation is placed at 100 pixels left and the value of `xShift` is set to 50, then the effective value of the x coordinate for the annotation adds up to 150 pixels. When applying scaling, the value of this attribute is included within the scale factor.
`yShift`	Like the `xShift` attribute, this attribute applies to the y-axis.
`grpXShift`	Shifts all annotation groups along the x coordinate. The difference between `xShift` and this attribute is that, during scaling, `xShift` is included within the scale factor whereas `grpXShift` is excluded.
`grpYShift`	Like the `grpXShift` attribute, this attribute applies to the y-axis.
`alpha`	Specifies the transparency for the group. This attribute takes values between 0 (transparent) and 100 (opaque, default).
`visible`	Specifies the visibility of the group. Setting this value to `0` hides the group, setting it to `1` (default) shows it.
`showShadow`	Specifies whether a shadow effect will be shown for the annotation group. Setting this attribute to `1` shows the effect, setting it `0` (default) does not show the effect.
`color`	Specifies the hex color code for the annotation group.
`font`	Specifies the font family for the text annotation(s) in the annotation group.
`fontSize`	Specifies the font size for the text annotation(s).
`textAlign`	Specifies the horizontal alignment for the text annotation(s).
`textVAlign`	Specifies the vertical alignment for the text annotation(s).
`rotateText`	Specifies whether the text annotation(s) will be rotated. This attribute takes `0` (default), `1`, `left`, and `right` as values.
`wrapText`	Specifies whether words that are too long to fit in a line should be wrapped to the next line. Setting this attribute to `0` disables wrapping of text, setting it to `1` (default) enables it.
`link`	Specifies the URL to which the user will be redirected, if the annotation group is clicked.
`toolText`	Specifies the tooltip for the annotation group.

Configuration Attributes for Annotation Items

These attributes are defined using the code structure shown below:

{
    "annotations": {
        "groups": [{
            "items": [{
                //Define the annotation items configuration attributes here.
            }]
        }]
    }
}

For simplicity, the annotation items configuration attributes are segregated into:

Common attributes (that work for all annotation types)
Ad hoc attributes (that work for only certain annotation types)

Common Attributes

Attribute Name	Description
`id`	Specifies a unique identification for the annotation. This `id` is used to identify and change other properties of the annotation.
`type`	Specifies the type of annotation to be drawn.
`color`	Specifies the hex color code for the annotation. For example, a value of `#6baa01` will draw an annotation in the green color. The default value is `#ff0000`.
`alpha`	Specifies the transparency of the annotation. This attribute takes values between 0 (transparent) and 100 (opaque, default).
`fillColor`	Specifies a list of hex color codes, if the group has to be rendered with a gradient effect. For example, `"fillColor”: "#ffcc66,#2deaff,#a6992a”`. This attribute is not applicable to the line, text, and image annotations.
`fillAlpha`	Specifies the transparency of the colors specified using the `fillColor` attribute. This attribute takes values between 0 (transparent) and 100 (opaque, default). The number of values provided for this attribute should be the same as that for the `fillColor` attribute. In case the number of values is less than the number of colors provided, the last of the comma-separated values is repeated for the remaining colors.
`fillRatio`	Specifies the ratio for distribution for all colors specified as a comma-separated list to the `fillColor` attribute. This attribute takes values between 0 and 100. The number of values provided for this attribute should be the same as that for the `fillColor` attribute. In case the number of ratio values is less than the number of colors provided, the last of the comma-separated values is repeated for the remaining colors. The summation of these values should not exceed 100.
`fillAngle`	For a gradient `fillColor`, it specifies the angle in which the gradient will be drawn. It accepts one value between 0 to 360 in degrees.
`fillPattern`	Specifies whether the gradient fill will be `linear` or `radial` (default for circle and arc annotations).
`showborder`	Specifies whether a border will be shown around the annotation. Setting this attribute to `1` shows the border, setting it to `0` (default) hides it.
`borderColor`	Specifies the hex color code for the annotation border. For example, setting this attribute to `#f8bd19` will show a yellow border around the annotation. This attribute is not applicable to the line annotation.
`borderAlpha`	Specifies the transparency of the annotation border. This attribute takes values between 0 (transparent) and 100 (opaque, default). This attribute is not applicable to the line annotation.
`borderThickness`	Specifies the thickness of the annotation border, in pixels. Default value is 2 pixels. This attribute is not applicable to the line annotation.
`dashed`	Specifies whether the annotation border will be drawn using dashed lines. Setting this attribute to `1` will render the border using dashed lines, setting it to `0` (default) will render it using whole lines. For the line annotation, it renders the annotation itself as a dashed line.
`dashLen`	Specifies the length of each dash, if a dashed border is drawn for the annotation.
`dashGap`	Specifies the gap between each dash, if a dashed border is drawn for the annotation.
`toolText`	Specifies the tooltip for annotation items that is shown when the mouse pointer is hovered over it.
`link`	Specifies the URL to which the user will be redirected, if the annotation item is clicked.
`showShadow`	Specifies whether a shadow effect will be shown for the annotation group. Setting this attribute to `1` shows the effect, setting it `0` (default) does not show the effect.

Ad Hoc Attributes

Line

Attribute Name	Description
`type`	Set this attribute to `line`.
`x`	Specifies the x coordinate of the starting position of the line with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the starting position of the line with respect to the topmost position (taken as zero) of the chart.
`toX`	Specifies the x coordinate of the ending position of the line with respect to the leftmost position (taken as zero) of the chart.
`toY`	Specifies the y coordinate of the ending position of the line with respect to the topmost position (taken as zero) of the chart.
`thickness`	Specifies the thickness of the line, in pixels.

Circle

Attribute Name	Description
`type`	Set this attribute to `circle`.
`x`	Specifies the x coordinate of the center of the circle with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the center of the circle with respect to the topmost position (taken as zero) of the chart.
`radius`	Specifies the radius of the circle, in pixels.
`yRadius`	Specifies the height, in pixels, if you want to draw an oval annotation.
`startAngle`	Specifies the start angle (in degrees), if a circle has to be drawn like a wedge. For example, setting `"startAngle”: "0”` and `”endAngle”: “180”` will draw a semicircle.
`endAngle`	Specifies the end angle (in degrees), if a circle has to be drawn like a wedge.

Arc

Attribute Name	Description
`type`	Set this attribute to `arc`.
`x`	Specifies the x coordinate of the center of the arc with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the center of the circle with respect to the topmost position (taken as zero) of the chart.
`radius`	Specifies the outer radius of the arc, in pixels.
`innerRadius`	Specifies the inner radius of the arc, in pixels.
`startAngle`	Specifies the starting angle of the arc. This attribute takes values between 0 and 360. The default value is 0.
`endAngle`	Specifies the ending angle of the arc. This attribute takes values between 0 and 360. The default value is 360.

Rectangle

Attribute Name	Description
`type`	Set this attribute to `rectangle`.
`x`	Specifies the x coordinate of the starting position of the rectangle with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the starting position of the rectangle with respect to the topmost position (taken as zero) of the chart.
`toX`	Specifies the x coordinate of the ending position of the rectangle with respect to the leftmost position (taken as zero) of the chart.
`toY`	Specifies the y coordinate of the ending position of the rectangle with respect to the topmost position (taken as zero) of the chart.
`radius`	Specifies the radius of the edges of a rectangle, in pixels. This attribute is used when you want to render the annotation as a rounded rectangle.

Polygon

Attribute Name	Description
`type`	Set it to `polygon`.
`sides`	Specifies the number of sides for the polygon. Its value must be greater than 2.
`x`	Specifies the x coordinate of the center of the polygon with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the center of the polygon with respect to the topmost position (taken as zero) of the chart.
`radius`	Specifies the radius of the edges of a polygon, in pixels.

Text

Attribute Name	Description
`type`	Set this attribute to `text`.
`text`	Specifies the text that is to be rendered as the annotation.
`x`	Specifies the x coordinate of the position of the text annotation with respect to the leftmost position (taken as zero) of the chart.
`y`	Specifies the y coordinate of the position of the text annotation with respect to the topmost position (taken as zero) of the chart.
`font`	Specifies the font family for the text annotation.
`fontSize`	Specifies the font size for the text annotation.
`align`	Specifies the horizontal alignment of the text annotation. This attribute takes `left`, `center`, and `right` as values. The default value is `center`.
`vAlign`	Specifies the vertical alignment of the text annotation. This attribute takes `top`, `middle`, and `bottom` as values. The default value is `middle`.
`bold`	Specifies whether the text will be in bold. Setting this attribute to `1` renders the text in bold, setting it to `0` (default) removes the bold formatting.
`italic`	Specifies whether the text will be in italic. Setting this attribute to `1` renders the text in italic, setting it to `0` (default) removes the italic formatting.
`bgColor`	Specifies the hex color code for the text annotation’s background. For example, a value of `#fcfc00` colors the background yellow.
`leftMargin`	Sets a fixed margin, in pixels, to the left of the text.
`rotateText`	Specifies whether the text annotation(s) will be rotated. This attribute takes `0` (default), `1`, `left`, and `right` as values.
`wrap`	Specifies whether text wrapping will be enabled. Setting this attribute to `1` will enable text wrapping, setting it to `0` (default) will disable it.
`wrapWidth`	Specifies the width wrapping dimension for the text. When this width is reached, it will cause the text to break into a new line. The `toX` and `toY` attributes can also be set on text if text wrapping dimensions are provided in absolute pixels from annotation group’s origin coordinates.
`wrapHeight`	Like the `wrapWidth` attribute, this attribute applies to the height occupied by the text. Ellipses are appended to the end of text when text overflows beyond allocated vertical space of `wrapHeight` or `toY` attributes.

Path

Attribute	Description
`type`	Set this attribute to `path`.
`path`	Specifies the path command and accepts standard SVG path format. For example, the path command “M 10, 10, L 100, 100” signifies that we start drawing from the coordinate at (10,10) pixel using M ( Move to) command and draw a line up to the coordinate (100,100) pixel as specified by the L (Line to) command.
`x`	Specifies the x coordinate of the starting position of the path with respect to the leftmost position (taken as 0) of the chart.
`y`	Specifies the y coordinate of the starting position of the path with respect to the topmost position (taken as 0) of the chart.

Images

Attribute	Description
`type`	Set this attribute to `image`.
`url`	Specifies the location of the image file (jpeg, png, or gif) that is to be rendered on the chart. Chart rendering does not pause for the image to load and as such asynchronously draws them as and when they are loaded. In case you need to load them instantaneously, you may considering preloading the images.
`x`	Specifies the x coordinate of the starting position of the image annotation with respect to the leftmost position (taken as 0) of the chart.
`y`	Specifies the y coordinate of the starting position of the image annotation with respect to the topmost position (taken as 0) of the chart.
`xscale`	Specifies the resize value for the image width.
`yscale`	Specifies the resize value for the image height.

Macros Supported for Positioning Annotations in Charts and Gauges

Macro Name	Usage
$chartStartX, $chartStartY, $chartEndX, $chartEndY, $chartCenterX, $chartCenterY, $chartWidth, $chartHeight	Define the annotation position attributes - `x`, `y`, `toX`, `toY`, etc relative to the chart.
$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.
$canvasStartX, $canvasStartY, $canvasEndX, $canvasEndY, $canvasWidth, $canvasHeight	Position annotations with respect to the canvas. These macros are applicable to cartesian charts.
$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.

Sub-token Macros for Positioning with Respect to the Dataset and Axes

Macro Name Sub Tokens Applicable Description Notes

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: x: $dataset.0.set.1.STARTX, y:$dataset.0.set.1.STARTY, tox: $dataset.0.set.1.STARTX+100, toy:$dataset.0.set.1.STARTY-40
$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: x: $yaxis.0.label.1.startx -12, y: $yaxis.0.label.0.starty - 5
$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 `$yaxis` macro. For example, to position a text on the x axis, the possible values could be: x: $xaxis.label.1.startx+2, y: $xaxis.label.0.starty+3

$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:
x: $dataset.0.set.1.STARTX,
y:$dataset.0.set.1.STARTY,
tox: $dataset.0.set.1.STARTX+100,
toy:$dataset.0.set.1.STARTY-40

$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:
x: $yaxis.0.label.1.startx -12,
y: $yaxis.0.label.0.starty - 5

$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 $yaxis macro.

For example, to position a text on the x axis, the possible values could be:
x: $xaxis.label.1.startx+2,
y: $xaxis.label.0.starty+3