Charting > Special Topics > Annotations on Charts

Annotations on Charts

How to:

An annotation is text, a marker, or both that you can place anywhere on a chart. Multiple annotations can be defined within the annotations array.

Chart annotations support the ability to specify an arbitrary SVG object and define events and tooltips for the SVG object, enabling you to create your own interactive buttons and icons on the chart canvas.

You have to add a separate eventDispatcher object to the request in order to add interactivity to an annotation. For information, see Using JSON to Register Chart Events.

The following shows the properties and default values for annotations: 

"annotations": [
 "position": {
   "x": undefined, 
   "y": undefined, 
   "points": undefined,   
   "parent": "background"
        },
 "marker": {  
   "visible": true,
   "color": "red",
   "size": 8,
   "shape": "circle",  
   "rotation": 0,
   "border": {
     "width": 1,
     "color": "black",
     "dash": ""
           }
     "tooltip": undefined
        },
 "line": {
   			"width": 1,
   			"color": undefined,
   			"dash: ""
    		},
 "label": {
    "visible": false,
    "text": "Annotation Label",
    "font": "10pt Sans-Serif",
    "color": "black",
    "position": "center"  
     }
 },
]

Syntax: How to Place an Annotation on a Chart 

"annotations": [
 "position": {
   "x": x,   "y": y, 
   "points": [{"x":x, "y":y},...},    
   "parent": "string"
     },
 "marker": {  
   "visible": boolean,
   "color": "string",
   "size": number,
   "shape": "string", 
   "position": "string",
   "rotation": number,
   "border": {
     "width": number,
     "color": "string",
     "dash": "string"
         }
     "tooltip": "string"
     },
 "line": {
   			"width": number,
   			"color": "string",
   			"dash": ""
    		},
 "label": {
         "visible": boolean,
         "text": "string",
         "font": "string",
         "color": "string",
         "position": "string"  
     }
 },
   .
   .
   .
]

where:

"position":
Defines the position of the annotation marker.
"x": x

Is the horizontal position for the annotation icon. A synonym for "x" is "left", which measures the horizontal position from the left edge of the frame. You can also use "right", which measures the position from the right edge of the frame.

The default value is undefined. Can be:

  • A number. If the parent chart component is "chart", the number represents a value on a numeric axis. Otherwise, it represents a number of pixels from the left corner of the parent component for "x" or "left", or the right corner for "right".
  • A series and group label for a horizontal chart (in the form {series:n,group:m}), which places the annotation on that series or group. This requires the parent component to be "chart".
  • A percent string (for example, "40%"), which places the annotation at a point the specified percentage horizontally from the left corner of the parent component for "x" or "left", or the right corner for "right".
  • A pixel string (for example, "40px"), which places the annotation at a point that number of pixels horizontally from the left corner of the parent component for "x" or "left", or the right corner for "right".

If you set multiple horizontal position properties, "x" takes precedence over either "right" or "left", and "left" takes precedence over "right".

"y": y

Is the vertical position for the annotation icon. A synonym for "y" is "bottom", which measures the horizontal position from the bottom edge of the frame. You can also use "top", which measures the position from the top edge of the frame.

The default value is undefined. Can be:

  • A number. If the parent chart component is "chart", the number represents a value on a numeric axis. Otherwise, it represents a number of pixels from the bottom edge of the parent component for "y" or "bottom", or the top edge for "top".
  • A series and group label for a vertical chart (in the form {series:n,group:m}), which places the annotation on that series or group. This requires the parent component to be "chart".
  • A percent string (for example, "40%"), which places the annotation at a point the specified percentage vertically from the bottom edge of the parent component for "y" or "bottom", or the top edge for "top".
  • A pixel string (for example, "40px"), which places the annotation at a point that number of pixels vertically from the bottom edge of the parent component for "y" or "bottom", or the top edge for "top".

If you set multiple vertical position properties, "y" takes precedence over either "bottom" or "top", and "bottom" takes precedence over "top".

"points": [{"x":x, "y":y},...]

Is an array of {x, y} points, used to draw arbitrary lines or shapes. Only used if "position": "x" and "y" are undefined.

"parent": "string"

Can be one of the following chart components:

  • "background", which measures the position from the lower left corner of the chart frame and places the annotation behind the chart. This is the default value.
  • "chart", which measures the position from the lower left corner of the chart draw area and places the annotation on the chart.
  • "legend", which measures the position from the lower left corner of the legend area and places the annotation in the legend area.
