Grouping Annotations

Prerequisites:

Annotation groups are a number of annotation items consolidated and configured together as one item. Grouping annotations is useful when there are multiple annotations on a chart and common properties have to be configured for all of them.

This article describes the usefulness of creating and manipulating multiple annotations as a group than as individual items.

Creating Annotation Groups

Assume that you have a spline chart that shows the footfalls for each day of a week. A rectangle and a text annotation are grouped together to show the total number of footfalls.

Take a look at the spline chart shown below:

FusionCharts should load here..

The label that shows the total number of footfalls for the week is created as an annotation group.

To create an annotation group, all you have to do is create each annotation item as an object within the same groupsitems object array.

The code snippet to create the above text and rectangle annotation, as a group, is given below:

…
"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",
            "text": "Total: 119,507",
            "fillcolor": "#ffffff",
            "fontsize": "10",
            "x": "$canvasEndX - 50",
            "y": "$canvasStartY + 15"
        }]
    }]
}
…

When the annotation group is rendered on the chart, annotation items will be layered in the order they are defined. Because you want to position the text annotation above the rectangle annotation, define the rectangle annotation before the text annotation.

When multiple annotations are grouped together, manipulating common functional and cosmetic properties and positioning annotations becomes easy. For example, assume that you had to change the position of the text and rectangle annotation from the spline chart above, you would have to first re-position the rectangle annotation and then re-position the text annotation.

Instead, if you manipulate them as a group, you will only have to change the group’s position.

The attributes that you can use to manipulate annotation groups are given below:

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 all the text annotation(s) in the annotation group.
fontSize Specifies the font size for all the text annotation(s).
textAlign Specifies the horizontal alignment for all the text annotation(s).
textVAlign Specifies the vertical alignment for all 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.
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”.
fillRatio Specifies the fill color ratio for an annotation group, if the group has to be rendered with a gradient effect. This attribute is useful only if you are specifying multiple colors using the fillColor attribute. It is a comma-separated list of numbers that lie between 0 and 100. For example, ”fillRatio”: “25, 25, 50”. 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.

These attributes belong to the annotationsgroups object array.

Manipulating Annotation Groups

Next, take a look at an example that shows how manipulating annotations as a group is easier than manipulating them as individual items.

For the above spline chart, this example will let the user control whether the total number of footfalls will be shown or hidden.

The chart thus rendered looks like this:

FusionCharts should load here..

Selecting the Show total footfall radio button will show the annotation group, selecting the Hide total footfall radio button will hide it.

The complete data structure for this chart is given below:

...