Interaction

Wiki ▸ API Reference ▸ Interaction

Interaction

Polychart.js uses an event-based model for interaction, coupled with a flexible way of animating an existing chart to a new state.

Adding Handlers to Charts

chart.addHandler(fn)

Add an event handler to respond to one or more events. The handler functions are called whenever an event occurs -- i.e. when User interacts with the chart. The parameter fn should either be a function, or an object with a method handle that serves as the event handler.

An event handler is called when an event of any type occurs, and it is up to the event handler itself to determine the correct behaviour during each event. This is for several reasons:

1. Interesting handlers tend to respond to multiple events
2. Interesting handlers tend to be stateful

Handler Function Parameters

The handler functions are called with the following four parameters.

type

Type

String

The type of event that occured, a string, one of the events types listed below

• mover - User moused over on a geometric object on the graph.
• mout - User moused out of a geometric object on the graph.
• click - User clicked on a geometric object on the graph.
• guide-click - User clicked on a legend element.
• select - User dragged and selected a range of data points on the graph.
• reset - User clicked on an empty point in the graph panel.
• data - A Polychart.js data used by one of the layers of the graph was updated.

obj

The Raphael object with which the user interacted with, or on which the event occured. One can interact with this object programmatically, or obtain a representation of the subset of data portrayed by this object through the attribute obj.evtData. This object uses filtering notation to describe a the subset of the data represented by the Raphael object. It can be used to change filtering or other specification on the current or other charts.

event

The JavaScript event that was triggered.

chart.

The chart object where the event was triggered. A specification of the chartis at chart.spec. This specification may be formatted slightly different from the original specification that was passed to the graph.

Built-in Interaction Functions

There are several built-in interaction handlers, some of which are automatically attached to charts.

polyjs.handler.tooltip()

Attaches tooltip to charts. Tooltip text can be changed using the aesthetic tooltip.

polyjs.handler.zoom()

Allow users to select an area on the chart to zoom, and click the chart background to reset.

Parameters:

• init_spec: the initial specification of the chart
• zoomOptions: an associate array with two attributes, x, and y, both of which have boolean values. If zoomOptions.x is set to true, then zooming is enabled for the x-axis. This is similar for zoomOptions.y. By default both are set to true.

polyjs.handler.drilldown() [BETA]

TODO: WRITE DOCUMENTATION