The MongoDB Charts Embedding SDK Beta has Launched 🚀
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.
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’.
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.