Navel Pondering Mantra

    @mongodb-js/charts-embed-dom
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    MongoDB Charts Embedding SDK

    Programmatically embed and control MongoDB Charts in your application.

    npm npm

    Example Usage

    import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';
    
    const sdk = new ChartsEmbedSDK({
      baseUrl: 'https://charts.mongodb.com/charts-charts-fixture-tenant-zdvkh',
    });
    
    // embed a chart
    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 whenever #refreshButton is clicked
    document
      .getElementById('refreshButton')
      .addEventListener('click', () => chart.refresh());
    
    // embed a dashboard
    const dashboard = sdk.createDashboard({
      dashboardId: '61d02578-6148-4c87-9cad-1fbaef50a0d3',
    });
    
    // render the chart into a container
    dashboard
      .render(document.getElementById('dashboard'))
      .catch(() => window.alert('Dashboard failed to initialise'));

    Getting Started

    Installation

    module formats: umd, cjs, and esm

    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
    1. Use the package
    import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';
    1. 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: EmbedOptions): ChartsEmbedSDK

    Creates an SDK object that can create Chart/Dashboard instances. Accepts an object that contains any default options to set for all Charts/Dashboards 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.

    createDashboard(options: EmbedDashboardOptions): Dashboard

    Creates an instance of a Dashboard that can be used to embed and control the embedded dashboard specified by dashboardId.

    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.
    width string | number The width of the embedded chart. If no width is provided, it will default to stretching to the width of its 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 its container. If a value is provided without units, it will be assumed to be pixels (px).
    autoRefresh boolean Specifies whether the chart automatically refreshes. If omitted, charts automatically refresh. Use this option with the maxDataAge option to configure how often the chart refreshes.
    maxDataAge number Specifies the maximum age of data to load from the cache when loading or refreshing the chart. If omitted, MongoDB Charts renders the chart with data from the cache if the data is less than one hour old.
    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.
    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 added to the allowed list in the 'Embed Chart' dialog for each Chart you wish to filter on.
    getUserToken function A function that should return a valid JWT token to use for authenticating the render request.
    theme 'light' | 'dark' The color scheme to apply to the chart. Defaults to light. 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.
    showAttribution boolean Whether to show the MongoDB attribution logo on the embedded chart. By default, this is set to true.

    EmbedDashboardOptions

    These options configure the behaviour of a Dashboard when it is first embedded. After this, you can control the configuration of the Dashboard 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.
    dashboardId string The dashboard id for the embedded dashboard. This can be found in the Embed Dashboard dialog.
    width string | number The width of the embedded dashboard. If no width is provided, it will default to stretching to the width of its container. If a value is provided without units, it will be assumed to be pixels (px).
    height string | number The height of the embedded dashboard. If no height is provided, it will default to stretching to the height of its container. If a value is provided without units, it will be assumed to be pixels (px).
    autoRefresh boolean Specifies whether the dashboard automatically refreshes. If omitted, dashboards automatically refresh. Use this option with the maxDataAge option to configure how often the dashboard refreshes.
    maxDataAge number Specifies the maximum age of data to load from the cache when loading or refreshing the dashboard. If omitted, MongoDB Charts renders the dashboard with data from the cache if the data is less than one hour old.
    background string A background color for the embedded dashboard e.g. 'transparent'. If no background is provided it will set a default based on the theme.
    chartsBackground string A background color for all charts in the embedded dashboard e.g. 'transparent'.
    getUserToken function A function that should return a valid JWT token to use for authenticating the render request.
    theme 'light' | 'dark' The color scheme to apply to the dashboard. Defaults to light.
    showAttribution boolean Whether to show the MongoDB attribution logo on the embedded dashboard. By default, this is set to true.
    widthMode 'fixed'|'scale' Width behaviour of charts in an embedded dashboard. fixed: width of charts will remain the same as the configured on dashboard; scale: width of charts will scale according to the container. Defaults to fixed.
    heightMode 'fixed'|'scale' Height behaviour of charts in an embedded dashboard. fixed: height of charts will remain the same as the configured on dashboard; scale: height of charts will scale according to the container. Defaults to fixed.

    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 accept 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 auto refresh. Auto refresh is enabled 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 added to the allowed list 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.

    addEventListener(event: string, eventHandler: (payload: object) => void, options: object): Promise<void>

    Adds an event listener to an embedded chart. We currently support only 'click' events. The payload parameter in the event callback contains details on the chart element clicked. You can also define the chart's mark roles and/or types for which you want to receive event information in the options parameter. More information regarding how to handle click events can be found in the Charts documentation.

    removeEventListener(event: string, eventHandler: (payload: object) => void, options: object): Promise<void>

    Removes an event listener that was previously added. You need to provide the same parameters that were used for subscribing to the event.

    setHighlight(value: object): Promise<void>

    Sets a highlight to apply to an embedded chart. The value object parameter should contain valid query operators. It is the same type of object that can be used in setFilter. You can clear an existing highlight by setting the value to an empty object {}. More information regarding charts highlighting can be found in the Charts documentation.

    getHighlight(): Promise<object>

    Returns the current highlight applied to an embedded chart.

    getData(): Promise<object>

    Returns the underlying data used to render chart. It has following structure

    {
      // an object whose key is the name of a channel, e.g. x, y, etc
      fields: { [channel]: string },
      // an array of object whose key is the name of a channel, e.g. x, y, etc
      documents: Array<{ [channel]: any }>
    }
    

    Dashboard

    The Dashboard instance returned by ChartsEmbedSDK.createDashboard({ ... }).

    render(container: HTMLElement): Promise<void>

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

    refresh(): Promise<void>

    Triggers a refresh of the dashboard.

    setAutoRefresh(bool: boolean): Promise<void>

    Enable or disable auto refresh. Auto refresh is enabled 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 on a dashboard is allowed to be before it is considered expired.

    getMaxDataAge(): Promise<number>

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

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

    Sets the current theme of the embedded dashboard. Defaults to 'light';

    getTheme(): Promise<string>

    Returns the current theme applied to the embedded dashboard.

    setChartsBackground(color: string): Promise<void>

    Sets a custom background color that will be applied to all charts of the embedded dashboard.

    getChartsBackground(): Promise<string>

    Returns the current custom background color.

    setWidthMode(mode: 'fixed' | 'scale'): Promise<void>

    Sets the width mode that will be applied to all charts of the embedded dashboard. Defaults to 'fixed';

    getWidthMode(): Promise<'fixed' | 'scale'>

    Returns the current width mode.

    setHeightMode(mode: 'fixed' | 'scale'): Promise<void>

    Sets the height mode that will be applied to all charts of the embedded dashboard. Defaults to 'fixed';

    getHeightMode(): Promise<'fixed' | 'scale'>

    Returns the current height mode.

    getChart(chartId: string): Promise<DashboardChart>

    Returns an instance DashboardChart that has the specified chart id.

    getAllCharts(): Promise<DashboardChart[]>

    Returns an array of DashboardChart instances of all charts on the embedded dashboard.

    DashboardChart

    The chart instance returned by Dashboard.getChart('chartId') or Dashboard.getAllCharts().

    refresh(): Promise<void>

    Triggers a refresh of the chart.

    addEventListener(event: string, eventHandler: (payload: object) => void, options: object): Promise<void>

    Adds an event listener to the embedded chart. We currently support only 'click' events. The payload parameter in the event callback contains details on the chart element clicked. You can also define the chart's mark roles and/or types for which you want to receive event information in the options parameter. More information regarding how to handle click events can be found in the Charts documentation.

    removeEventListener(event: string, eventHandler: (payload: object) => void, options: object): Promise<void>

    Removes an event listener that was previously added. You need to provide the same parameters that were used for subscribing to the event.

    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.

    Keywords

    none

    Install

    npm i @mongodb-js/charts-embed-dom

    DownloadsWeekly Downloads

    2,739

    Version

    2.2.0

    License

    Apache-2.0

    Unpacked Size

    3.55 MB

    Total Files

    47

    Last publish

    Collaborators

    • mutukrish
    • tomhollander
    • matt_d_rat
    • srv-charts-read-only
    • srv-mdb-charts-build-bot
    • kristina.stefano
    • jarjee