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