charts-embed-dom-react18 v2.1.0-beta.1

Programmatically embed and control MongoDB Charts in your application.

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

1. Install the @mongodb-js/charts-embed-dom package

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

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

2. Use the package

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

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

<script>
  const ChartsEmbedSDK = window.ChartsEmbedSDK;

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

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

FAQs

I'm using Rollup, what configuration options do I need to set?

To use the Embedding SDK with Rollup, you'll need to have a rollup.config.js that looks like:

import resolve from '@rollup/plugin-node-resolve';
import cjs from '@rollup/plugin-commonjs';

export default {
  input: 'index.js',
  output: {
    file: 'bundle.js',
    format: 'cjs'
  },
  plugins: [ cjs(), resolve({ browser: true, preferBuiltins: false }) ]
};

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.

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.

setAutoRefresh(bool: boolean): Promise<void>

Enable or disable chart autorefresh. Auto refresh is disabled by default.

isAutoRefresh(): Promise<boolean>

Returns whether auto refreshing is enabled or not.

setMaxDataAge(seconds: number): Promise<void>

Sets a duration (in seconds) for how old a chart is allowed to be before it is considered expired.

getMaxDataAge(): Promise<number>

Returns the duration (in seconds) that has to pass before a chart is considered stale.

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.