Navigation
This documentation refers to the MongoDB Charts service in MongoDB Atlas. Read the on-premises documentation to learn how to use the MongoDB Charts on site.

Embed Charts with the Embedding SDK

Note: Beta Software

The Charts Embedding JavaScript SDK is beta software. It is subject to change and not recommended for production use until it is out of beta.

You can embed a chart into a web application with the Charts Embedding JavaScript SDK, allowing more flexible adjustments of settings and rendering.

Features of the embedding SDK include:

  • Add filters dynamically
  • Change the size and style of the chart
  • Refresh on demand

The current version of the SDK supports unauthenticated chart embedding. A future version will include support for authenticated embedded charts.

To embed a chart with the SDK, you need to:

  • Enable unauthenticated embedding for the chart.
  • Whitelist any document fields which you want to have available for use in chart filters.
  • Have the chart ID and base URL strings.

To prepare a chart for embedding with the SDK, use the following procedure.

Procedure

1

Select a dashboard.

From your dashboard tab, select the dashboard containing the chart you wish to make embeddable.

2

Select a chart.

From the dashboard, click ellipsis icon at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable external sharing on the data source

If you have already enabled external sharing on the data source this chart uses, skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Configure external sharing link.

4

Select the Unauthenticated tab in the dialog window.

Embed unauthenticated chart
5

Toggle the switch marked Enable unauthenticated access to On.

6

Whitelist any fields to be used for filtering.

If you plan to allow filtering on your chart, select the allowable fields from the User Specified Filters dropdown menu.

7

Click the Javascript SDK button.

The chart ID and base URL appear in the modal window.

Embed unauthenticated chart

Installation

If you have a simple web app, you can reference the Embedding SDK from a script tag, and no installation is needed. If you are building a more complex web app and are using npm or yarn, you can install the Embedding SDK so that it can be used directly from your script files.

To install the embedding SDK with npm, use the following command:

npm install @mongodb-js/charts-embed-dom

To install with yarn:

yarn add @mongodb-js/charts-embed-dom

Examples

An example app using the embedding SDK can be found at codesandbox.io. The example app demonstrates some of the interactive features available to the embedding SDK, including an interactive filter and a manual refresh button.

The 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.

The example app uses two SDK methods:

Method Description Args Returns
refresh() Reloads the chart with the latest data from its data source. none Promise<void>
setFilter()

Filters your embedded chart based on a specified MQL filter document.

Note

Any fields included in the filter must be specified in the Embed Chart modal. See Filter Embedded Charts with the SDK.

filter object Promise<void>

Quick Start with HTML

If you’re just getting started with the embedding SDK and you would like to confirm that your chart ID and base URL are correct and try out some of the options, you can use the SDK in a simple HTML page by including it as part of a header script tag.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Chart demo</title>
    <meta charset="utf-8">
    <!-- import the embedding sdk -->
    <script src="https://unpkg.com/@mongodb-js/charts-embed-dom@next"></script>
    <script src="https://code.jquery.com/jquery-1.9.1.min.js"></script>
    <script>
      $( document ).ready(function() {
        $("#refresh").on("click", () => {
          chart.refresh();
        });
      });
    </script>
  </head>
  <body>
    <h1>Embedded Chart Demo</h1>
    <button id="refresh">Refresh Chart</button>
    <div id="chart"></div>
    <script>
      const sdk = new ChartsEmbedSDK;
      // when using npm:
      // import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';

      const chart = sdk
        .createChart({
          baseUrl: '<your-base-url>',
          chartId: '<your-chart-id>',
          width: 500,
          height: 500,
          refreshInterval: 300
        })
        .render(document.getElementById('chart'));
    </script>
  </body>
</html>

Filter Embedded Charts with the SDK

You can add a filter to an embedded chart with the filter option. Filtering allows the chart author to only display data in the embedded chart which matches a specified MQL filter.

Any fields included in the filter must be specified in the Embed Chart modal. The Embed Chart modal contains a dropdown menu of fields on which to allow filtering.

The following uses the filter option to represent only documents in which the total field is greater than 100:

createChart({
  baseUrl: '<your-base-url>',
  chartId: '<your-chart-id>',
  width: 500,
  height: 500,
  filter: { "total": { "$gt": 100 } }
})

Option Reference

The following options are available to the JavaScript createChart method:

Option Type Description Required?
baseUrl string Base URL of the chart. yes
chartID string Unique identifier of the chart. yes
height number Height of the chart, in pixels. yes
width number Width of the chart, in pixels. yes
filter object A filter to apply to the chart. no
refreshInterval number How often to refresh the chart, in seconds. The minimum refresh interval is 10 seconds. autorefresh is off by default. no
theme string A theme for the chart to use. Valid options are light and dark. Defaults to light. no
showAttribution boolean Specifies whether or not to display the MongoDB logo below the chart. Defaults to true. no