Demos

Beginner's Guide

Charts / Gauges / Maps Guide

Customizing Charts

API

Integrating With Your Stack

Help

Loading

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

Top