Annotations are user-defined objects or shapes drawn on a chart. Annotations are often required to make interpretation of the chart easy for the end user. This section will teach you how to create different shapes, images, and text annotations for use with your chart.
Annotations as part of FusionCharts Suite XT are defined inside the annotations object. This object has an array of groups, with each group element having a unique id. The groups object contains an array of items, each item contains information on one specific annotation in the chart. Having annotations organised in groups is useful when manipulating multiple annotations at once through API calls.
Shown below is a code snippet showing a the structure of a simple annotations object.
"annotations": {
"groups": [
{
"id": "custom-group-1",
"items": [
{
// Item definition goes here
},
{
// Item definition goes here
},
]
},
{
"id": "custom-group-2",
"items": [
{
// Item definition goes here
},
{
// Item definition goes here
},
]
},
]
}
Using shapes in an annotation
Line Annotation
The simplest type of annotation is a line shaped annotation. The chart shown below has a simple dashed line and a label that highlights the point with the highest value over the week
The attributes used to customize the annotation are:
| Name | Description |
|---|---|
type |
If set to line, it renders a rectangle annotation. |
x |
It specifies the starting x-coordinate for the annotation. This x co-ordinate is relative to the x co-ordinate of the annotation group in which the annotation is placed. |
y |
It specifies the starting y-coordinate for the annotation. This y co-ordinate is relative to the y co-ordinate of the annotation group in which the annotation is placed. |
toX |
It specifies the ending x-coordinate for the annotation. This x co-ordinate is relative to the x co-ordinate of the annotation group in which the annotation is placed. |
toY |
It specifies the ending y-coordinate for the annotation. This y co-ordinate is relative to the y co-ordinate of the annotation group in which the annotation is placed. |
thickness |
It specifies the thickness of the line annotation. |
color |
It specifies the hex code for the color that will be used to render the line annotation. |
dashed |
It specifies if the line must be dashed or not. |
alpha |
It specifies the transparency for the annotation. |
The data structure of this annotation is shown here
Circle Annotation
The same annotation as shown above can be drawn using a circle that shows the highest value for the week. The chart looks like this
Given below is the list of attributes used to draw and configure a circle annotation:
| Attribute | Description |
|---|---|
type |
If set to circle, it renders a circle annotation. |
x |
It specifies the center x-coordinate for the annotation. This x co-ordinate is relative to the x co-ordinate of the annotation group in which the annotation is placed. |
y |
It specifies the center y-coordinate for the annotation. This y co-ordinate is relative to the y co-ordinate of the annotation group in which the annotation is placed. |
radius |
It specifies the radius of the circle. |
yRadius |
if specifies the y-radius of the circle that allows you to stretch or compress the annotation vertically. |
color |
It specifies the hex code for the color that will be used to render the circle annotation. |
alpha |
It specifies the transparency for the annotation. |
startAngle |
It specifies the starting angle for the circle annotation. |
endAngle |
It specifies the ending angle for the circle annotation. |
The data structure of this annotation is shown here
Using images in an annotation
You can specify the url to an image instead of a shape. Shown below is an example where images are used for the annotations
Given below is the list of attributes used to configure an image annotation:
| Attribute | Description |
|---|---|
| type | If set to image, it renders an image annotation. |
| x | It specifies the center x-coordinate for the annotation. This x coordinate is relative to the x coordinate of the annotation group in which the annotation is placed. |
| y | It specifies the center y-coordinate for the annotation. This y coordinate is relative to the y coordinate of the annotation group in which the annotation is placed. |
| url | It specifies the relative path of the image to be used as annotation. |
The data structure of this annotation is shown here
Image scaling
It may be required at times to scale images based on chart specific requirements, in some cases you may want to keep one image to scale while scaling up or down other images based on the data being shown.
Shown here is an example where the images are scaled
Given below is a brief description of the attributes used to scaling in an image annotation
| Attribute | Description |
|---|---|
| xScale | It specifies the percentage according to which the width of the image is scaled. |
| yScale | It specifies the percentage according to which the height of the image is scaled. |
The data structure used in the chart above to configure scaling of annotations is as follows:
Using text in an annotation
Shown here is a simple annotation with some text in a spline chart
These are the attributes that help customize annotation text:
| Attribute | Description |
|---|---|
| type | If set to text, it renders a text annotation. |
| x | It specifies the center x-coordinate for the annotation. This x coordinate is relative to the x coordinate of the annotation group in which the annotation is placed. |
| y | It specifies the center y-coordinate for the annotation. This y coordinate is relative to the y coordinate of the annotation group in which the annotation is placed. |
| label | It specifies the text to render as the annotation. |
| color | It specifies the hex code of the color that will be used to render the text annotation. |