The MongoDB Charts Embedding SDK Beta has Launched 🚀

Scott Sidwell
February 12, 2020 | Updated: February 19, 2020
#Charts

MongoDB Charts on Atlas now supports embedding using a JavaScript SDK (in beta), allowing you to programmatically create and interact with your charts in your own application.

Embedded Charts have just got an upgrade in the latest release of Charts on Atlas. The new Charts Embedding SDK allows you to render and control MongoDB Charts directly in your application via JavaScript, without needing to touch any HTML. It’s never been easier to enrich your applications with live visualizations. This has been a long-awaited feature that makes it stunningly easy to enrich your web applications with live visualizations from your data.

This beta release allows you to render unauthenticated charts with the SDK. Support for rendering authenticated charts with the SDK will be coming a bit later on. If you need a more secure embedding solution in the meantime, you can continue to use the Verified Signature option for IFrame embedded charts.

What Can You Do With the Embedding SDK?

The best way to show you is to demo it! The chart below was embedded using the Embedding SDK. Note how we are able to refresh the chart on demand and dynamically change what filters are applied to the chart using the drop-down.

Embedded MongoDB Chart Filtering — Explore this example yourself

Why Use the SDK Over the Existing IFrame Approach?

Previously, as a developer, you could only embed charts into your application by copying and pasting an IFrame snippet which you then inserted in your web application. While this worked for a number of users, others asked for a richer experience. The IFrame approach, while simple to integrate, delivers charts that can’t be programmatically controlled. For example, if you wanted to change a filter or theme after the chart was rendered on a page, you had to refresh the page to see a change in the chart. With the new SDK, not only can you now interact with a chart using JavaScript, but you will also have a better developer experience.

How Can I Get Started?

The easiest way to get started with the SDK is to include a script tag in the header of your page.

<html>
  <head>
     <script src="https://unpkg.com/@mongodb-js/charts-embed-dom@beta"></script>  
  </head>
  <body>
    <div id="chart" />
    <script>
      // use the SDK here via ChartsEmbedSDK
    </script>
  </body>
</html>

For larger projects, you can install the SDK using NPM.

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

Once you’ve installed the package or added it to your page, you will need to configure it with the appropriate values for the chart you’re wishing to embed.

// when using npm:
// import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';

const sdk = new ChartsEmbedSDK({
  baseUrl: BASE_URL
});

const chart = sdk.createChart({ chartId: CHART_ID }); 
chart.render(document.getElementById('app'));

To get the ‘BASE_URL’ and ‘CHART_ID’, you’ll need to open up https://charts.mongodb.com and navigate to the ‘Embed Chart’ dialog for your chart. Here you can enable unauthenticated sharing, as well as click the ‘Javascript SDK’ tab to see the ‘Chart ID' and 'Base URL’.

Embed Charts

With these in hand, you can return to your code editor and fill in the missing pieces

// when using npm:
// import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';

const sdk = new ChartsEmbedSDK({
  baseUrl: 'https://charts.mongodb.com/charts-charts-fixture-tenant-zdvkh'
});

const chart = sdk.createChart({ chartId: '48043c78-f1d9-42ab-a2e1-f2d3c088f864' }); 
chart.render(document.getElementById('app'));

From here, you can call methods on the chart object like chart.setFilter({ ‘address.country’: 'Australia' }) to apply custom filters to your chart (assuming you’ve whitelisted the address.country field in the Embed Dialog) and chart.setRefreshInterval(1000) to set how often a chart should refresh dynamically in your application.

Give It a Try

We’d love to find out how you’re using the Charts Embedding SDK. If you have any questions, feel free to use the in-product chat, or if you have suggestions on how to improve anything in Charts, use the MongoDB Feedback Engine.

If you haven’t tried Charts yet, you can get started by signing up for MongoDB Atlas for free.

← Previous

Filter Your Dashboards with MongoDB Charts

MongoDB Charts on Atlas now supports dashboard-level filters, allowing you to quickly change the context of a single dashboard to better focus your analysis.

February 12, 2020

Next →

Control Your Colours in MongoDB Charts

Colours are integral to the story you want to convey with any sort of data visualisation. With the latest release of MongoDB Charts , we have added more control to how you can assign colours to your charts! Previously, colour assignment of a series were always based on the series order within that chart. However, we may instead want to colour the chart based on the series value. Some basic scenarios where these different strategies prove useful include: Colouring the top 3 series with the colours gold, silver and bronze. Colouring the series "Summer" and "Winter" with "Red" and "Blue" respectively, to symbolise the season. If the above examples did not give it away enough, we will create some beautiful charts using an Olympics dataset to fully understand the capabilities of the new features. Single-series charts We will start off with a basic single-series chart. These charts usually have a single field encoded to the x and y axes and will display a single colour for the chart. In these charts, we now show a single colour swatch for you to edit. Simple, right? Multi-series charts For more complicated charts with multiple series, we may want to colour the series based on the encoded field itself. These charts are created when multiple fields are encoded to an aggregation channel where the field key is used to build the multi-series chart. In the above chart, I have a medal tally of the top 10 countries based on medal count. The chart itself is fine, but we could improve this chart with some useful colouring! A notable colour scheme we could apply to this chart is assigning each series to the colour of the medal. Inside the Color Palette customisation option, you will see that each encoded field is now listed based on the order that they were encoded in. With the colour scheme set to the medal colour, the chart will be a lot easier to convey the original information. Colours assigned to these channels will always have the same colour assigned and will ignore the ordering of these fields. Assigning chart colours to string data The final chart that we want to create, involves a chart where the data itself is a String type. With these chart types, the Color Palette will provide options to toggle between the two different colour assignment strategies where: 'By Order' will allow you to assign colours by the ordering of the series 'By Series' lets you customise the colour for a specific series value To help streamline the process of assigning colours in the above chart, in the ‘By Order’ menu, I can choose to assign colours based on the value order of the Discipline that appears in the chart. This may be useful if we don't care what the colours are that represent each Discipline. Alternatively, we could assign colours using 'By Series' so that we can be assured that I can represent the Disciplines with an associated colour. Now that we have created all of our charts using the different ways we can assign colours, we can be confident that the colours in our data visualisations are consistent throughout our dashboard. Want to start colouring your charts today? You can start now for free by signing up for MongoDB Atlas , deploying a free tier cluster and activating Charts. Have an idea on how we can make MongoDB Charts better? Feel free to leave an idea at the MongoDB Feedback Engine .

August 4, 2021