Adding user interactions

One of the most important parts of a data visualization is the ability to allow the user to explore the data themselves and interact with it. An Interaction, as the name suggests, implements a way to interact with a Component. Interactions can be attached and detached from Components like so:

// Attach an interaction to a component
interaction.attachTo(component);

// Detach an interaction from a component
interaction.detachFrom(component);

Plottable ships with a number of Interactions that can be used. In this tutorial, we will look at two of these Interactions: Interactions.Click and Interactions.PanZoom. A full list of Interactions can be found here.

Interactions.Click

A Click interaction allows the user to define a callback function when one clicks on a Component. It exposes the following methods:

// Sets a callback to be called when the Component is clicked
interaction.onClick(function(point) { });

// Removes a callback that would be called when the Component is clicked
interaction.offClick(function(point) { });

Let's see how we can use the click interaction on a Plots.Bar in order to select a particular column in the following example. Try clicking on any of the bars:

We start off by constructing our basic bar plot.

var xScale = new Plottable.Scales.Linear();
var yScale = new Plottable.Scales.Linear();

var data = [];
for (var i = 1; i < 10; i++) { data.push({"x": i, "y": i}); }

var plot = new Plottable.Plots.Bar()
  .x(function(d) { return d.x; }, xScale)
  .y(function(d) { return d.y; }, yScale)
  .addDataset(new Plottable.Dataset(data));

Now, we define our click interaction like so

var interaction = new Plottable.Interactions.Click();

In the above example, we want to highlight the selected bar with a red fill. We define a function that takes in a Point as a parameter. This point can be used with the .entitiesAt method exposed on BarPlot in order to retrieve the Entity object that corresponds to the clicked point. Entities are objects that represent data-backed visual entries inside of a Component, giving us access to the datum that corresponds to the Entity, the position of the entity as a Point, the d3 selection object that the Entity corresponds to, and the parent component for the Entity.

function onClickInteraction(point) {
  // Reset all the colors to blue
  plot.selections().attr("fill", "#5279c7");

  // Retrieve the d3 selection for the clicked point
  var selection = plot.entitiesAt(point)[0].selection;

  // Set the fill for the d3 selection to orange
  selection.attr("fill", "#F99D42");
}

The final step is to set the onClick() callback for this interaction to the function that we have written above and attach it to the plot, which we then render to our target SVG.

interaction.onClick(onClickInteraction);
interaction.attachTo(plot);
plot.renderTo("svg#click");

Now that you understand the structure of an Interaction, and how to set callbacks on it and attach it to Components, you should have a working knowledge of Plottable as a whole. Thanks for sticking through the basic tutorials!

The full code for this example is here:

var xScale = new Plottable.Scales.Linear();
var yScale = new Plottable.Scales.Linear();

var data = [];
for (var i = 1; i < 10; i++) { data.push({"x": i, "y": i}); }

var plot = new Plottable.Plots.Bar()
  .x(function(d) { return d.x; }, xScale)
  .y(function(d) { return d.y; }, yScale)
  .addDataset(new Plottable.Dataset(data));
var interaction = new Plottable.Interactions.Click();

function onClickInteraction(point) {
  plot.selections().attr("fill", "#5279c7");
  var selection = plot.entitiesAt(point)[0].selection;
  selection.attr("fill", "#F99D42");
}

interaction.onClick(onClickInteraction);
interaction.attachTo(plot);

plot.renderTo("svg#example");