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" />
</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.