Creating Annotations on a Chart or Gauge

Annotations can be created in two ways - passing annotation details as part of the chart data or programmatically by using annotation specific JavaScript API. You might want to choose the latter in case your annotations are dynamic in nature (i.e. they are dependent on the data of the chart runtime) or if you are just more comfortable using JavaScript. In this article, we will discuss how to create annotations by passing annotation details as part of the data and also discuss how to organise annotations within groups and then move on to using annotations on one of our previously created charts.

Annotations, when passed through chart (or gauge) data, must be included within annotation object at the root of the data JSON (or XML).

{
    "annotations": { }
}

Additional configurations of the root annotations object is explained under the "General Configuration" section in the article Attribute Reference for Annotations.

Annotation Groups

Before we start with annotations, we need to know about annotation groups. As the name suggests, groups help organise annotations in sets. Every annotation must belong to a group. Organising annotation items within groups help in a number of ways:

  1. Groups act as layers and can be configured to be positioned above or below a chart or a gauge.

  2. A group can be shifted and scaled, as such, moving and scaling all annotations within it uniformly.

  3. A group can take a number of annotation item properties that gets inherited by all annotation items within it. This allows easy application of common attributes across all annotation items within a group.

  4. Annotation can also be programmatically operated upon, allowing for easier manipulation of annotations within it.

Annotation groups are encapsulated within the groups array right inside the annotations object of a chart's source data. This array expects multiple groups provided as objects. The following sample data shows the annotations object with the groups array containing two blank groups.

{
    "annotations": {
        "groups": [ { }, { } ]
    }
}

Additional configuration of annotation groups is explained in the article Attribute Reference for Annotations.

Annotation Items

The various shapes (and other objects) that we draw using annotations are called annotation items. Annotation items are added to annotation groups as items array to the groups object.

{
    "annotations": {
        "groups": [{
            items: [ { }, { } ]
        }]
    }
}

To understand more about annotations, let’s add annotations to the example chart that we created in the article Building Your First Few Charts. The chart shows the monthly revenue of Harry's Supermart. As a first step, we will display the total revenue of the year on the top-right corner of the chart.

To show the total revenue on the chart, add the following annotation block to the dataSource of the chart.


"annotations": {
    "groups": [{
        "id": "total-label",
        "items": [{
            "id": "total-label-value",
            "type": "text",
            "fontColor": "#000000",
            "fontSize": "10",
            "x": "430",
            "y": "40",
            "text": "Annual Revenue: $7.5M"
        }]
    }]
}

The above json contains an annotation item of type text containing the summation of monthly revenues. The annotation item is put inside a group (since we had previously learnt that all annotation items must be put within annotation groups. We positioned the text on top-right corner of the chart using the x and y attributes and customized the color and size of text using fontColor and fontSize attribute respectively. As such, annotation items can be customized in multiple ways and we will discuss them later in this article.

Next, we update the chart attributes to align the caption to the left using the "captionAlignment": "left" attribute to give more room to show the annotations on the right and add a bit of extra space between the caption and the canvas using "captionPadding": "25".

With the aforementioned changes done, our chart now displays the total revenue on top right corner.

FusionCharts should load here..

The data used to create the chart above, is as follows:

...

Choosing annotation item type

The type attribute on each annotation item governs what shape the annotation item will have. While adding the total revenue in our previous example, we needed a rectangle (as text background) and a label to show the text. For that, we set the type attribute to rectangle for the first annotation item and the type to text for the second item.

The type attribute accepts one of the following as values:

Shape Type Description
line Setting type to line allows you to draw straight lines between two points. The two points can be specified using x, y as start point and toX, toY as end point.
rectangle As the type name suggests, setting this type allows you to draw a rectangle between two points.
circle Using this as annotation item type, one can draw circles with x, y as centre and a radius attribute to control how large the circle should be drawn. Circles can also be used to draw ovals by specifying the yRadius attribute.
arc An arc type of annotation item is suitable to draw doughnut like shapes since arc accepts an additional innerR attribute (w.r.t. circle) to specify the inner radius of the circle.
polygon When we need to draw shapes like triangle, pentagon, etc, we would need to set the type of an annotation item to polygon and provide a value for the sides attribute. In all other aspects, a polygon behaves like a circle with respect to its positioning and radius.
path This type of annotation item allows you to draw free-from path. Interesting graphic elements such as callouts and arrows can be drawn using the same. When "type": "path" is set, an attribute called path needs to be configured with path commands. The path command accepts standard SVG path format. An example path would be "M 10, 10, L 100, 100". This signifies that we start drawing from (10,10) pixel coordinate using M command and draw a line till (100,100) pixel coordinate as specified by the L command.
text This type of annotation item is used for drawing texts.
image In case one wants to render an image file (jpeg, gif, png, etc) on a chart, an annotation item of this type needs to be used.

With respect to our previous example, we can add an additional rectangular background underneath the total revenue annotation text in order to give it additional emphasis. To do that, we would add another annotation item before the text by replacing the entire annotations block with the following snippet:


"annotations": {
    "groups": [{
        "items": [{
            "id": "total-label-bg",
            "type": "rectangle",
            "radius": "3",
            "x": "380",
            "y": "25",
            "toX": "480",
            "toY": "55",
            "fillColor": "#0075c2",
            "alpha": "70"
        }, {
            "id": "total-label-value",
            "type": "text",
            "fontColor": "#ffffff",
            "fontSize": "10",
            "x": "430",
            "y": "40",
            "wrapWidth": "90",
            "wrapHeight": "15",
            "text": "Total: $7.5M"
        }]
    }]
}

This set of annotations now contains two annotation items within the annotations group, the change being the additional annotation item of type rectangle added before the text label. Adding it before the text ensures that the rectangle is drawn under the text label.

We position the rectangle with similar attributes that we had previously used to position the text and also use additional attributes specifically supported by rectangle annotation item type. In order to make it blend in aesthetically, we customise its fillColor and border radius.

FusionCharts should load here..

The data used to create the chart above, is as follows:

...

Additional configuration of annotation items is explained in the article Attribute Reference for Annotations.