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
$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