"marker":
Defines the properties of the annotation marker.
"visible": boolean

Defines whether the annotation marker is visible. Valid values are:

  • true, which makes the annotation marker visible. This is the default value.
  • false, which makes the annotation marker not visible.
"color": "string"

Defines the color for the annotation marker, defined by a color name or numeric specification string, or a gradient defined by a string. The default value is "red".

"size": number

Is the size, in pixels, of the diameter of the annotation marker. This is ignored if "shape" represents an SVG path. The default value is 8.

"shape": "string"

Is a shape for the annotation marker. All valid marker shapes are supported. It can also be an SVG path data string ('d' attribute) that defines the icon shape and size. The default shape is "circle".

For a list of marker shapes, see Series-Specific Properties.

"position": "string"

Defines the marker position relative to data text labels for bullet charts as "top", "bottom", or "middle", Not supported for other types of charts.

"rotation": number

Is a number between 0 and 360 that defines the rotation angle of the marker, in degrees.

"border":
Defines the properties of the marker border.
"width": number

Is a number that defines the width of the border in pixels. The default value is 1.

"color": "string"

Is a color for the marker border defined by a color name or numeric specification string. The default value is "black".

"dash": "string"

Is a string that defines the border dash style. Use a string of numbers that defines the width of a dash followed by the width of the gap between dashes. The default is no dash ("").

tooltip

Is a tooltip for the annotation marker. The default value is undefined.

"line":

Defines the properties of the line drawn if points are specified instead of one x and y value. This is only used if "position" includes multiple points. These properties will speciffy the line style used to connect those points.

"width": number

Is the width of the line in pixels. The default value is 1.

"color": "string"

Is a string that specifies the color of the line. The default value is undefined.

"dash": "string"

Is a string that defines the line dash style. Use a string of numbers that defines the width of a dash followed by the width of the gap between dashes. The default is no dash ("").

"label":
Defines the properties of the annotation label.
"visible": boolean

Defines whether the annotation label is visible. Valid values are:

  • true, which makes the annotation label visible. This is the default value.
  • false, which makes the annotation label not visible.
"text": "string"

Defines the annotation label text. The default value is no label text.

"font": "string"

Defines the annotation label font. The default value is "10pt Sans-Serif".

"color": "string"
Defines the annotation label color defined by a color name or numeric specification string. The default value is "black".
"position": "string"

Defines a position for the annotation label relative to the annotation marker. Valid values are:

  • "top", which places the annotation label above the annotation marker.
  • "bottom", which places the annotation label below the annotation marker.
  • "left", which places the annotation label to the left of the annotation marker.
  • "right", which places the annotation label to the right of the annotation marker.
  • "center", which places the annotation label centered on the annotation marker. This is the default value.

Example: Adding Annotations

The following request specifies two annotations. The first annotation is on the chart component. Its marker is a yellow pirate cross with a black border that is 120 pixels horizontally from the left edge of the x-axis and at the 800K point along the y-axis (which is numeric). The label is positioned below the marker. The second annotation only has a position (representing pixels), so there is no label, and it has the default marker, a red circle that is 8 pixels in size. 

GRAPH FILE WF_RETAIL_LITE
SUM COGS_US GROSS_PROFIT_US 
BY PRODUCT_CATEGORY
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH VBAR
ON GRAPH SET STYLE *
*GRAPH_JS
"annotations": [
	{"position": {"x": "120px", "y": 800000, "parent": "chart"},
		"marker": {"visible": true, "color": "yellow",
			"size": 30, "shape": "piratecross", "rotation": 0,
			"border": {"width": 1, "color": "black", "dash": ""}},
		"label": {"visible": true, "text": "Chart annotation: x: 120px, y: 800K", 
			"font": "14pt Times New Roman", "color": "black", "position": "bottom"}},
		{"position": {"x": 10, "y": 200}}]
*END
ENDSTYLE
END

The output is:

Example: Placing Annotations Relative to a Series and Group

The following request has one annotation, on series 1 and group 1. The y value is at 50% along the y-axis. The marker is a blue triangle. 

