Navigation

Handle Click Events

Note

Click Events in the Charts Embedding SDK is available as a beta feature. It is only available with Charts Embedding JavaScript SDK v2.1.0-beta.1.

The Charts Embedding JavaScript SDK includes a click event handler that allows you to subscribe to click events. When you click on a particular element on your chart, the click event handler captures details of the element that you clicked. Use this feature to build interactive experiences similar to the following in your application:

  • Click on an element on a chart and open a pane with more details on the clicked element.
  • Create a filter for another chart.

Before you begin, install the Charts Embedding JavaScript SDK.

The event handler takes an event type, click, and a callback function that contains information about the click event and the clicked element as a single payload object. The click event handler syntax looks similar to the following:

chart.addEventListener("click", callback);

The event handler also allows you to define the mark roles for which you want to receive event information, thus eliminating the need to check the payload. The click event handler syntax for defining the mark roles to filter by looks similar to the following:

const options = { includes: [{ roles: ['mark', 'axis-label'] }] };
chart.addEventListener("click", callback, options);

The click event handler must be added after the chart has finished rendering, as shown in the following example:

Example
chart.render(document.getElementById("chart")).then(
() => chart.addEventListener('click',
(payload) => alert(JSON.stringify(payload)),
options)
);
Note

If you specify the options parameter, the click event handler captures events only if the clicked mark's role matches one of the values specified in the parameter. If you omit this parameter, the click event handler captures all click events on the chart.

You can use the click event payload to construct a custom filter that you can apply on other charts in your application. The syntax of the payload object for the callback function looks similar to the following:

chart.addEventListener("click", (payload) => {
// handle events
}

The following example payload object shows the elements inside the payload:

Example
{
"chartId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"chartTitle": "This is my chart's title",
"chartDescription": "This is my chart's description",
"event": { // information about the mouse event. For example:
"type": "click", // event type
"altKey": false, // modifier keys
"ctrlKey": false,
"shiftKey": false,
"metaKey": false,
"offsetX": 152, // element coordinates
"offsetY": 176,
"clientX": 172, // coordinates from application viewpoint
"clientY": 241,
"pageX": 172, // coordinates relative to the page
"pageY": 241,
"screenX": 172, // coordinates relative to screen
"screenY": 312
},
"data": { // information about the clicked chart element. For example:
"y": {
"label": "unwind array 'genres'",
"value": "Adventure"
},
"x": {
"label": "count ( _id )",
"value": 659
},
"color": {
"label": "year",
"value": "2000 - 2010",
"lowerBound": 2000,
"upperBound": 2010
}
},
selectionFilter: {
// category data expressed as MQL filter query that
// interactive filters would output to filter other charts.
// For example:
genres: 'Adventure',
year: {
$gte: 2000,
$lt: 2010,
},
},
"target": { // information about the clicked target. For example:
"type": "rect", // type of mark, such as rect, line, etc.
"role": "mark", // role of mark, such as mark, legend, etc.
"fill": "#8CB6F2" // fill color of the mark
},
"apiVersion": 1 // API version of event payload
}

To learn more about the elements inside the payload object, see:

The event element of the payload contains information about the mouse event including:

  • The type of mouse event, which must be click
  • The modifier keys used to trigger a click event such as altKey, ctrlKey, shiftKey, metaKey
  • The X and Y coordinates:

    • Relative to the canvas element of the chart
    • From the application viewpoint
    • Relative to the page
    • Relative to the screen

The data element of the payload contains information about the clicked chart element. For each encoded data field (x, y, series, intensity, color, shape, size, label, arc, value, target, number, display, text, location), the data element contains:

  • The channel label
  • The value of the clicked element
  • The lower bound for numeric or date binning only

For data tables, the Charts Embedding JavaScript SDK click event handler captures click events for the following elements:

  • Chart title
  • Fields that represent the channel data for the clicked element:

    • groups field, which contains all Groups channels including label and value
    • cell field, which contains the column header label and value of the clicked cell

The selectionFilter element of the payload must contain a valid MQL filter document, which represents the filter that corresponds to the clicked mark's category channels or x value channel on a continuous chart. You can modify or implement your own selectionFilter.

The filter object represents a single clicked item:

  • A string or unbinned number or date, which becomes an equality match query ({field: value}) or a query using $eq, $ne, $in, or $nin operators.
  • A binned number or date, which becomes a query using gt, $gte, $lt, or lte operators. Periodic dates are ignored.
Example
{ field: 'value' }
{ field1: 'value1', field2: 'value2' }
{ field: { $in: [ 'a', 'b', 'c' ] } }
{ field: { $nin: [ 'x', 'y', 'z' ] } }
{ field: { $gt: 10 } }
{ field: { $gt: 13, $lte: 30 } }
{ field: { $gt: Date("2020-01-01"), $lt: Date("2020-03-31") } }

The selectionFilter document can have several key and value filters. For example, if a mark of a multi-series chart is clicked, the filter document contains both the category and series filter pairs. Each filter must reference the actual data source fields used and not their labels.

On an embedded chart that includes event handlers with a filter for element roles, the chart shows:

  • The when you hover over an element that triggers a filtered click event
  • The when you hover over an element that doesn't trigger a click event

If the event handler doesn't include filter for element roles, the appears when you hover over any chart element.

The target element of the payload contains information about the clicked target including:

  • The type of mark, such as rect, line, arc, symbol, etc.
  • The role of mark, such as mark, legend, axis-label, etc.
  • The fill color of the mark

For data tables, the Charts Embedding JavaScript SDK click event handler payload captures the following:

  • Mark type, which is text
  • Mark role, such as group-cell, value-cell, dynamic-value-cell, row-total-cell, column-total-cell, header-column-total-cell, and grand-total-cell

The Charts Embedding JavaScript SDK click event handler does not capture click events on column headers.

The Charts Embedding JavaScript SDK includes examples that demonstrate common uses for click events in an application. The first example shows basic click events and payload handling. The second example shows interactive filtering of clicked chart elements.

To learn more about installing the Embedding SDK and running the example app with your own data or sample data, see MongoDB Charts Embedding Example for Click Events on GitHub. Each example app is configured with a chart ID and base URL which are particular to the app. Be sure to configure your own apps with the correct chart ID and base URL.

In the example app for basic handling of click events, when you click on an element on the Movie Genres chart, the click event handler displays data based on the clicked element. In this example application, the chart shows the on all chart elements because the chart doesn't include a filter for mark roles.

Each time you click on an element in the chart, the click event listener refreshes the payload to reflect data from the x and y axis. When you click on an element that represents a specific genre and decade in the Movie Genres chart, the Clicked Element and Full Event Payload displays details on that movie genre and decade including:

  • Fields that represent data for the clicked element.
  • Mark type, role, and fill color.

Refer to the example app to view the full event payload.

In the example app for interactive filtering, when you click on an element on the Movie Genres chart, the embedding SDK generates a filter based on the element on which you clicked and then applies the filter to a second chart. In this example application, the chart shows:

  • The when you hover over an interactive element
  • The when you hover over an element which doesn't trigger a click event

The click event listener triggers events only for the mark roles specified through the options parameter. The payload defines a filter based on the y axis, which represents the movie genres, and the lower and upper bound range, which represents the decade. Each time you click on an element that represents a specific genre and decade on the Movie Genres chart, the Movie Details data table is filtered by the clicked element and changes to display the movies available in that genre and decade.

Refer to the example app to view the full a sample event handler callback function.

Give Feedback