Package Exports

@mongodb-js/charts-embed-dom

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@mongodb-js/charts-embed-dom) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

MongoDB Charts Embedding SDK

Programmatically embed and control MongoDB Charts in your application.

Note: This library is current in beta, and is not recommended for use in production instances before a 1.0.0 release. For existing approaches to support embedding charts, please review the Charts documentation

demo of embedding Explore this example yourself!

Example Usage

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',
});

// render the chart into a container
chart
  .render(document.getElementById('chart'))
  .catch(() => window.alert('Chart failed to initialise'));

// refresh the chart whenenver #refreshButton is clicked
document
  .getElementById('refreshButton')
  .addEventListener('click', () => chart.refresh());

Getting Started

Installation

Install the @mongodb-js/charts-embed-dom beta package

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

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

Use the package

import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';

Profit 📈

Distribution Bundle

A universal module definition bundle is also published on npm under the /dist folder for consumption.

You can use the UMD to run @mongodb-js/charts-embed-sdk directly in the browser.

<!-- library  -->
<script src="https://unpkg.com/@mongodb-js/charts-embed-dom@beta"></script>

<script>
  const ChartsEmbedSDK = window.ChartsEmbedSDK;

  const sdk = new ChartsEmbedSDK({ ... });
  const chart = sdk.createChart({ ... });

  chart.render(document.getElementById('chart'));
</script>

API

ChartsEmbedSDK

The default export of @mongodb-js/charts-embed-dom.

`constructor(options: EmbedChartOptions): ChartsEmbedSDK`

Creates an SDK object that can create Chart instances. Accepts an object that contains any default options to set for all Charts created using this SDK instance.

`createChart(options: EmbedChartOptions): Chart`

Creates an instance of a Chart that can be used to embed and control the MongoDB Chart specified by chartId.

EmbedChartOptions

These options configure the behaviour of a Chart when it is first embedded. After this, you can control the configuration of the Chart by calling methods on its handle.

name	type	description
baseUrl	string	The base url for your MongoDB Charts instance, it should look something like: `https://charts.mongodb.com/charts-example-url-zdvkh`.
chartId	string	The chart id for the embedded chart. This can be found in the `Embed Chart` dialog when viewing a chart on a Dashboard.
filter	object	A filter to apply to the embedded chart. This expects an object that contains a valid query operators. Any fields referenced in this filter are expected to be whitelisted in the 'Embed Chart' dialog for each Chart you wish to filter on.
refreshInterval	number	The number of seconds to wait before refreshing the Chart. The minimum refreshInterval is 10 seconds. By default, a chart will never refresh once rendered.
width	string \| number	The width of the embedded chart. If no width is provided, it will default to stretching to the width of it's container. If a value is provided without units, it will be assumed to be pixels (px).
height	string \| number	The height of the embedded chart. If no height is provided, it will default to stretching to the height of it's container. If a value is provided without units, it will be assumed to be pixels (px).
theme	'light' \| 'dark'	The color scheme to apply to the chart. If the theme is set to 'dark', you will need to ensure that your background color has appropriate contrast as by default a chart's background is transparent.
background	string	A background color for the embedded chart e.g. 'transparent'. If no background is provided it will set a default based on the theme.
getUserToken	function	A function that shoud return a valid JWT token to use for authenticating the render request.

Chart

The Chart instance returned by ChartsEmbedSDK.createChart({ ... }).

`render(container: HTMLElement): Promise<void>`

Renders a chart into the specified container and should only be invoked once. It returns a Promise that will resolve once the chart is 'ready' to accepts commands (like setFilter, refresh).

`refresh(): Promise<void>`

Triggers a refresh of the chart, if it is embedded.

`setRefreshInterval(seconds: number): Promise<void>`

Sets how often the embedded chart will wait before refreshing. The minimum refreshInterval is 10 seconds. To disable, set the refreshInterval to 0.

`getRefreshInterval(seconds: number): Promise<number>`

Returns the number of seconds a chart will wait before refreshing

`setFilter(filter: object): Promise<void>`

Applies a filter to the embedded chart. This expects an object that contains valid query operators. Any fields referenced in this filter are expected to be whitelisted in the 'Embed Chart' dialog. An empty document {} is equivilent to no filter.

`getFilter(): Promise<object>`

Returns the current filter applied to the embedded chart.

`setTheme(theme: 'dark' | 'light'): Promise<void>`

Sets the current theme of the embedded chart. When setting the theme to 'dark', you will need to ensure that your background color has appropriate contrast as by default a chart's background is transparent.

`getTheme(): Promise<string>`

Returns the current theme applied to the embedded chart.

getRealmUserToken(client: StitchClient): string

A helper function to use the Realm authentication provider. Returns a value to pass to the getUserToken prop via a function.