Annotator

This tutorial shows how we can use Annotator tool that comes with the Exporting plugin.

About Annotator

Annotator is a standalone control that enables users to add visual annotations to the charts.

Under the hood it's just a wrapper for an amazing marker.js 2 library.

Annotator is equipped to automatically load marker.js so you do not need any additional downloads or any dependencies to install.

Loading

Annotator comes with the Exporting plugin, so if you are using other plugin's features, nothing needs to be loaded additionally.

If you are planning on using Annotator alone, you will need to load Exporting plugin.

You can import those in your TypeScript / ES6 application as JavaScript modules:

import * as am5exporting from "@amcharts/amcharts5/plugins/exporting";

For vanilla JavaScript applications and web pages, you can use "script" version:

<script src="https://cdn.amcharts.com/lib/5/plugins/exporting.js"></script>

MORE INFOFor more information on installing amCharts 5 as well as loading modules refer to our "Getting started" tutorial.

Enabling

Annotator is instantiated just like any other object in amCharts 5: by calling new() method of its class, passing in root element and settings object.

let annotator = am5plugins_exporting.Annotator.new(root, {});
var annotator = am5plugins_exporting.Annotator.new(root, {});

Invoking

Via API

Annotator instance contains several methods that we can use:

MethodComment
open()Triggers annotation mode on the chart. This will display UI toolbars and disable all interactions on the chart itself.
close()Exists from annotation mode. All annotations remain visible on the chart.
toggle()Toggles annotation mode between on and off. If annotations have been modified, the changes will be saved.
cancel()Exits from annotation mode. Any changes made during last session of the annotation editing are discarded.
clear()All annotations are removed.
annotator.open();
annotator.open();

Via export menu

We can add Annotator to export menu by manually inserting it into menu items:

let menuitems = exporting.get("menu").get("items");

menuitems.push({
  type: "separator"
});

menuitems.push({
  type: "custom",
  label: "Annotate",
  callback: function() {
    this.close();
    annotator.toggle();
  }
});
var menuitems = exporting.get("menu").get("items");

menuitems.push({
  type: "separator"
});

menuitems.push({
  type: "custom",
  label: "Annotate",
  callback: function() {
    this.close();
    annotator.toggle();
  }
});

Configuring UI

Annotator acts as a wrapper for the actual annotation library - marker.js 2.

To configure UI and functionality of the marker.js you will need to use MarkerArea object.

You can retrieve this object using Annotator's getMarkerArea() method.

Please note that it returns a Promise rather than actual object, so you will need to use await or then() syntax:

annotator.getMarkerArea().then(function(markerArea) {

  // Set colors
  markerArea.settings.defaultColorSet = ["red", "green", "blue"];
  markerArea.settings.defaultColor = "green";

  // Set UI styles
  markerArea.uiStyleSettings.toolboxColor = "#F472B6",
  markerArea.uiStyleSettings.toolboxAccentColor = "#BE185D",

});
annotator.getMarkerArea().then(function(markerArea) {

  // Set colors
  markerArea.settings.defaultColorSet = ["red", "green", "blue"];
  markerArea.settings.defaultColor = "green";

  // Set UI styles
  markerArea.uiStyleSettings.toolboxColor = "#F472B6",
  markerArea.uiStyleSettings.toolboxAccentColor = "#BE185D",

});

For more information on configuring MarkerArea, visit these marker.js docs.

Example

See the Pen
Chart with annotator support
by amCharts team (@amcharts)
on CodePen.0

Pre-loading annotations

In some cases we will want to pre-load previously created annotations, rather then starting afresh.

Getting annotation data

To get current annotations from annotator, we can use its markerState setting.

It's a setting annotator stores raw data in whenever annotation UI is closed.

let annotationData = annotator.get("markerState");
var annotationData = annotator.get("markerState");

Now that we have raw data (which is a JS object), we can serialize and store it the way we see fit, for later retrieval.

Restoring annotation data

For restoring annotation data, we too use markerState.

We can use annotator's set() method, or provide it when initializing the annotator itself:

let annotationData = { ... };

let annotator = am5plugins_exporting.Annotator.new(root, {
  markerState: annotationData
});
var annotationData = { ... };

var annotator = am5plugins_exporting.Annotator.new(root, {
  markerState: annotationData
});

See the Pen
amCharts 5: Annotating Charts
by amCharts team (@amcharts)
on CodePen.0