Skip to content

Commit 9edd5d9

Browse files
steverensteveren
authored
DOCSP-7882: [Charts] Embedding SDK (unauthenticated) (#294)
1 parent 4646175 commit 9edd5d9

File tree

7 files changed

+253
-2
lines changed

7 files changed

+253
-2
lines changed

‎source/embedded-chart-options.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,8 @@ Considerations
266266
no longer valid. The host web page must regenerate a new signature
267267
to resume rendering the chart.
268268

269+
.. _chart-display-theme:
270+
269271
Specify a Display Theme
270272
-----------------------
271273

‎source/embedding-charts-sdk.txt

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
.. _embedding-charts-sdk:
2+
3+
===================================
4+
Embed Charts with the Embedding SDK
5+
===================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. include:: /includes/sdk-beta.rst
16+
17+
You can embed a chart into a web application with the Charts Embedding
18+
JavaScript SDK, allowing more flexible adjustments of settings and rendering.
19+
20+
Features of the embedding SDK include:
21+
22+
- Add filters dynamically
23+
- Change the size and style of the chart
24+
- Refresh on demand
25+
26+
The current version of the SDK supports :ref:`unauthenticated chart
27+
embedding <choose-access-level>`. A future version will include support
28+
for authenticated embedded charts.
29+
30+
To embed a chart with the SDK, you need to:
31+
32+
- Enable unauthenticated embedding for the chart.
33+
- Whitelist any document fields which you want to have available for use
34+
in :ref:`chart filters <embed-options-filter>`.
35+
- Have the chart ID and base URL strings.
36+
37+
To prepare a chart for embedding with the SDK, use the following
38+
procedure.
39+
40+
.. _embed-chart-procedure:
41+
42+
Procedure
43+
---------
44+
45+
.. include:: /includes/steps/embed-chart-sdk-anon.rst
46+
47+
Installation
48+
------------
49+
50+
If you have a simple web app, you can reference the Embedding SDK from a
51+
script tag, and no installation is needed. If you are building a more complex
52+
web app and are using ``npm`` or ``yarn``, you can install the Embedding SDK
53+
so that it can be used directly from your script files.
54+
55+
To install the embedding SDK with ``npm``, use the following command:
56+
57+
.. code-block:: none
58+
59+
npm install @mongodb-js/charts-embed-dom
60+
61+
To install with ``yarn``:
62+
63+
.. code-block:: none
64+
65+
yarn add @mongodb-js/charts-embed-dom
66+
67+
Examples
68+
--------
69+
70+
An `example app <https://codesandbox.io/s/charts-embedding-sdk-8i898>`__ using
71+
the embedding SDK can be found at ``codesandbox.io``. The example app
72+
demonstrates some of the interactive features available to the embedding
73+
SDK, including an interactive filter and a manual refresh button.
74+
75+
The example app is configured with a chart ID and base URL which are
76+
particular to the app. Be sure to configure your own apps with the correct
77+
chart ID and base URL.
78+
79+
Quick Start with HTML
80+
~~~~~~~~~~~~~~~~~~~~~
81+
82+
If you're just getting started with the embedding SDK and you would
83+
like to confirm that your chart ID and base URL are correct and
84+
try out some of the options, you can use the SDK in a simple HTML
85+
page by including it as part of a header script tag.
86+
87+
.. code-block:: html
88+
89+
<!DOCTYPE html>
90+
<html lang="en">
91+
<head>
92+
<title>Chart demo</title>
93+
<meta charset="utf-8">
94+
<!-- import the embedding sdk -->
95+
<script src="https://unpkg.com/@mongodb-js/charts-embed-dom@next"></script>
96+
<script src="https://code.jquery.com/jquery-1.9.1.min.js"></script>
97+
<script>
98+
$( document ).ready(function() {
99+
$("#refresh").on("click", () => {
100+
chart.refresh();
101+
});
102+
});
103+
</script>
104+
</head>
105+
<body>
106+
<h1>Embedded Chart Demo</h1>
107+
<button id="refresh">Refresh Chart</button>
108+
<div id="chart"></div>
109+
<script>
110+
const sdk = new ChartsEmbedSDK;
111+
// when using npm:
112+
// import ChartsEmbedSDK from '@mongodb-js/charts-embed-dom';
113+
114+
const chart = sdk
115+
.createChart({
116+
baseUrl: '<your-base-url>',
117+
chartId: '<your-chart-id>',
118+
width: 500,
119+
height: 500,
120+
refreshInterval: 300
121+
})
122+
.render(document.getElementById('chart'));
123+
</script>
124+
</body>
125+
</html>
126+
127+
Filter Embedded Charts with the SDK
128+
-----------------------------------
129+
130+
You can add a :ref:`filter <embed-options-filter>` to an embedded chart
131+
with the ``filter`` option. Filtering allows the chart author to only display
132+
data in the embedded chart which matches a specified :abbr:`MQL (MongoDB
133+
Query Language)` filter.
134+
135+
Any fields included in the filter must be specified in the Embed Chart modal
136+
window. The Embed Chart modal window contains a dropdown menu of fields on
137+
which to allow filtering.
138+
139+
Option Reference
140+
----------------
141+
142+
The following options are available to the JavaScript ``createChart``
143+
method:
144+
145+
.. list-table::
146+
:header-rows: 1
147+
:widths: 10 10 70 10
148+
149+
* - Option
150+
- Type
151+
- Description
152+
- Required?
153+
154+
* - ``baseUrl``
155+
- string
156+
- Base URL of the chart.
157+
- yes
158+
159+
* - ``chartID``
160+
- string
161+
- Unique identifier of the chart.
162+
- yes
163+
164+
* - ``height``
165+
- number
166+
- Height of the chart, in pixels.
167+
- yes
168+
169+
* - ``width``
170+
- number
171+
- Width of the chart, in pixels.
172+
- yes
173+
174+
* - ``filter``
175+
- object
176+
- A :ref:`filter <embed-options-filter>` to apply to the chart.
177+
- no
178+
179+
* - ``refreshInterval``
180+
- number
181+
- How often to refresh the chart, in seconds. The minimum refresh
182+
interval is 10 seconds. ``autorefresh`` is off By default.
183+
- no
184+
185+
* - ``theme``
186+
- string
187+
- A :ref:`theme <chart-display-theme>` for the chart to use. Valid
188+
options are ``light`` and ``dark``. Defaults to ``light``.
189+
- no
190+
191+
* - ``showAttribution``
192+
- boolean
193+
- Specifies whether or not to display the :guilabel:`MongoDB` logo
194+
below the chart. Defaults to ``true``.
195+
- no
196+

‎source/embedding-charts.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ require a verified signature to accompany each data request, or allow
1919
anyone with the chart's identifying information to share it or embed it
2020
in a web page.
2121

22+
.. _choose-access-level:
23+
2224
How to Choose an Access Level
2325
-----------------------------
2426

@@ -118,3 +120,4 @@ If an embedded chart fails to render, an error code is displayed:
118120
:titlesonly:
119121

120122
/embedded-chart-options
123+
/embedding-charts-sdk

‎source/images/charts/embed-chart-sdk.png

78.3 KB
Loading

‎source/includes/sdk-beta.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. admonition:: Note: Beta Software
2+
:class: important
3+
4+
The Charts Embedding JavaScript SDK is beta software. It is subject to
5+
change and not recommended for production use until it is out of beta.

‎source/includes/steps-embed-chart-sdk-anon.yaml

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
stepnum: 1
2+
source:
3+
file: steps-embed-chart-unauthenticated.yaml
4+
ref: select-dashboard
5+
---
6+
stepnum: 2
7+
source:
8+
file: steps-embed-chart-unauthenticated.yaml
9+
ref: select-chart
10+
---
11+
stepnum: 3
12+
source:
13+
file: steps-embed-chart-unauthenticated.yaml
14+
ref: enable-data-source
15+
---
16+
stepnum: 4
17+
source:
18+
file: steps-embed-chart-unauthenticated.yaml
19+
ref: select-unauthenticated
20+
---
21+
title: Toggle the switch marked :guilabel:`Enable unauthenticated
22+
access` to :guilabel:`On`.
23+
ref: toggle-unauthenticated-on
24+
level: 4
25+
---
26+
title: Whitelist any fields to be used for filtering.
27+
ref: whitelist-filter-fields
28+
level: 4
29+
content: |
30+
If you plan to allow :ref:`filtering <embed-options-filter>` on your
31+
chart, select the allowable fields from the :guilabel:`User Specified
32+
Filters` dropdown menu.
33+
---
34+
title: Click the :guilabel:`Javascript SDK` button.
35+
ref: click-js-sdk
36+
level: 4
37+
content: |
38+
39+
The chart ID and base URL appear in the modal window.
40+
41+
.. figure:: /images/charts/embed-chart-sdk.png
42+
:figwidth: 600px
43+
:alt: Embed unauthenticated chart
44+
45+
...
46+

‎source/includes/steps-embed-chart-unauthenticated.yaml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
---
21
title: Select a dashboard.
32
ref: select-dashboard
43
level: 4
@@ -46,7 +45,7 @@ content: |
4645
This |html| snippet is ready to copy and paste into an external web
4746
page.
4847
49-
.. figure:: /images/charts/embed-chart2.png
48+
.. figure:: /images/charts/embed-chart.png
5049
:figwidth: 508px
5150
:alt: Embed unauthenticated chart
5251

0 commit comments

Comments
 (0)