The functionality that comes with Flotr can be easily extended with the Flotr Event hooks. You can observe several events. On this page I’ll explain how to take advantage of the events fired by Flotr.

Flotr Project Page » Flotr Documentation » Flotr Event Hooks

The Events

Prototype only supports namespaced custom events. This means that when you want to fire a non-native event, the event name must be prepended with <namespace>:. I wrote a beginner article about events in Prototype, so if you don’t understand this ‘event’ thing, just read ‘Firing Custom Events With The Prototype Javascript Framework‘. For Flotr I’m using the flotr namespace. So events fired by Flotr look like flotr:eventname:

• flotr:click → Fired when someone clicks the graph.
• flotr:mousemove → Fired when someone moves the mouse over the graph.
• flotr:select → Fired when someone has selected a portion of the graph.
• flotr:hit → Fired when mouse tracking points at a value from a series.

Some of these events also pass information with the fired event. For example, the flotr:click event passes the x and y coordinates of the click to the event handler. I’ll dive into this later on. First I’ll show how to observe/listen to the events fired by Flotr.

Observing the events

All events fired by Flotr are fired through the container element. The container element is the first argument of the Flotr.draw() function. This element eventually will contain all generated content like the canvas elements, axis and legend. Firing the events through the container element is very convenient. For example, we have a graph with zooming functionality (flotr:select event is observed on the container element). One selects a portion of the graph. Then the flotr:select is fired, and a new graph is drawn in the container element. The newly drawn graph also has zooming support and thereby it fires the flotr:select through the container element. But we’re still observing that element for the select event, so we don’t have to add a new observer for the select event. For a better understanding, go to the Mouse Zoom Support Example.

To give you a quick example of how to observe an event fired by Flotr:

// Observe the 'flotr:click' event.
$('container').observe('flotr:click', function(evt){
	// Get the click coordinates passed as event memo.
	var pos = evt.memo[0];
	alert('You selected x=' + pos.x + ', y=' + pos.y );
});

Note: Prototype encapsulates data from custom events in the Event.memo property. So Event.memo is the place to access the passed data.

Encapsulated data

flotr:click

The memo passed with Flotr click event:

[{x: numerical value, y: numerical value}]

flotr:mousemove

The memo passed with Flotr mousemove event is an Array that contains the ‘native mousemove’ Event object and an object with the x and y coordinates of the mouse.

[event, {x: numerical value, y: numerical value}]

flotr:select

The memo passed with Flotr select event is an object with four properties. These properties are the corner coordinates of the selected area.

[{
	x1: numerical value,
	y1: numerical value,
	x2: numerical value,
	y2: numerical value
}]

flotr:hit

The memo passed with Flotr hit event is an object with four properties:

[{
	dist: numerical value, // => the distance between the mouse and the point
	mouse: options object, // => holds the mouse options for the series of the point
	x: numerical value, // => x-value of the point
	y: numerical value // => y-value of the point
}]