PlotJax Helper Object Developer's Guide

Note: this is a preliminary specification subject to change.

To facilitate customization of PlotJax rendering and (especially) interactivity, the PlotJax constructor supports a "Helper" object parameter. The PlotJax Helper object provides methods which are called prior to processing certain types of events:

onlayout - prior to drawing the chart contents, each chart is queried for layout information. The Helper may impose additional behaviors on the layout during this stage.

ondraw - when each chart is requested to draw its contents, the Helper can be called to provide additional processing
onhover - when a hover event occurs on any individual element of a chart (datapoint for most types, wedges for pie charts, bars for barcharts, etc.), the Helper can be called to provide content for a hover tooltip
onclick - when a mouseclick event occurs on any individual element, the Helper can be called to perform event specific processing
oncapture - called for each chart element contained within a capture gesture
onflick - called for each chart element covered by a flick gesture

A base class definition for PlotJaxHelper is specified below:

Constructor

The constructor is entirely application specific, as it is never called from within PlotJax. Note that the Helper must be created prior to creating the PlotJax container. A single Helper may be used for multiple PlotJax containers.

`onload(plotjax, charts, balloon, gesture)`

(Optional) Called after all charts have been loaded into a PlotJax container. This provides the Helper an opportunity to record the individual components prior to any rendering or other interaction.

plotjax is the PlotJax container object
charts is an array of individual charts within the container
balloon is the PLJX_Balloon object used for tooltip popups
gesture is the PLJX_Gesture object used to manage the capture and flick gestures within the container

`onlayout(plotjax, chart)`

(Optional) Called during the layout process for each chart in the container.

`content = ondraw(plotjax, chart, id)`

(Optional) Called during drawing for each element of each chart in the container.

`onhover(plotjax, chart, id)`

(Optional) Called when the mouse enters an individual element of a chart.

plotjax is the container object;
chart is the chart object;
id is a unique element identifier for the datapoint/wedge/bar;

Returns either text content to be inserted into the hover tooltip, or null, in which case the tooltip will not be shown.

`onclick(plotjax, chart, id, x, y)`

(Optional) Called when the mouse is clicked over an individual element of a chart

plotjax is the container object;
chart is the chart object;
id is a unique element identifier for the clicked datapoint/wedge/bar;
x and y are the coordinates of the mouse cursor within the entire canvas

If no onclick is defined, or no Helper is defined, and the chart element has an associated tooltip property, a balloon tooltip will be opened and loaded with the tooltip property content (either static text or loaded via a URL).

`oncapture(plotjax, chart, id)`

(Optional) Called for each chart element that lies inside a capture gesture area.

plotjax is the container object;
chart is the chart object;
id is a unique element identifier for the datapoint/wedge/bar;

If no oncapture is defined, or no Helper is defined, a zoom operation will be applied to the chart element.

`onflick(plotjax, chart, id)`

(Optional) Called for each chart element that is covered by a flick gesture.

plotjax is the container object;
chart is the chart object;
id is a unique element identifier for the datapoint/wedge/bar;

If no onflick is defined, or no Helper is defined, the element is recoverably removed from the chart.

`getBalloonContent(plotjax, chart, id)`

(Optional) Called when a balloon tooltip might be opened.

plotjax is the container object;
chart is the chart object;
id is a unique element identifier for the datapoint/wedge/bar;

The method can retrieve any information it needs to generate the tooltip content using the chart object's accessors.

The returned value must be one of

a string of HTML text, which will be directly inserted into the balloon
a string URL prefixed by "http://", which will be loaded each time the associated balloon is displayed.
null, in which case no balloon will be generated for the datapoint

E.g.,

function myHelper(url) {
	this.baseurl = url;
}

myHelper.prototype.getBalloonContent = function(plotjax, chart, elemid) {
	var datapt = chart.getChartElementValues(elemid);
	return this.baseurl + "plotnum=" + chart.getChartIndex() +
		"&plotkind=" + chart.getPlotKind() + "&x=" + datapt[0] + "&y=" + datapt[1];
}

var tooltipper = new myToolTipper("http://my.domain.com/cgi-bin/charttip.pl?");

var mychart = new PlotJax("mychart", 400, 400, contentJson, tooltipper);

PlotJax Chart Accessors

Each chart object contained within a PlotJax container provides the following accessor methods which can be used by Helper objects to determine a chart's properties:

`getChartId()`

Returns the unique identifier for the chart

`getChartIndex()`

Returns the ordinal index of the chart in the list of charts, starting at zero.

`getPlotKind()`

Returns the kind of plot (see PlotKind)

`getChartElementBBox(id)`

Returns the bounding box for the specified chart element. The bounding box is a 4-tuple consisting of the coordinates of the upper left and lower right corners of the box, relative to the containing canvas area.

`getChartElementShape(id)`

Returns the shape specification for the specified chart element.

`getChartElementIcon(id)`

Returns the icon URL for the specified chart element.

`getChartElementValues(id)`

Returns a list of values associated with the element; the returned list is dependent on the kind of chart; e.g., for a bubble chart, the list is [ x-value, y-value, size-value, intensity-value ].

`getChartElementColor(id)`

Returns the color of the specified chart element.

`setChartElementShape(id)`

Sets the shape specification for the specified chart element.

`setChartElementIcon(id)`

Sets the icon URL for the specified chart element.

`setChartElementColor(id)`

Sets the color of the specified chart element.

`removeChartElement(id)`

Removes the specified chart element from the chart. Once removed, the element cannot be recovered.

`addChartElement(id, properties)`

Adds an element to the chart. properties is an object of the same form as an individual PlotJax.Charts.Data element.