GRAPH FILE WF_RETAIL_LITE 
SUM COGS_US GROSS_PROFIT_US REVENUE_US 
BY PRODUCT_CATEGORY 
ON GRAPH PCHOLD FORMAT JSCHART 
ON GRAPH SET LOOKGRAPH VBAR 
ON GRAPH SET STYLE * 
*GRAPH_JS 
"annotations": [{
	"position": {"x": {"series": 1, "group": 1}, 
		"y": "50%", "parent": "chart"},
	"marker": {"visible": true, "color": "blue", 
		"shape": "triangle", "rotation": 0,
		"border": {"width": 1, "color": "black", "dash": ""}},
	"label": {"visible": true, "text": "Series annotation", 
		"font": "10pt Times New Roman", "color": "black", "position": "bottom"}
	}]
*END
ENDSTYLE 
END

The output is:

Example: Placing an Annotation in the Legend Area

The following request places a blue star over the green legend marker in the legend area. 

GRAPH FILE WF_RETAIL_LITE 
SUM COGS_US GROSS_PROFIT_US REVENUE_US 
BY PRODUCT_CATEGORY 
ON GRAPH PCHOLD FORMAT JSCHART 
ON GRAPH SET LOOKGRAPH VBAR 
ON GRAPH SET STYLE * 
*GRAPH_JS 
"legend": {"lineStyle": {"color": "red"}},
"annotations": [{
	"position": {
		"x": "106px", 
		"y": ".14px", 
		"parent": "legend"},
	"marker": {"visible": true, "color": "blue", 
		"shape": "fiveStar", "rotation": 0,
		"border": {"width": 1, "color": "black", "dash": ""}}
	}]
*END
ENDSTYLE 
END

The output is:

Example: Defining an Interactive Annotation for a Chart

The following request creates an annotation that consists of a red icon with a navy dashed border. The event associated with clicking this icon opens the Information Builders home page. The tooltip displays the following text: 

Click to go to informationbuilders.com
SET PAGE-NUM=NOLEAD
SET HTMLENCODE=OFF
SET EMBEDHEADING=ON
GRAPH FILE wf_retail_lite
SUM REVENUE_US
BY PRODUCT_CATEGORY
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH BAR
ON GRAPH SET STYLE *
INCLUDE=IBFS:/FILE/IBI_HTML_DIR/ibi_themes/Warm.sty,$
TYPE=DATA, COLUMN=N1, BUCKET=x-axis, $
TYPE=DATA, COLUMN=N2, BUCKET=y-axis, $
*GRAPH_JS
   "eventDispatcher": {
    	"events": [
    		{
    			// This will add a click  event handler to the annotation
    			"event": "click", object: "annotation", series: 0, url: "http://informationbuilders.com", target: "_blank"
    		}
    	]
    },	
 
annotations:[{
  	"position": {
		    "x": 750,
		    "y": 12,
		"parent": "background"
	},
	"marker": {
    "visible": true,
    "color": "red",
    "border": {"width": 1, "color": "navy", "dash": "2 2"},
	   "shape": "m 12.666667,8.291667 0,-4.375 c 0,-0.319084 -0.26425,-0.583334 -0.583334,-0.583334 l -4.3749997,0 C 7.4715,3.333333 7.2615,3.479167 7.1705,3.688583 7.0795,3.907333 7.125,4.16225 7.29825,4.32675 l 1.3125,1.3125 -4.8673333,4.867333 c -0.2280834,0.228084 -0.2280834,0.592667 0,0.820167 L 4.67325,12.256583 c 0.2280833,0.228084 0.5926667,0.228084 0.8201667,0 L 10.36075,7.38925 l 1.3125,1.3125 c 0.109083,0.118417 0.2555,0.17325 0.410083,0.17325 0.07292,0 0.155167,-0.01808 0.228084,-0.0455 0.209416,-0.091 0.35525,-0.301 0.35525,-0.537833 z M 15,3.625 l 0,8.75 C 15,13.824 13.824,15 12.375,15 l -8.75,0 C 2.176,15 1,13.824 1,12.375 L 1,3.625 C 1,2.176 2.176,1 3.625,1 l 8.75,0 C 13.824,1 15,2.176 15,3.625 Z",
		"tooltip": "Click to go to informationbuilders.com"
	}
}]
*END
 ENDSTYLE
END

The output is shown in the following image.

 WebFOCUS

Feedback