Handling Events

This page describes how to listen for and handle events fired by a visualization.

Contents

Overview

Google visualizations can fire events that you can listen for. Events can be triggered by user actions: for example a user clicks on a chart, or can be internal: for example, a timer firing an event every 10 seconds. You can register a Javascript method to be called whenever certain events are fired, possibly with data specific to that event.

Every visualization defines its own events, and the documentation for that visualization should describe when each event is fired, what it means, and how to get back any information associated with the event. This page describes how to register to receive events from a visualization, and how to handle them.

There is one event that any selectable visualization should fire: the select event. However, the behavior and meaning of this event is defined by each visualization.

It is important to note that the Visualization API events are separate and distinct from the standard DOM events.

Registering For and Handling an Event

To register your event handlers, you call google.visualization.events.addListener() with the name of the visualization exposing the event, the string name of the event to listen for, and the name of the function to call when that event is fired. Your function should accept a single parameter that is the event that was fired. This event can have custom information about the event, as described in the visualization documentation.

The following code snippet shows an alert box every time the user clicks on a table row:

// Create a table visualization on your page. 
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Note that this will only register to listen for events for this specific table object; you can only register to receive events from a specific object.

You can also pass in a function definition, as shown here:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Retrieving Event Information

Events generally expose information in two ways: by passing information into the handler function as a parameter; or by adding information to a global object. If and how the event exposes information should be described in the documentation for that visualization. Here is how to retrieve both types of information:

Event information passed to your handler

If the visualization passes data as a parameter to your handling function, you would retrieve it as shown here:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

The parameter passed in to your handler will have a property that should be documented for the visualization. For an example of a visualization that exposes event information this way, see the Table visualization's page event.

Event information passed to a global object

Some events instead change a property of a global object, which you can then request. A common example of that is the "select" event, which is fired when a user selects a part of a visualization. In this case, the code must call getSelection() on the visualization to learn what the current selection is. More information is given on the select event below.

// orgChart is my global orgchart visualization variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');
  

The select Event

As mentioned previously, any visualization that can be selected should fire a "select" event that works in a standard way to let you retrieve the values of the selected item in the visualization. (However, there is no absolute requirement that a visualization behave this way; check the documentation for your visualization).

In general, visualizations that expose the "select" event are designed with the following specifications:

• The select event does not pass any properties or objects to the handler (your function handler should not expect any parameters to be passed to it).
• The visualization should expose the method getSelection(), which returns an array of objects describing the selected data elements. These objects have the properties row and column. row and column are the row and column indexes of the selected item in the DataTable. (Selection events describe the underlying data in the graph, not HTML elements in the visualization.) To get the data of the item selected, you'll have to call DataTable.getValue() or getFormattedValue().
  If both row and column are specified, the selected element is a cell. If only row is specified, the selected element is a row. If only column is specified, the selected element is a column.
• The visualization should expose the method setSelection(selection) to change the selection in the underlying table and select the corresponding data in the visualization. The selection parameter that is an array similar to the getSelection() array, where each element is an object with properties row and column. The row property defines the index of the selected row in the DataTable, and the column property defines the index of the selected column in the DataTable. When this method is called, the visualization should visually indicate what the new selection is. The implementation of setSelection() should not trigger a 'select' event.
  If both row and column are specified, the selected element is a cell. If only row is specified, the selected element is a row. If only column is specified, the selected element is a column.

Some caveats:

• Visualizations might ignore part of the selection. For example a table that can show only selected rows may ignore cell or column elements in their setSelection implementation.)
• Some visualizations might not trigger a 'select' event, and some visualizations may support only entire row selection or entire column selection. The documentation of each visualization defines the events and methods it supports.
• Multiselection is handled differently in different visualizations (some don't even allow it).
• In order to read the selected data, you'll need to call DataTable.getValue() in your handler; the simplest way to enable that is to make the DataTable object global.

The following example pops up an alertbox with the selected table elements, when an element of a table visualization is selected:

Note that the table visualization only fires row selection events; however, the code is generic, and can be used for row, column, and cell selection events.

Here's the handler code for that example:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);
}

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
  function selectHandler() {
    var selection = table.getSelection();
    var message = '';
    for (var i = 0; i < selection.length; i++) {
      var item = selection[i];
      if (item.row != null && item.column != null) {
        var str = data.getFormattedValue(item.row, item.column);
        message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
      } else if (item.row != null) {
        var str = data.getFormattedValue(item.row, 0);
        message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
      } else if (item.column != null) {
        var str = data.getFormattedValue(0, item.column);
        message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
      }
    }
    if (message == '') {
      message = 'nothing';
    }
    alert('You selected ' + message);
  }

Get started quickly with an Interactive Code Sample you can edit and save.

The ready Event

If a visualization is not immediately ready to respond to user interaction or method calls when it returns from the draw() method, it should fire a "ready" event to let the developer know when the visualization is ready to process called methods. (However, there is no requirement that a visualization fire this event; check the visualization's documentation).

In general, visualizations that expose the "ready" event are designed with the following specifications:

• The ready event does not pass any properties to the handler (your function handler should not expect any parameters to be passed to it).
• The visualization should fire the ready event after the visualization is ready for interaction. If the drawing of the visualization is asynchronous, it is important that the event is fired when interaction methods can actually be called, and not just when the draw method ends.
• Adding a listener to this event should be done before calling the draw method, because otherwise the event might be fired before the listener is set up and you will not catch it.
• By calling interaction methods before the ready event is fired, you take a risk that these methods will not work properly.

The convention is that visualizations which do not fire a "ready" event are ready for interaction immediately after the draw method ends and returns control to the user.

Event Handling Example

The following example demonstrates both getSelection() and setSelection(). It synchronizes the selection between two visualizations that use the same data table. Click on either visualization to synchronize the selection in the other visualization.

// Create our two visualizations.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table visualization.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Click on the visualizations below on table rows or on chart elements to see the selection in action:

Get started quickly with an Interactive Code Sample you can edit and save.