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.

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

• JSON
• XML

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:

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.

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

• JSON
• XML

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