diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..382c521 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/usr/bin/env sh +. "$(dirname -- "$0")/_/husky.sh" + +npm run build:md diff --git a/examples/.markdown/compilation/chart/authenticated-custom-jwt.json b/examples/.markdown/compilation/chart/authenticated-custom-jwt.json new file mode 100644 index 0000000..17106e5 --- /dev/null +++ b/examples/.markdown/compilation/chart/authenticated-custom-jwt.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/authenticated-custom-jwt/README.md", + "files" : ["examples/.markdown/config/chart/authenticated-custom-jwt.md"] +} diff --git a/examples/.markdown/compilation/chart/authenticated-google.json b/examples/.markdown/compilation/chart/authenticated-google.json new file mode 100644 index 0000000..ab7b938 --- /dev/null +++ b/examples/.markdown/compilation/chart/authenticated-google.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/authenticated-google/README.md", + "files" : ["examples/.markdown/config/chart/authenticated-google.md"] +} diff --git a/examples/.markdown/compilation/chart/authenticated-realm-deprecated.json b/examples/.markdown/compilation/chart/authenticated-realm-deprecated.json new file mode 100644 index 0000000..57ecca5 --- /dev/null +++ b/examples/.markdown/compilation/chart/authenticated-realm-deprecated.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/authenticated-realm-deprecated/README.md", + "files" : ["examples/.markdown/config/chart/authenticated-realm-deprecated.md"] +} diff --git a/examples/.markdown/compilation/chart/authenticated-realm-web.json b/examples/.markdown/compilation/chart/authenticated-realm-web.json new file mode 100644 index 0000000..cc7a4b2 --- /dev/null +++ b/examples/.markdown/compilation/chart/authenticated-realm-web.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/authenticated-realm-web/README.md", + "files" : ["examples/.markdown/config/chart/authenticated-realm-web.md"] +} diff --git a/examples/.markdown/compilation/chart/click-events-basic.json b/examples/.markdown/compilation/chart/click-events-basic.json new file mode 100644 index 0000000..01f209e --- /dev/null +++ b/examples/.markdown/compilation/chart/click-events-basic.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/click-events-basic/README.md", + "files" : ["examples/.markdown/config/chart/click-events-basic.md"] +} diff --git a/examples/.markdown/compilation/chart/click-events-filtering.json b/examples/.markdown/compilation/chart/click-events-filtering.json new file mode 100644 index 0000000..2977cc6 --- /dev/null +++ b/examples/.markdown/compilation/chart/click-events-filtering.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/click-events-filtering/README.md", + "files" : ["examples/.markdown/config/chart/click-events-filtering.md"] +} diff --git a/examples/.markdown/compilation/chart/programmatic-highlighting.json b/examples/.markdown/compilation/chart/programmatic-highlighting.json new file mode 100644 index 0000000..3114c00 --- /dev/null +++ b/examples/.markdown/compilation/chart/programmatic-highlighting.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/programmatic-highlighting/README.md", + "files" : ["examples/.markdown/config/chart/programmatic-highlighting.md"] +} diff --git a/examples/.markdown/compilation/chart/timeline-charts.json b/examples/.markdown/compilation/chart/timeline-charts.json new file mode 100644 index 0000000..209378c --- /dev/null +++ b/examples/.markdown/compilation/chart/timeline-charts.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/timeline-charts-example/README.md", + "files" : ["examples/.markdown/config/chart/timeline-charts-example.md"] +} diff --git a/examples/.markdown/compilation/chart/unauthenticated.json b/examples/.markdown/compilation/chart/unauthenticated.json new file mode 100644 index 0000000..58f629a --- /dev/null +++ b/examples/.markdown/compilation/chart/unauthenticated.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/charts/unauthenticated/README.md", + "files" : ["examples/.markdown/config/chart/unauthenticated.md"] +} diff --git a/examples/.markdown/compilation/dashboard/authenticated-custom-jwt.json b/examples/.markdown/compilation/dashboard/authenticated-custom-jwt.json new file mode 100644 index 0000000..8ffbe6e --- /dev/null +++ b/examples/.markdown/compilation/dashboard/authenticated-custom-jwt.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/authenticated-custom-jwt/README.md", + "files" : ["examples/.markdown/config/dashboard/authenticated-custom-jwt.md"] +} \ No newline at end of file diff --git a/examples/.markdown/compilation/dashboard/authenticated-google.json b/examples/.markdown/compilation/dashboard/authenticated-google.json new file mode 100644 index 0000000..6036c7a --- /dev/null +++ b/examples/.markdown/compilation/dashboard/authenticated-google.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/authenticated-google/README.md", + "files" : ["examples/.markdown/config/dashboard/authenticated-google.md"] +} diff --git a/examples/.markdown/compilation/dashboard/authenticated-realm-deprecated.json b/examples/.markdown/compilation/dashboard/authenticated-realm-deprecated.json new file mode 100644 index 0000000..ed7c49d --- /dev/null +++ b/examples/.markdown/compilation/dashboard/authenticated-realm-deprecated.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/authenticated-realm-deprecated/README.md", + "files" : ["examples/.markdown/config/dashboard/authenticated-realm-deprecated.md"] +} diff --git a/examples/.markdown/compilation/dashboard/authenticated-realm-web.json b/examples/.markdown/compilation/dashboard/authenticated-realm-web.json new file mode 100644 index 0000000..0281bf0 --- /dev/null +++ b/examples/.markdown/compilation/dashboard/authenticated-realm-web.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/authenticated-realm-web/README.md", + "files" : ["examples/.markdown/config/dashboard/authenticated-realm-web.md"] +} diff --git a/examples/.markdown/compilation/dashboard/unauthenticated-get-chart.json b/examples/.markdown/compilation/dashboard/unauthenticated-get-chart.json new file mode 100644 index 0000000..dd04b26 --- /dev/null +++ b/examples/.markdown/compilation/dashboard/unauthenticated-get-chart.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/unauthenticated-get-chart/README.md", + "files" : ["examples/.markdown/config/dashboard/unauthenticated-get-chart.md"] +} diff --git a/examples/.markdown/compilation/dashboard/unauthenticated.json b/examples/.markdown/compilation/dashboard/unauthenticated.json new file mode 100644 index 0000000..36dc811 --- /dev/null +++ b/examples/.markdown/compilation/dashboard/unauthenticated.json @@ -0,0 +1,4 @@ +{ + "build" : "examples/dashboard/unauthenticated/README.md", + "files" : ["examples/.markdown/config/dashboard/unauthenticated.md"] +} diff --git a/examples/.markdown/config/chart/authenticated-custom-jwt.md b/examples/.markdown/config/chart/authenticated-custom-jwt.md new file mode 100644 index 0000000..ef0e49f --- /dev/null +++ b/examples/.markdown/config/chart/authenticated-custom-jwt.md @@ -0,0 +1,42 @@ +# MongoDB Charts Embedding Example - Authenticated Embedded Chart + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +This sample shows how to use the JavaScript Embedding SDK to render **authenticated** embedded charts, specifically via a custom jwt authentication. The sample app has its own authentication and token issuing logic. You may want to follow a similar approach if you are not integrating with an external authentication mechanism or your authentication is not based on JWTs. Alternatively, if you are using an existing authentication mechanism that issues JWTs, you can use those tokens to authenticate your chart rendering requests after configuring a Charts authentication provider that can validate the JWT. + +#include "examples/.markdown/docs/chart/authenticated-common-features.md" +- 🔑 Custom JWT authentication via `jsonwebtoken` + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" Along with this, a local jwt authentication server will be spun up on `http://localhost:8000`. + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md" + + - Name: `Custom JWT` _Note, this is only for your convenience and can be named anything_ + - Provider: `Custom JSON Web Token` + - Signing Algorithm: `HS256` _Note, this is the default signing algorithm for the `jsonwebtoken` library and many others_ + - Signing Key: `topsecret` _Note, this key must correlate with the key found in `config.js`_ + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" + +The hard coded credentials used in this demo are: + +- Username: `admin` +- Password: `password` + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Change the login logic to adapt to your project's security workflow. +- Think whether an authenticated chart is the feature you're after. If you're simply looking for a way to show off your data, [unauthenticated embedding](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated) simplifies the workflow even further. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/authenticated-google.md b/examples/.markdown/config/chart/authenticated-google.md new file mode 100644 index 0000000..19ca729 --- /dev/null +++ b/examples/.markdown/config/chart/authenticated-google.md @@ -0,0 +1,61 @@ +# MongoDB Charts Embedding Example - Google Authentication + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +This sample shows how to use the JavaScript Embedding SDK to render **authenticated** embedded charts, specifically via configuring **Google** as an authentication provider. The sample app is already set up to authenticate with a Google Client ID hosted by the Charts Development team. + +#include "examples/.markdown/docs/chart/authenticated-common-features.md" +- 𝗚 Google authentication + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. + +Logging in with any valid Google account will allow you to render the chart. + +## Getting a Google Client ID + +This sample is pre-configured with a MongoDB-owned test Client ID. To use Google Sign-In in your own apps, you must create your own Client ID. + +Steps on how to configure a Project with Google and attain a Google Client ID can be found [here](https://developers.google.com/identity/sign-in/web/sign-in). You'll need to set the Origin and Redirect URIs to whatever you use in your application. In our sample, that is http://localhost:3000. + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md" + + - Name: `Google` _Note, this is only for your convenience and can be named anything you want here_ + - Provider: `Google` + - Google Client ID: _See above for + - This should be the entire string `.apps.googleusercontent.com` + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" +- **Optional:** Replace the `` with your own Google Client ID. (look for "\~REPLACE\~" in the comments) + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Use Incognito Mode to see a pure login experience +- Consider how you want to secure your data with the Google Embedding Provider. Anybody can create a Google account. Consider using Charts Injected Filters to make your application more secure. + + - For example, consider the following injected filter + + ```javascript + // Reject tokens that aren't from example.com domain + if (context.token.hd != "yourCompany.com") { + return false; + } + return true; + ``` + + - ![Screen Shot 2020-04-21 at 1 47 54 pm](https://user-images.githubusercontent.com/19422770/79823279-b9b35880-83d6-11ea-8370-774bcde80252.png) + - This will only allow users from your company domain to view the chart data 🔒 + +- Think whether an authenticated chart is the feature you're after. If you're simply looking for a way to show off your data, [unauthenticated embedding](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated) simplifies the workflow even further. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/authenticated-realm-deprecated.md b/examples/.markdown/config/chart/authenticated-realm-deprecated.md new file mode 100644 index 0000000..0ee97ec --- /dev/null +++ b/examples/.markdown/config/chart/authenticated-realm-deprecated.md @@ -0,0 +1,49 @@ +# MongoDB Charts Embedding Example - App Services Authentication [DEPRECATED] + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-deprecated)_ + +> ## :rotating_light: The [`mongodb-stitch-browser-sdk`](https://www.npmjs.com/package/mongodb-stitch-browser-sdk) package is now deprecated. Please use [`realm-web`](https://www.npmjs.com/package/realm-web) instead and follow the [authenticated-realm-web](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-web) example. + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +This sample shows how to use the JavaScript Embedding SDK to render **authenticated** embedded charts, specifically via configuring **Atlas App Services** as an authentication provider. The sample app is already set up to authenticate with an App Services application hosted by the Charts Development team. + +This sample also demonstrates data filtering by role, thanks to the App Services Rules system. See more details [here](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/). Simply login with either `australianEmployee@mongodb.com` or `canadianEmployee@mongodb.com`, and take note of the different results! + +#include "examples/.markdown/docs/chart/authenticated-common-features.md" +- 🔑 App Services authentication +- 🙋‍♂️ Data filtering by App Services User Role + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/realm-credentials.md" + +## Authenticate with your App Services App + +#include "examples/.markdown/docs/chart/realm-app-preparation-steps.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-authentication-provider-realm.md" + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" +- Replace the Realm `AppClientID` string with the base URL for your App Services app (look for "\~REPLACE\~" in the comments) +- Replace the Stitch App ID in the Stitch Constructor, and remove the base URL. `Stitch.initializeAppClient('')` + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Play with App Services Rules system, and change how different accounts see your Chart. +- Think whether an authenticated chart is the feature you're after. If you're simply looking for a way to show off your data, [unauthenticated embedding](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated) simplifies the workflow even further. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/authenticated-realm-web.md b/examples/.markdown/config/chart/authenticated-realm-web.md new file mode 100644 index 0000000..24b84bb --- /dev/null +++ b/examples/.markdown/config/chart/authenticated-realm-web.md @@ -0,0 +1,46 @@ +# MongoDB Charts Embedding Example - App Services Authentication + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-web)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +This sample shows how to use the JavaScript Embedding SDK to render **authenticated** embedded charts, specifically via configuring **Atlas App Services** as an authentication provider. The sample app is already set up to authenticate with an App Services application hosted by the Charts Development team. + +This sample also demonstrates data filtering by role, thanks to the App Services Rules system. See more details [here](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/). Simply login with either `australianEmployee@mongodb.com` or `canadianEmployee@mongodb.com`, and take note of the different results! + +#include "examples/.markdown/docs/chart/authenticated-common-features.md" +- 🔑 App Services authentication +- 🙋‍♂️ Data filtering by App Services User Role + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/realm-credentials.md" + +## Authenticate with your App Services App + +#include "examples/.markdown/docs/chart/realm-app-preparation-steps.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-authentication-provider-realm.md" + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" +- Replace the Realm App ID string. `Realm.App({id: ''})` + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Play with App Services Rules system, and change how different accounts see your Chart. +- Think whether an authenticated chart is the feature you're after. If you're simply looking for a way to show off your data, [unauthenticated embedding](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated) simplifies the workflow even further. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/click-events-basic.md b/examples/.markdown/config/chart/click-events-basic.md new file mode 100644 index 0000000..11abdbf --- /dev/null +++ b/examples/.markdown/config/chart/click-events-basic.md @@ -0,0 +1,94 @@ +# MongoDB Charts Embedding Example - Click Events + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +#include "examples/.markdown/docs/chart/click-events-description.md" + +This sample shows the basics of how to subscribe to and handle click events, including extracting relevant details about the chart elmement that was clicked. You can also see a more advanced demo that demonstrates [interactive filtering](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering). + +#### The features included in this demo are as follows: + +- Adding a click event handler to a chart, using code similar to: + +```javascript +chart.addEventListener("click", callback); +``` + +- Highlighting the element clicked on the chart, using the following code: + +```javascript +chart.setHighlight(payload.selectionFilter) +``` + +- Parsing the payload returned to the callback event. A typical click event's payload will look something like this: + +```json +{ + "chartId": "c0774a27-3432-4207-b795-afeb56243652", + "event": { + "type": "click", + "altKey": false, + "ctrlKey": false, + "shiftKey": false, + "metaKey": false, + "offsetX": 152, + "offsetY": 176, + "clientX": 172, + "clientY": 241, + "pageX": 172, + "pageY": 241, + "screenX": 172, + "screenY": 312 + }, + "data": { + "y": { + "label": "unwind array 'genres'", + "value": "Adventure" + }, + "x": { + "label": "count ( _id )", + "value": 659 + }, + "color": { + "label": "year", + "value": "2000 - 2010", + "lowerBound": 2000, + "upperBound": 2010 + } + }, + "target": { + "type": "rect", + "role": "mark", + "fill": "#8CB6F2" + }, + "apiVersion": 1 +} +``` + +More information regarding how to handle click events can be found in the [Charts documentation](https://docs.mongodb.com/charts/saas/handle-click-events/). + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md" + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Embed multiple charts, and use the click events to filter one chart based on the click events detected on the other. This is demonstrated in our + [interactive filtering](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering) example. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/click-events-filtering.md b/examples/.markdown/config/chart/click-events-filtering.md new file mode 100644 index 0000000..a06a0ca --- /dev/null +++ b/examples/.markdown/config/chart/click-events-filtering.md @@ -0,0 +1,47 @@ +# MongoDB Charts Embedding Example - Interactive Filtering + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +#include "examples/.markdown/docs/chart/click-events-description.md" + +This sample shows how to implement interactive filtering, whereby clicks on one chart are used to generate filters which are applied to a second chart. To learn the basics of chart click events, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. + +More information regarding how to handle click events can be found in the [Charts documentation](https://docs.mongodb.com/charts/saas/handle-click-events/). + +#### The features included in this demo are as follows: + +- Adding a click event handler to a chart, using code similar to: + +```javascript +chart.addEventListener("click", callback, options); +``` + +- Adding an option to make just certain parts of the chart clickable (in this case only the bars) +- Obtaining an MQL filter document based on the data returned in the payload using `selectionFilter` +- Highlighting the clicked element on the first chart using `setHighlight` +- Filtering a second chart using the `setFilter` method + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md" + +11. In the same menu, note the **User Specified Filters** option. If you wish to try out filtering on your own dataset, you will need to whitelist a field by which to filter on. For example, our sample Movies dataset filters on `year` and `genres`. + + Furthermore, the filter related code in `src/index.js` will need to be updated to conform to the filter query you wish to apply. + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" +- Replace the filter in the `addEventListener` callback with a suitable filter document for your chart + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/programmatic-highlighting.md b/examples/.markdown/config/chart/programmatic-highlighting.md new file mode 100644 index 0000000..68bda5a --- /dev/null +++ b/examples/.markdown/config/chart/programmatic-highlighting.md @@ -0,0 +1,39 @@ +# MongoDB Charts Embedding Example - Programmatic Highlighting + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/programmatic-highlighting)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +When you embed charts using the Embedding SDK, you are able to customise the embedded charts by setting attributes. One of these is `setHighlight()`, which lets you emphasise part of your charts to attract attention. This feature adds a layer of richness to interactive charts, and can be used to show relationships between charts. To learn the basics of interactive charts, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. To learn about other properties you can use to customise your charts, please refer to the [API documentation](https://www.npmjs.com/package/@mongodb-js/charts-embed-dom). + +More information regarding charts highlighting can be found in the [Charts documentation](https://docs.mongodb.com/charts/saas/handle-click-events/). + +#### The features included in this demo are as follows: + +- Adding chart highlighting: + +```javascript +chart.setHighlight({ field: { $expr }}); +``` + +- Highlighting two charts (one bar, one table) at the same time with the same filter expression +- Showing more complicated MQL filters with the drop down +- Allow custom filtering expressions by editing the textarea + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md" + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/timeline-charts-example.md b/examples/.markdown/config/chart/timeline-charts-example.md new file mode 100644 index 0000000..3b0b866 --- /dev/null +++ b/examples/.markdown/config/chart/timeline-charts-example.md @@ -0,0 +1,45 @@ +# MongoDB Charts Embedding Example - Timeline Chart + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/timeline-charts-example)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +The example code in this directory is building a small react app, implementing a chart timeline using the Charts Embedding SDK. + +What the application is doing is showing the distribution of Olympic medals through the years. + +![timeline-retina-960x438-500ms](https://user-images.githubusercontent.com/51065986/89610627-5df5d800-d8be-11ea-954b-6d92086d9f58.gif) + +We are using a [filter](https://docs.mongodb.com/charts/saas/filter-embedded-charts/#filter-data-on-charts-embedded-with-the-sdk) on the Olympic year, changing the filter every few seconds to turn it into a timelapse. + +The idea is this - for every Olympic year we are filtering all data from the beginning of the Olympic games to the current year. + +Example: + +- First Olympic Year: in this case it's just the data for the first year +- Second Olympic Year: all data from First Olympic Year to Second Olympic Year +- Third Olympic Year: all data from First Olympic Year to Third Olympic Year +- .... +- Last Olympic Year: all data from First Olympic Year to Last Olympic Year, which in this case is all the data + +The idea of doing this application was to show you some interactivity you can accomplish with the embedding SDK. +Doing timeline charts is not really a feature of the embedding SDK but it shows you that with a little bit of code you can do different things with your charts. + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md" Ensure you have whitelisted all the fields you want to use filters for. + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" +- Change the filter to whatever makes sense for your project. Currently the filter gets the data between two years and is using the "Year" field for filtering. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/chart/unauthenticated.md b/examples/.markdown/config/chart/unauthenticated.md new file mode 100644 index 0000000..f18e304 --- /dev/null +++ b/examples/.markdown/config/chart/unauthenticated.md @@ -0,0 +1,50 @@ +# MongoDB Charts Embedding Example - Unauthenticated Embedded Chart + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated)_ + +## Background + +#include "examples/.markdown/docs/chart/embed-sdk-introduction.md" + +This sample shows how to use the JavaScript Embedding SDK to render unauthenticated embedded charts, along with showing off the various ways your application can interact with charts using the SDK. + +#### The features included in this demo are as follows: + +- Render an embedded chart on a web page +- Set the charts theme to either `'light'` or `'dark'` +- Get the charts current theme +- Set the charts max data age to various values +- Get the charts current max data age +- Manually refresh the chart +- Set the charts current filter + - Note, filtering on a chart requires setting up white listed fields in MongoDB Charts. We have done this for our sample data. +- Get the current filter on a chart + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +## Preparing your Chart for Embedding + +#include "examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md" + +#include "examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md" + +11. **Optional** + In the same menu, note the **User Specified Filters** option. If you wish to try out filtering on your own dataset, you will need to whitelist a field by which to filter on. For example, our sample AirBnB dataset filters on `address.country`. + + Furthermore, the filter related code in `src/index.js` will need to be updated to conform to the filter query you wish to run, and the options provided in `index.html` will need to be updated too. To be clear, + - Update the query **field** in `src/index.js` + - Update the query **values** in `index.html` + +## Running this Sample with your data + +#include "examples/.markdown/docs/chart/using-own-data-general-steps.md" + +## Next Steps + +#include "examples/.markdown/docs/chart/next-steps-common-text.md" +- Think whether an unauthenticated chart is the feature you're after. [Embedding iframes](https://docs.mongodb.com/charts/master/embedded-chart-options/) from Charts is a great way to showcase your data if you don't need the user to interact with the chart. +- Consider the data you're making available, and the queries you're allowing. If the data is sensitive and you need to ensure the charts can only be accessed by authorized people, you should look at using authenticated embedding. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/authenticated-custom-jwt.md b/examples/.markdown/config/dashboard/authenticated-custom-jwt.md new file mode 100644 index 0000000..2a4b793 --- /dev/null +++ b/examples/.markdown/config/dashboard/authenticated-custom-jwt.md @@ -0,0 +1,18 @@ +# MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (Custom JWT) + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an authenticated dashboard embedded onto your application using Custom JWT as the authentication provider. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/authenticated-common-features.md" +- Custom JWT authentication via the `jsonwebtoken` package + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/authenticated-google.md b/examples/.markdown/config/dashboard/authenticated-google.md new file mode 100644 index 0000000..7ecb0ec --- /dev/null +++ b/examples/.markdown/config/dashboard/authenticated-google.md @@ -0,0 +1,21 @@ +# MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (Google Auth) + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an authenticated dashboard embedded onto your application using Google as the authentication provider. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/authenticated-common-features.md" +- Integrate Google Sign-In to authenticate users + - You can follow [this tutorial](https://developers.google.com/identity/sign-in/web/sign-in) for more details + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. + +Logging in with any valid Google account will allow you to render the chart. + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/authenticated-realm-deprecated.md b/examples/.markdown/config/dashboard/authenticated-realm-deprecated.md new file mode 100644 index 0000000..6800b45 --- /dev/null +++ b/examples/.markdown/config/dashboard/authenticated-realm-deprecated.md @@ -0,0 +1,25 @@ +# MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (Realm) [DEPRECATED] + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-deprecated)_ + +> ## :rotating_light: The [`mongodb-stitch-browser-sdk`](https://www.npmjs.com/package/mongodb-stitch-browser-sdk) package is now deprecated. Please use [`realm-web`](https://www.npmjs.com/package/realm-web) instead and follow the [authenticated-realm-web](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-web) example. + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an authenticated dashboard embedded onto your application using App Services as the authentication provider. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/authenticated-common-features.md" +- App Services authentication +- Data filtering by App Services User Role + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/realm-credentials.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/authenticated-realm-web.md b/examples/.markdown/config/dashboard/authenticated-realm-web.md new file mode 100644 index 0000000..a8cf379 --- /dev/null +++ b/examples/.markdown/config/dashboard/authenticated-realm-web.md @@ -0,0 +1,23 @@ +# MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (App Services) + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-web)_ + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an authenticated dashboard embedded onto your application using App Services as the authentication provider. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/authenticated-common-features.md" +- Use App Services authentication +- Data filtering by App Services User Role + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/realm-credentials.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/unauthenticated-get-chart.md b/examples/.markdown/config/dashboard/unauthenticated-get-chart.md new file mode 100644 index 0000000..3398c12 --- /dev/null +++ b/examples/.markdown/config/dashboard/unauthenticated-get-chart.md @@ -0,0 +1,24 @@ +# MongoDB Charts Embedding Example - Unauthenticated Embedded Dashboard with `getChart` and `getAllCharts` methods + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated-get-chart)_ + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an unauthenticated dashboard embedded onto your application and retrieve all or just one chart on a dashboard. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/unauthenticated-common-features.md" +- Manually refresh the dashboard (Refresh all charts within a dashboard) +- Get all the charts that are rendered on a dashboard via the SDK +- Manually refresh a chart instance that you have specified +- Adding/Removing click event listeners to a specific chart instance that you have specified +- Viewing the payload for a click event + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/config/dashboard/unauthenticated.md b/examples/.markdown/config/dashboard/unauthenticated.md new file mode 100644 index 0000000..76d41d1 --- /dev/null +++ b/examples/.markdown/config/dashboard/unauthenticated.md @@ -0,0 +1,24 @@ +# MongoDB Charts Embedding Example - Unauthenticated Embedded Dashboard + +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated)_ + +## Background + +#include "examples/.markdown/docs/dashboard/embed-sdk-introduction.md" + +This example, demonstrates how you might render an unauthenticated dashboard embedded onto your application via the SDK. If you don't want to use the SDK but want an easier way to render your dashboard, you can use an [embedded iframe](https://dochub.mongodb.org/core/charts-embedding-dashboards-iframe) instead. + +## Highlighted features + +#include "examples/.markdown/docs/dashboard/unauthenticated-common-features.md" +- Manually refresh the dashboard (Refresh all charts within a dashboard) +- Set the whole dashboard theme to `'light'` or `'dark'` +- Set background colour of all charts shown on the dashboard. Note that this will overwrite the colour that has been set by the current theme +- Set the max data age of a chart on a dashboard +- Set the height and width mode to `'fixed'` or `'scale'`. + +## Quickstart + +#include "examples/.markdown/docs/quickstart.md" + +#include "examples/.markdown/docs/footer.md" \ No newline at end of file diff --git a/examples/.markdown/docs/chart/authenticated-common-features.md b/examples/.markdown/docs/chart/authenticated-common-features.md new file mode 100644 index 0000000..956b34e --- /dev/null +++ b/examples/.markdown/docs/chart/authenticated-common-features.md @@ -0,0 +1,4 @@ +#### The features included in this demo are as follows: + +- 📈 Render an embedded chart on a web page +- 🔒 Only render charts to valid users \ No newline at end of file diff --git a/examples/.markdown/docs/chart/chart-preparation-steps/create-authentication-provider-realm.md b/examples/.markdown/docs/chart/chart-preparation-steps/create-authentication-provider-realm.md new file mode 100644 index 0000000..6fc2f13 --- /dev/null +++ b/examples/.markdown/docs/chart/chart-preparation-steps/create-authentication-provider-realm.md @@ -0,0 +1,15 @@ + - Name: `App Services Auth Provider` _Note, this is only for your convenience and can be named anything_ + - Provider: `Atlas App Services` + - Atlas Project: Select the Atlas project that contains the App Services Application you configured in the previous steps + - App ID: Select the ID of the App Services App you configured in the previous steps + +13. Click "Save" + + **Optional** + + - Turn on "Fetch data using App Services". + - This option should be turned on when you wish to delegate data fetching logic to your App. Specifically, if you have configured App Services Rules that apply to the users that are being authenticated, and you wish to have these rules enforced before the chart is rendered, turn this setting on. + - This setting should be left off if you only require App Services to authenticate valid users, and you have no desire to filter data by their role in your App. i.e, all valid users see the same chart, invalid users cannot see the chart. + - Enter the Service name that retrieves your data. To find the name of this, + - Navigate to "Linked Data Sources" on the left hand navigation panel. + - Look for the "Service Name" associated with your deployment. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md b/examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md new file mode 100644 index 0000000..a780ddd --- /dev/null +++ b/examples/.markdown/docs/chart/chart-preparation-steps/create-chart-to-embed.md @@ -0,0 +1,7 @@ +This sample is preconfigured to render a specific chart. You can run the sample as-is, or you can modify it to render your own chart by completing the following steps: + +### Create chart to embed + +1. Log onto MongoDB Charts. + +2. If you haven't done so already, create a chart on any dashboard that you would like to embed. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md b/examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md new file mode 100644 index 0000000..00d8e07 --- /dev/null +++ b/examples/.markdown/docs/chart/chart-preparation-steps/enable-authenticated-access.md @@ -0,0 +1,25 @@ +### Enable data source for authenticated access + +3. Go to the Data Sources tab found on the side panel. + +4. Find the data source that you want to use on the chart by selecting the deployment, database and collection. Once found, click on the Manage button in the Data access section to access the Data source management page. + +5. Make sure the "External users can view data in this data source" option is toggled on and "Allow authenticated data access" has been selected. + +### Enable chart for embedded access + +6. Go to the **Dashboards** tab on the side panel, and select the dashboard that contains the chart you wish to embed. + +7. Find the chart you want to embed, click the **...** menu and select **Embed chart**. + +8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**'. + +9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. + +### Create authentication provider + +10. Go to the Embedding tab on the side panel. + +11. Ensure the **Authentication Settings** tab is selected and press the **Add** button in the **Authentication providers** section. + +12. Fill in the details like so: \ No newline at end of file diff --git a/examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md b/examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md new file mode 100644 index 0000000..2130732 --- /dev/null +++ b/examples/.markdown/docs/chart/chart-preparation-steps/enable-unauthenticated-access.md @@ -0,0 +1,19 @@ +### Enable data source for unauthenticated access + +3. Go to the Data Sources tab found on the side panel. + +4. Find the data source that you want to use on the chart by selecting the deployment, database and collection. Once found, click on the Manage button in the Data access section to access the Data source management page. + +5. Make sure the "External users can view data in this data source" option is toggled on and "Allow unauthenticated data access" has been selected. + +6. Go to the Data Sources tab, find the data source that you are using on the chart, and choose External Sharing Options from the ... menu. Make sure that embedding is enabled for this data source and select '**Unauthenticated or Verified Signature**' + +### Enable chart for embedded access + +7. Find the chart you want to embed, click the **...** menu and select **Embed chart** + +8. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' + +9. Select the **Javascript SDK** option + +10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/click-events-description.md b/examples/.markdown/docs/chart/click-events-description.md new file mode 100644 index 0000000..eada4ab --- /dev/null +++ b/examples/.markdown/docs/chart/click-events-description.md @@ -0,0 +1 @@ +When you embed charts using the Embedding SDK, you are able to subscribe to events that show when a user clicked on a chart, and the details of the element on which they clicked. This feature can be used to build interactive charts. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/embed-sdk-introduction.md b/examples/.markdown/docs/chart/embed-sdk-introduction.md new file mode 100644 index 0000000..c9228cf --- /dev/null +++ b/examples/.markdown/docs/chart/embed-sdk-introduction.md @@ -0,0 +1,5 @@ +📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ + +MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. + +Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). \ No newline at end of file diff --git a/examples/.markdown/docs/chart/next-steps-common-text.md b/examples/.markdown/docs/chart/next-steps-common-text.md new file mode 100644 index 0000000..82fc10e --- /dev/null +++ b/examples/.markdown/docs/chart/next-steps-common-text.md @@ -0,0 +1,3 @@ +Once you gain an understanding of the API, consider the following + +- Take on the optional steps to prepare and manipulate your own data source rather than the sample. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/realm-app-preparation-steps.md b/examples/.markdown/docs/chart/realm-app-preparation-steps.md new file mode 100644 index 0000000..72e44e6 --- /dev/null +++ b/examples/.markdown/docs/chart/realm-app-preparation-steps.md @@ -0,0 +1,32 @@ +This sample is preconfigured to render, and more specifically, **authenticate** users who are verified to view a specific chart. You can run the sample as-is, or you can modify it to render and authenticate your own chart by completing the following steps: + +### Prepare your App Services App + +Choose or create an App which will be used to authenticate users who wish to view your chart. + +1. Log onto Atlas App Services + + - Create App Services App if you haven't already + +2. Click on Users on the left navigation column + +3. Click on Providers + +4. Set up a provider, or utilise and existing one. One of the easiest providers to setup is Email/Password + + 1. Click on Edit for the Email/Password Provider + 2. Enable the Provider + 3. Set User Confirmation to automatically confirm users + 4. Set Password Reset to send a reset email + 1. Set the reset URL to `http://localhost` + 2. You can also do this for confirming users if you prefer + 5. Save these settings. + 6. Deploy these changes + +5. Click the Users tab +6. Click Add New User +7. Fill out the new User details + +### Optionally, Prepare your Dataset + +If you want to use your App to filter data for each user, (Like we have done in our sample) set up an [Atlas service](https://www.mongodb.com/cloud/atlas) and corresponding [Rules](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/) that filter the data as desired. Injected Filters and [Dashboard filtering](https://www.mongodb.com/blog/post/filter-your-dashboards-with-mongodb-charts) are other Charts features one can use to attain similar functionality. \ No newline at end of file diff --git a/examples/.markdown/docs/chart/using-own-data-general-steps.md b/examples/.markdown/docs/chart/using-own-data-general-steps.md new file mode 100644 index 0000000..a293c10 --- /dev/null +++ b/examples/.markdown/docs/chart/using-own-data-general-steps.md @@ -0,0 +1,4 @@ +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. + +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) \ No newline at end of file diff --git a/examples/.markdown/docs/dashboard/authenticated-common-features.md b/examples/.markdown/docs/dashboard/authenticated-common-features.md new file mode 100644 index 0000000..8cffed1 --- /dev/null +++ b/examples/.markdown/docs/dashboard/authenticated-common-features.md @@ -0,0 +1,6 @@ +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ + +In this example, you should be able to: + +- Render an authenticated embedded dashboard +- Render a dashboard to valid users only \ No newline at end of file diff --git a/examples/.markdown/docs/dashboard/embed-sdk-introduction.md b/examples/.markdown/docs/dashboard/embed-sdk-introduction.md new file mode 100644 index 0000000..2082b9e --- /dev/null +++ b/examples/.markdown/docs/dashboard/embed-sdk-introduction.md @@ -0,0 +1,3 @@ +📄 _[See the MongoDB Charts Embedding Docs for more details](https://dochub.mongodb.org/core/charts-embedding-dashboards)_ + +The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard directly into your application. Just like embedded charts, you can embed a dashboard via unauthenticated or an authenticated method. \ No newline at end of file diff --git a/examples/.markdown/docs/dashboard/unauthenticated-common-features.md b/examples/.markdown/docs/dashboard/unauthenticated-common-features.md new file mode 100644 index 0000000..41202a0 --- /dev/null +++ b/examples/.markdown/docs/dashboard/unauthenticated-common-features.md @@ -0,0 +1,5 @@ +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ + +In this example, you should be able to: + +- Render an unauthenticated embedded dashboard \ No newline at end of file diff --git a/examples/.markdown/docs/footer.md b/examples/.markdown/docs/footer.md new file mode 100644 index 0000000..acf77ff --- /dev/null +++ b/examples/.markdown/docs/footer.md @@ -0,0 +1 @@ +Happy Charting! 🚀 📈 diff --git a/examples/.markdown/docs/quickstart.md b/examples/.markdown/docs/quickstart.md new file mode 100644 index 0000000..f67abf8 --- /dev/null +++ b/examples/.markdown/docs/quickstart.md @@ -0,0 +1,12 @@ +_The following steps presume the use of npm, though yarn works as well._ + +1. Ensure you have Node installed. You can confirm with `node --version`. On some operating systems, Node is available as the `nodejs` binary instead. + +2. Clone the Git repository or download the code to your computer. + +3. Run `npm install` to install the package dependencies. + +4. Run `npm start` to start the application. This will utilise parcel.js. + - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is + +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. \ No newline at end of file diff --git a/examples/.markdown/docs/realm-credentials.md b/examples/.markdown/docs/realm-credentials.md new file mode 100644 index 0000000..9ec12c7 --- /dev/null +++ b/examples/.markdown/docs/realm-credentials.md @@ -0,0 +1,13 @@ +The two hard coded credentials used in this demo are: + +``` +username: australianEmployee@mongodb.com +password: password +``` + +``` +username: canadianEmployee@mongodb.com +password: password +``` + +And they will display localised data thanks to the configured App Services User Roles. \ No newline at end of file diff --git a/examples/charts/authenticated-custom-jwt/README.md b/examples/charts/authenticated-custom-jwt/README.md index 4e2207f..b9446a8 100644 --- a/examples/charts/authenticated-custom-jwt/README.md +++ b/examples/charts/authenticated-custom-jwt/README.md @@ -20,15 +20,17 @@ This sample shows how to use the JavaScript Embedding SDK to render **authentica _The following steps presume the use of npm, though yarn works as well._ -1. Ensure you have Node installed. You can confirm with `node --version`. On some operating systems, Node available as the `nodejs` binary instead. +1. Ensure you have Node installed. You can confirm with `node --version`. On some operating systems, Node is available as the `nodejs` binary instead. 2. Clone the Git repository or download the code to your computer. 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. Along with this, a local jwt authentication server will be spun up on `http://localhost:8000`. + ## Preparing your Chart for Embedding This sample is preconfigured to render a specific chart. You can run the sample as-is, or you can modify it to render your own chart by completing the following steps: @@ -49,43 +51,37 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Enable chart for embedded access -6. Go to the Dashboards tab on the side panel, and select the dashboard that contains the chart you wish to embed. - -7. Click the **...** menu and select **Embed chart**. +6. Go to the **Dashboards** tab on the side panel, and select the dashboard that contains the chart you wish to embed. -8. Ensure the Authenticated tab is selected and turn on '**Enable authenticated access**'. +7. Find the chart you want to embed, click the **...** menu and select **Embed chart**. -9. Note the Chart ID and the Base URL, as you will need them for running the demo. +8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**'. -10. Close the menu. +9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. ### Create authentication provider -11. Go to the Embedding tab on the side panel. +10. Go to the Embedding tab on the side panel. -12. Ensure the "Authentication Settings" tab is selected and press the "Add" button in the Authentication providers section. +11. Ensure the **Authentication Settings** tab is selected and press the **Add** button in the **Authentication providers** section. -13. Fill in the details like so: +12. Fill in the details like so: -- Name: `Custom JWT` _Note, this is only for your convenience and can be named anything_ -- Provider: `Custom JSON Web Token` -- Signing Algorithm: `HS256` _Note, this is the default signing algorithm for the `jsonwebtoken` library and many others_ -- Signing Key: `topsecret` _Note, this key must correlate with the key found in `config.js`_ + - Name: `Custom JWT` _Note, this is only for your convenience and can be named anything_ + - Provider: `Custom JSON Web Token` + - Signing Algorithm: `HS256` _Note, this is the default signing algorithm for the `jsonwebtoken` library and many others_ + - Signing Key: `topsecret` _Note, this key must correlate with the key found in `config.js`_ ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - Open the _index.js_ file (`src/index.js`) - - Replace the `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu. (look for "\~REPLACE\~" in the comments) -2. Run `npm install` to install the package dependencies. -3. Run `npm start` to start the application. +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. Along with this, a local jwt authentication server will be spun up on `http://localhost:8000`. +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) The hard coded credentials used in this demo are: -- Username : `admin` +- Username: `admin` - Password: `password` ## Next Steps diff --git a/examples/charts/authenticated-google/README.md b/examples/charts/authenticated-google/README.md index 24dffc3..1c70836 100755 --- a/examples/charts/authenticated-google/README.md +++ b/examples/charts/authenticated-google/README.md @@ -26,10 +26,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:3000` in the url bar to see the sample. Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. Logging in with any valid Google account will allow you to render the chart. @@ -45,9 +45,9 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. -2. If you haven't done so already, create a chart you would like to embed on any dashboard. +2. If you haven't done so already, create a chart on any dashboard that you would like to embed. ### Enable data source for authenticated access @@ -59,11 +59,11 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Enable chart for embedded access -6. Go to the Dashboards tab on the side panel, and select the dashboard that contains the chart you wish to embed. +6. Go to the **Dashboards** tab on the side panel, and select the dashboard that contains the chart you wish to embed. -7. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart**. -8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**' +8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**'. 9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. @@ -71,26 +71,22 @@ This sample is preconfigured to render a specific chart. You can run the sample 10. Go to the Embedding tab on the side panel. -11. Ensure the "Authentication Settings" tab is selected and press the "Add" button in the Authentication providers section. +11. Ensure the **Authentication Settings** tab is selected and press the **Add** button in the **Authentication providers** section. -12. Go to the Admin Settings tab on the left navigation column. Under 'Embedding Authentication Providers', click 'Add New Provider'. +12. Fill in the details like so: -13. Fill in the details like so: - - - Name: `Google` _Note, this is only for your convenience and can be named anything you want here_ - - Provider: `Google` - - Google Client ID: _See above for - - This should be the entire string `.apps.googleusercontent.com` + - Name: `Google` _Note, this is only for your convenience and can be named anything you want here_ + - Provider: `Google` + - Google Client ID: _See above for + - This should be the entire string `.apps.googleusercontent.com` ## Running this Sample with your data -If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -- Open the `index.html` file -- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) -- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) -- **Optional** - - Replace the `` with your own Google Client ID. (look for "\~REPLACE\~" in the comments) +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- **Optional:** Replace the `` with your own Google Client ID. (look for "\~REPLACE\~" in the comments) ## Next Steps diff --git a/examples/charts/authenticated-realm-deprecated/README.md b/examples/charts/authenticated-realm-deprecated/README.md index 4de1198..78b2d69 100644 --- a/examples/charts/authenticated-realm-deprecated/README.md +++ b/examples/charts/authenticated-realm-deprecated/README.md @@ -1,27 +1,27 @@ # MongoDB Charts Embedding Example - App Services Authentication [DEPRECATED] +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-deprecated)_ + > ## :rotating_light: The [`mongodb-stitch-browser-sdk`](https://www.npmjs.com/package/mongodb-stitch-browser-sdk) package is now deprecated. Please use [`realm-web`](https://www.npmjs.com/package/realm-web) instead and follow the [authenticated-realm-web](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-web) example. ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-deprecated)_ - MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). This sample shows how to use the JavaScript Embedding SDK to render **authenticated** embedded charts, specifically via configuring **Atlas App Services** as an authentication provider. The sample app is already set up to authenticate with an App Services application hosted by the Charts Development team. -This sample also demonstrates data filtering by role, thanks to App Services Rules system. See more details [here](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/). Simply login with either `australianEmployee@mongodb.com` or `canadianEmployee@mongodb.com`, and take note of the different results! +This sample also demonstrates data filtering by role, thanks to the App Services Rules system. See more details [here](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/). Simply login with either `australianEmployee@mongodb.com` or `canadianEmployee@mongodb.com`, and take note of the different results! #### The features included in this demo are as follows: - 📈 Render an embedded chart on a web page - 🔒 Only render charts to valid users -- 🔑 Appp Serviecs authentication -- 🙋‍♂️ Data filtering by App Services User Role. +- 🔑 App Services authentication +- 🙋‍♂️ Data filtering by App Services User Role ## Quickstart @@ -33,10 +33,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. The two hard coded credentials used in this demo are: @@ -58,7 +58,7 @@ This sample is preconfigured to render, and more specifically, **authenticate** ### Prepare your App Services App -Choose or create a App which will be used to authenticate users who wish to view your chart. +Choose or create an App which will be used to authenticate users who wish to view your chart. 1. Log onto Atlas App Services @@ -87,15 +87,15 @@ Choose or create a App which will be used to authenticate users who wish to view If you want to use your App to filter data for each user, (Like we have done in our sample) set up an [Atlas service](https://www.mongodb.com/cloud/atlas) and corresponding [Rules](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/) that filter the data as desired. Injected Filters and [Dashboard filtering](https://www.mongodb.com/blog/post/filter-your-dashboards-with-mongodb-charts) are other Charts features one can use to attain similar functionality. -## Prepare MongoDB Charts +## Preparing your Chart for Embedding This sample is preconfigured to render a specific chart. You can run the sample as-is, or you can modify it to render your own chart by completing the following steps: -## Create chart to embed +### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. -2. If you haven't done so already, create a chart you would like to embed on any dashboard. +2. If you haven't done so already, create a chart on any dashboard that you would like to embed. ### Enable data source for authenticated access @@ -107,11 +107,11 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Enable chart for embedded access -6. Go to the Dashboards tab on the left navigation column, and select the dashboard that contains the chart you wish to embed. +6. Go to the **Dashboards** tab on the side panel, and select the dashboard that contains the chart you wish to embed. -7. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart**. -8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**' +8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**'. 9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. @@ -119,14 +119,14 @@ This sample is preconfigured to render a specific chart. You can run the sample 10. Go to the Embedding tab on the side panel. -11. Ensure the "Authentication Settings" tab is selected and press the "Add" button in the Authentication providers section. +11. Ensure the **Authentication Settings** tab is selected and press the **Add** button in the **Authentication providers** section. 12. Fill in the details like so: - - Name: `App Services Auth Provider` _Note, this is only for your convenience and can be named anything_ - - Provider: `Atlas App Services` - - Atlas Project: Select the Atlas project that contains the App Services Application you configured in the previous steps - - App ID: Select the ID of the App Services App you configured in the previous steps + - Name: `App Services Auth Provider` _Note, this is only for your convenience and can be named anything_ + - Provider: `Atlas App Services` + - Atlas Project: Select the Atlas project that contains the App Services Application you configured in the previous steps + - App ID: Select the ID of the App Services App you configured in the previous steps 13. Click "Save" @@ -141,12 +141,11 @@ This sample is preconfigured to render a specific chart. You can run the sample ## Running this Sample with your data -If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -- Open the _index.js_ file (`src/index.js`) +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) - Replace the Realm `AppClientID` string with the base URL for your App Services app (look for "\~REPLACE\~" in the comments) -- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) -- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - Replace the Stitch App ID in the Stitch Constructor, and remove the base URL. `Stitch.initializeAppClient('')` ## Next Steps diff --git a/examples/charts/authenticated-realm-web/README.md b/examples/charts/authenticated-realm-web/README.md index 2490baa..ddcf45b 100644 --- a/examples/charts/authenticated-realm-web/README.md +++ b/examples/charts/authenticated-realm-web/README.md @@ -1,11 +1,11 @@ # MongoDB Charts Embedding Example - App Services Authentication +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-web)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/authenticated-realm-web)_ - MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). @@ -19,7 +19,7 @@ This sample also demonstrates data filtering by role, thanks to the App Services - 📈 Render an embedded chart on a web page - 🔒 Only render charts to valid users - 🔑 App Services authentication -- 🙋‍♂️ Data filtering by App Services User Role. +- 🙋‍♂️ Data filtering by App Services User Role ## Quickstart @@ -31,10 +31,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. The two hard coded credentials used in this demo are: @@ -85,15 +85,15 @@ Choose or create an App which will be used to authenticate users who wish to vie If you want to use your App to filter data for each user, (Like we have done in our sample) set up an [Atlas service](https://www.mongodb.com/cloud/atlas) and corresponding [Rules](https://www.mongodb.com/docs/atlas/app-services/mongodb/define-roles-and-permissions/) that filter the data as desired. Injected Filters and [Dashboard filtering](https://www.mongodb.com/blog/post/filter-your-dashboards-with-mongodb-charts) are other Charts features one can use to attain similar functionality. -## Prepare MongoDB Charts +## Preparing your Chart for Embedding This sample is preconfigured to render a specific chart. You can run the sample as-is, or you can modify it to render your own chart by completing the following steps: ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. -2. If you haven't done so already, create a chart you would like to embed on any dashboard. +2. If you haven't done so already, create a chart on any dashboard that you would like to embed. ### Enable data source for authenticated access @@ -105,11 +105,11 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Enable chart for embedded access -6. Go to the Dashboards tab on the left navigation column, and select the dashboard that contains the chart you wish to embed. +6. Go to the **Dashboards** tab on the side panel, and select the dashboard that contains the chart you wish to embed. -7. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart**. -8. Ensure the **Authenticated** tab is selected and turn on '**Enable Authenticated access**' +8. Ensure the **Authenticated** tab is selected and turn on '**Enable authenticated access**'. 9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. @@ -117,14 +117,14 @@ This sample is preconfigured to render a specific chart. You can run the sample 10. Go to the Embedding tab on the side panel. -11. Ensure the "Authentication Settings" tab is selected and press the "Add" button in the Authentication providers section. +11. Ensure the **Authentication Settings** tab is selected and press the **Add** button in the **Authentication providers** section. 12. Fill in the details like so: - - Name: `App Services Auth Provider` _Note, this is only for your convenience and can be named anything_ - - Provider: `Atlas App Services` - - Atlas Project: Select the Atlas project that contains the App Services Application you configured in the previous steps - - App ID: Select the ID of the App Services App you configured in the previous steps + - Name: `App Services Auth Provider` _Note, this is only for your convenience and can be named anything_ + - Provider: `Atlas App Services` + - Atlas Project: Select the Atlas project that contains the App Services Application you configured in the previous steps + - App ID: Select the ID of the App Services App you configured in the previous steps 13. Click "Save" @@ -139,12 +139,11 @@ This sample is preconfigured to render a specific chart. You can run the sample ## Running this Sample with your data -If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -- Open the _index.js_ file (`src/index.js`) +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) - Replace the Realm App ID string. `Realm.App({id: ''})` -- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) -- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) ## Next Steps diff --git a/examples/charts/click-events-basic/README.md b/examples/charts/click-events-basic/README.md index a2b87fe..1acf02d 100644 --- a/examples/charts/click-events-basic/README.md +++ b/examples/charts/click-events-basic/README.md @@ -1,12 +1,18 @@ # MongoDB Charts Embedding Example - Click Events +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic)_ + ## Background -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic)_ +📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. -When you embed charts using the Embedding SDK, you are able to subscribe to events that show when a user clicked on a chart, and the details of the element on which they clicked. This feature can be used to build interactive charts. This sample shows the basics of how to subscribe to and handle click events, including extracting relevant details about the chart elmement that was clicked. You can also see a more advanced demo that demonstrates [interactive filtering](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering). +Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). + +When you embed charts using the Embedding SDK, you are able to subscribe to events that show when a user clicked on a chart, and the details of the element on which they clicked. This feature can be used to build interactive charts. + +This sample shows the basics of how to subscribe to and handle click events, including extracting relevant details about the chart elmement that was clicked. You can also see a more advanced demo that demonstrates [interactive filtering](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering). #### The features included in this demo are as follows: @@ -79,10 +85,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. ## Preparing your Chart for Embedding @@ -90,7 +96,7 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. 2. If you haven't done so already, create a chart on any dashboard that you would like to embed. @@ -102,31 +108,30 @@ This sample is preconfigured to render a specific chart. You can run the sample 5. Make sure the "External users can view data in this data source" option is toggled on and "Allow unauthenticated data access" has been selected. +6. Go to the Data Sources tab, find the data source that you are using on the chart, and choose External Sharing Options from the ... menu. Make sure that embedding is enabled for this data source and select '**Unauthenticated or Verified Signature**' + ### Enable chart for embedded access -6. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart** -7. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' +8. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' -8. Select the **Javascript SDK** option +9. Select the **Javascript SDK** option -9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. +10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - Open the _index.js_ file (`src/index.js`) - - Replace the `baseUrl` string on with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string on with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) -2. Run `npm install` to install the package dependencies. -3. Run `npm start` to launch the sample application +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) ## Next Steps Once you gain an understanding of the API, consider the following +- Take on the optional steps to prepare and manipulate your own data source rather than the sample. - Embed multiple charts, and use the click events to filter one chart based on the click events detected on the other. This is demonstrated in our [interactive filtering](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering) example. diff --git a/examples/charts/click-events-filtering/README.md b/examples/charts/click-events-filtering/README.md index 0e29985..352192f 100644 --- a/examples/charts/click-events-filtering/README.md +++ b/examples/charts/click-events-filtering/README.md @@ -1,12 +1,18 @@ # MongoDB Charts Embedding Example - Interactive Filtering +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering)_ + ## Background -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-filtering)_ +📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. -When you embed charts using the Embedding SDK, you are able to subscribe to events that show when a user clicked on a chart, and the details of the element on which they clicked. This feature can be used to build interactive charts. This sample shows how to implement interactive filtering, whereby clicks on one chart are used to generate filters which are applied to a second chart. To learn the basics of chart click events, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. +Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). + +When you embed charts using the Embedding SDK, you are able to subscribe to events that show when a user clicked on a chart, and the details of the element on which they clicked. This feature can be used to build interactive charts. + +This sample shows how to implement interactive filtering, whereby clicks on one chart are used to generate filters which are applied to a second chart. To learn the basics of chart click events, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. More information regarding how to handle click events can be found in the [Charts documentation](https://docs.mongodb.com/charts/saas/handle-click-events/). @@ -33,10 +39,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. ## Preparing your Chart for Embedding @@ -44,7 +50,7 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. 2. If you haven't done so already, create a chart on any dashboard that you would like to embed. @@ -74,16 +80,10 @@ This sample is preconfigured to render a specific chart. You can run the sample ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - - Open the _index.js_ file (`src/index.js`) - - Replace the `baseUrl` string on with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string on with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the filter in the `addEventListener` callback with a suitable filter document for your chart - -2. Run `npm install` to install the package dependencies. -3. Run `npm start` to launch the sample application +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the filter in the `addEventListener` callback with a suitable filter document for your chart Happy Charting! 🚀 📈 diff --git a/examples/charts/programmatic-highlighting/README.md b/examples/charts/programmatic-highlighting/README.md index 34c1d1b..2c30241 100644 --- a/examples/charts/programmatic-highlighting/README.md +++ b/examples/charts/programmatic-highlighting/README.md @@ -1,12 +1,16 @@ # MongoDB Charts Embedding Example - Programmatic Highlighting +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/programmatic-highlighting)_ + ## Background -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/programmatic-highlighting)_ +📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. -When you embed charts using the Embedding SDK, you ae able to customise the embedded charts by setting attributes. One of these is `setHighlight()`, which lets you emphasise part of your charts to attract attention. This feature adds a layer of richness to interactive charts, and can be used to show relationships between charts. To learn the basics of interactive charts, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. To learn about other properties you can use to customise your charts, please refer to the [API documentation](https://www.npmjs.com/package/@mongodb-js/charts-embed-dom). +Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). + +When you embed charts using the Embedding SDK, you are able to customise the embedded charts by setting attributes. One of these is `setHighlight()`, which lets you emphasise part of your charts to attract attention. This feature adds a layer of richness to interactive charts, and can be used to show relationships between charts. To learn the basics of interactive charts, see the [click events](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/charts/click-events-basic) sample. To learn about other properties you can use to customise your charts, please refer to the [API documentation](https://www.npmjs.com/package/@mongodb-js/charts-embed-dom). More information regarding charts highlighting can be found in the [Charts documentation](https://docs.mongodb.com/charts/saas/handle-click-events/). @@ -32,10 +36,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. ## Preparing your Chart for Embedding @@ -43,7 +47,7 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. 2. If you haven't done so already, create a chart on any dashboard that you would like to embed. @@ -55,27 +59,23 @@ This sample is preconfigured to render a specific chart. You can run the sample 5. Make sure the "External users can view data in this data source" option is toggled on and "Allow unauthenticated data access" has been selected. +6. Go to the Data Sources tab, find the data source that you are using on the chart, and choose External Sharing Options from the ... menu. Make sure that embedding is enabled for this data source and select '**Unauthenticated or Verified Signature**' + ### Enable chart for embedded access -6. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart** -7. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' +8. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' -8. Select the **Javascript SDK** option +9. Select the **Javascript SDK** option -9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. +10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - - Open the _index.js_ file (`src/index.js`) - - Replace the `baseUrl` string on with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string on with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - -2. Run `npm install` to install the package dependencies. -3. Run `npm start` to launch the sample application +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) Happy Charting! 🚀 📈 diff --git a/examples/charts/timeline-charts-example/README.md b/examples/charts/timeline-charts-example/README.md index e42c581..48aee70 100644 --- a/examples/charts/timeline-charts-example/README.md +++ b/examples/charts/timeline-charts-example/README.md @@ -1,10 +1,14 @@ # MongoDB Charts Embedding Example - Timeline Chart +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/timeline-charts-example)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/timeline-charts-example)_ +MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. + +Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). The example code in this directory is building a small react app, implementing a chart timeline using the Charts Embedding SDK. @@ -31,21 +35,24 @@ Doing timeline charts is not really a feature of the embedding SDK but it shows _The following steps presume the use of npm, though yarn works as well._ -1. Ensure you have Node installed. You can confirm with `node --version`. +1. Ensure you have Node installed. You can confirm with `node --version`. On some operating systems, Node is available as the `nodejs` binary instead. 2. Clone the Git repository or download the code to your computer. 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. It will open directly in the browser at this address `http://localhost:3000`. +4. Run `npm start` to start the application. This will utilise parcel.js. + - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is + +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. ## Preparing your Chart for Embedding -This sample is preconfigured to render specific charts. You can run the sample as-is, or you can modify it to render your own charts by completing the following steps: +This sample is preconfigured to render a specific chart. You can run the sample as-is, or you can modify it to render your own chart by completing the following steps: ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. 2. If you haven't done so already, create a chart on any dashboard that you would like to embed. @@ -57,24 +64,24 @@ This sample is preconfigured to render specific charts. You can run the sample a 5. Make sure the "External users can view data in this data source" option is toggled on and "Allow unauthenticated data access" has been selected. -### Enable chart for embedded access +6. Go to the Data Sources tab, find the data source that you are using on the chart, and choose External Sharing Options from the ... menu. Make sure that embedding is enabled for this data source and select '**Unauthenticated or Verified Signature**' -6. Find the chart you want to embed, click the **(...)** menu and select **Embed chart** +### Enable chart for embedded access -7. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' +7. Find the chart you want to embed, click the **...** menu and select **Embed chart** -8. Ensure that you whitelist all fields that you want to use filters for. +8. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' 9. Select the **Javascript SDK** option -10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. +10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. Ensure you have whitelisted all the fields you want to use filters for. ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - Open the _Dashboard.jsx_ file (`src/Dashboard.jsx`) - - Replace the `baseUrl` string on with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string on with the chart ID you copied from the MongoDB Charts Embedded Chart menu. The example code shows 2 charts. (look for "\~REPLACE\~" in the comments) - - Change the filter to whatever makes sense for your project. Currently the filter gets the data between two years and is using the "Year" field for filtering. +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. + +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Change the filter to whatever makes sense for your project. Currently the filter gets the data between two years and is using the "Year" field for filtering. Happy Charting! 🚀 📈 diff --git a/examples/charts/unauthenticated/README.md b/examples/charts/unauthenticated/README.md index f693c3b..0925a6c 100644 --- a/examples/charts/unauthenticated/README.md +++ b/examples/charts/unauthenticated/README.md @@ -1,11 +1,11 @@ # MongoDB Charts Embedding Example - Unauthenticated Embedded Chart +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://docs.mongodb.com/charts/saas/embedding-charts/)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/charts/unauthenticated)_ - MongoDB Charts allows you to create visualizations of your MongoDB data using a simple web interface. You can view the visualizations within the Charts UI, or you can use the Embedding feature to render the charts in an external web application. Charts can be embedded either using a simple IFRAME snippet, or by using the Charts Embedding SDK from your JavaScript code. When using the SDK, embedded charts can be either unauthenticated (meaning anyone who has access to the page where the chart is embedded can view the chart), or authenticated (whereby the user can only view the chart if they have an active authentication session linked to a Charts authentication provider). @@ -34,10 +34,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. ## Preparing your Chart for Embedding @@ -45,7 +45,7 @@ This sample is preconfigured to render a specific chart. You can run the sample ### Create chart to embed -1. Log onto MongoDB Charts +1. Log onto MongoDB Charts. 2. If you haven't done so already, create a chart on any dashboard that you would like to embed. @@ -57,17 +57,19 @@ This sample is preconfigured to render a specific chart. You can run the sample 5. Make sure the "External users can view data in this data source" option is toggled on and "Allow unauthenticated data access" has been selected. +6. Go to the Data Sources tab, find the data source that you are using on the chart, and choose External Sharing Options from the ... menu. Make sure that embedding is enabled for this data source and select '**Unauthenticated or Verified Signature**' + ### Enable chart for embedded access -6. Find the chart you want to embed, click the **...** menu and select **Embed chart** +7. Find the chart you want to embed, click the **...** menu and select **Embed chart** -7. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' +8. Ensure the **Unauthenticated** tab is selected and turn on '**Enable unauthenticated access**' -8. Select the **Javascript SDK** option +9. Select the **Javascript SDK** option -9. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. +10. Note the **Chart ID** and the **Base URL**, as you will need them for running the demo. -10. **Optional** +11. **Optional** In the same menu, note the **User Specified Filters** option. If you wish to try out filtering on your own dataset, you will need to whitelist a field by which to filter on. For example, our sample AirBnB dataset filters on `address.country`. Furthermore, the filter related code in `src/index.js` will need to be updated to conform to the filter query you wish to run, and the options provided in `index.html` will need to be updated too. To be clear, @@ -76,15 +78,10 @@ This sample is preconfigured to render a specific chart. You can run the sample ## Running this Sample with your data -1. If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, - - Open the _index.js_ file (`src/index.js`) - - Replace the `baseUrl` string on with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace the `chartId` string on with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for "\~REPLACE\~" in the comments) - - Replace `address.country` in the `setFilter` code with your whitelisted field (look for "\~REPLACE\~" in the comments) -2. Run `npm install` to install the package dependencies. -3. Run `npm start` to launch the sample application +If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, make the following changes to the index file. Most examples have a `src/index.js` file which needs to be modified, except the Google authentication example (`index.html`) and for the Timeline Charts example (modify `src/Dashboard.jsx` instead). When complete, refer to steps 3 & 4 of the **Quickstart** section to run the application. -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +- Replace the Charts `baseUrl` string with the base URL you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) +- Replace the `chartId` string with the chart ID you copied from the MongoDB Charts Embedded Chart menu (look for `\~REPLACE\~` in the comments) ## Next Steps diff --git a/examples/dashboard/authenticated-custom-jwt/README.md b/examples/dashboard/authenticated-custom-jwt/README.md index 3aebf02..9c6fd8f 100644 --- a/examples/dashboard/authenticated-custom-jwt/README.md +++ b/examples/dashboard/authenticated-custom-jwt/README.md @@ -8,9 +8,9 @@ The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard dire This example, demonstrates how you might render an authenticated dashboard embedded onto your application using Custom JWT as the authentication provider. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: @@ -18,7 +18,7 @@ In this example, you should be able to: - Render a dashboard to valid users only - Custom JWT authentication via the `jsonwebtoken` package -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -28,7 +28,9 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. + +Happy Charting! 🚀 📈 diff --git a/examples/dashboard/authenticated-google/README.md b/examples/dashboard/authenticated-google/README.md index 2422767..b9215b3 100644 --- a/examples/dashboard/authenticated-google/README.md +++ b/examples/dashboard/authenticated-google/README.md @@ -8,9 +8,9 @@ The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard dire This example, demonstrates how you might render an authenticated dashboard embedded onto your application using Google as the authentication provider. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: @@ -19,7 +19,7 @@ In this example, you should be able to: - Integrate Google Sign-In to authenticate users - You can follow [this tutorial](https://developers.google.com/identity/sign-in/web/sign-in) for more details -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -29,9 +29,11 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:3000` in the url bar to see the sample. Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. Use Incognito mode to see the full Google login flow rather then signing in with your Chrome Google account. Logging in with any valid Google account will allow you to render the chart. + +Happy Charting! 🚀 📈 diff --git a/examples/dashboard/authenticated-realm-deprecated/README.md b/examples/dashboard/authenticated-realm-deprecated/README.md index 1550a9d..9ecf4c2 100644 --- a/examples/dashboard/authenticated-realm-deprecated/README.md +++ b/examples/dashboard/authenticated-realm-deprecated/README.md @@ -1,29 +1,29 @@ # MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (Realm) [DEPRECATED] +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-deprecated)_ + > ## :rotating_light: The [`mongodb-stitch-browser-sdk`](https://www.npmjs.com/package/mongodb-stitch-browser-sdk) package is now deprecated. Please use [`realm-web`](https://www.npmjs.com/package/realm-web) instead and follow the [authenticated-realm-web](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-web) example. ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://dochub.mongodb.org/core/charts-embedding-dashboards)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-deprecated)_ - The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard directly into your application. Just like embedded charts, you can embed a dashboard via unauthenticated or an authenticated method. This example, demonstrates how you might render an authenticated dashboard embedded onto your application using App Services as the authentication provider. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: - Render an authenticated embedded dashboard - Render a dashboard to valid users only - App Services authentication -- Data filtering by App Services User Role. +- Data filtering by App Services User Role -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -33,11 +33,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. - +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. The two hard coded credentials used in this demo are: @@ -52,3 +51,5 @@ password: password ``` And they will display localised data thanks to the configured App Services User Roles. + +Happy Charting! 🚀 📈 diff --git a/examples/dashboard/authenticated-realm-web/README.md b/examples/dashboard/authenticated-realm-web/README.md index b30eb6e..35e420e 100644 --- a/examples/dashboard/authenticated-realm-web/README.md +++ b/examples/dashboard/authenticated-realm-web/README.md @@ -1,27 +1,27 @@ # MongoDB Charts Embedding Example - Authenticated Embedded Dashboard (App Services) +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-web)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://dochub.mongodb.org/core/charts-embedding-dashboards)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/authenticated-realm-web)_ - The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard directly into your application. Just like embedded charts, you can embed a dashboard via unauthenticated or an authenticated method. This example, demonstrates how you might render an authenticated dashboard embedded onto your application using App Services as the authentication provider. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: - Render an authenticated embedded dashboard - Render a dashboard to valid users only - Use App Services authentication -- Data filtering by App Services User Role. +- Data filtering by App Services User Role -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -31,11 +31,10 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. - +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. The two hard coded credentials used in this demo are: @@ -50,3 +49,5 @@ password: password ``` And they will display localised data thanks to the configured App Services User Roles. + +Happy Charting! 🚀 📈 diff --git a/examples/dashboard/unauthenticated-get-chart/README.md b/examples/dashboard/unauthenticated-get-chart/README.md index 84fab60..a078e45 100644 --- a/examples/dashboard/unauthenticated-get-chart/README.md +++ b/examples/dashboard/unauthenticated-get-chart/README.md @@ -1,28 +1,29 @@ # MongoDB Charts Embedding Example - Unauthenticated Embedded Dashboard with `getChart` and `getAllCharts` methods +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated-get-chart)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://dochub.mongodb.org/core/charts-embedding-dashboards)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated-get-chart)_ - The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard directly into your application. Just like embedded charts, you can embed a dashboard via unauthenticated or an authenticated method. This example, demonstrates how you might render an unauthenticated dashboard embedded onto your application and retrieve all or just one chart on a dashboard. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: - Render an unauthenticated embedded dashboard +- Manually refresh the dashboard (Refresh all charts within a dashboard) - Get all the charts that are rendered on a dashboard via the SDK - Manually refresh a chart instance that you have specified - Adding/Removing click event listeners to a specific chart instance that you have specified - Viewing the payload for a click event -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -32,7 +33,9 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. + +Happy Charting! 🚀 📈 diff --git a/examples/dashboard/unauthenticated/README.md b/examples/dashboard/unauthenticated/README.md index be6346d..2ee0d0c 100644 --- a/examples/dashboard/unauthenticated/README.md +++ b/examples/dashboard/unauthenticated/README.md @@ -1,18 +1,18 @@ # MongoDB Charts Embedding Example - Unauthenticated Embedded Dashboard +🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated)_ + ## Background 📄 _[See the MongoDB Charts Embedding Docs for more details](https://dochub.mongodb.org/core/charts-embedding-dashboards)_ -🎮 _[Play with a live demo of this sample here](https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/dashboard/unauthenticated)_ - The MongoDB Charts Embedding SDK allows you to embed a Chart or a Dashboard directly into your application. Just like embedded charts, you can embed a dashboard via unauthenticated or an authenticated method. This example, demonstrates how you might render an unauthenticated dashboard embedded onto your application via the SDK. If you don't want to use the SDK but want an easier way to render your dashboard, you can use an [embedded iframe](https://dochub.mongodb.org/core/charts-embedding-dashboards-iframe) instead. -_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ +## Highlighted features -## Highlighted Features +_Note that this is not an exhaustive list of all the features for the Dashboard Embedding SDK._ In this example, you should be able to: @@ -23,7 +23,7 @@ In this example, you should be able to: - Set the max data age of a chart on a dashboard - Set the height and width mode to `'fixed'` or `'scale'`. -## Quick Start +## Quickstart _The following steps presume the use of npm, though yarn works as well._ @@ -33,7 +33,9 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `npm start` to start the application. This will utilise parcel.js +4. Run `npm start` to start the application. This will utilise parcel.js. - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -This should create a local server running the Charts demo. Open a web browser and navigate to `http://localhost:1234` in the url bar to see the sample. +This should create a local server running the Charts demo. Open a web browser and navigate to the server address to see the sample. This is `http://localhost:3000` for the Timeline Charts example and any using Google authentication, and `http://localhost:1234` for all others. + +Happy Charting! 🚀 📈 diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..e89bc36 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,75 @@ +{ + "name": "charts-embed-sdk", + "version": "1.0.0", + "lockfileVersion": 2, + "requires": true, + "packages": { + "": { + "name": "charts-embed-sdk", + "version": "1.0.0", + "license": "ISC", + "dependencies": { + "markdown-include": "^0.4.3" + }, + "devDependencies": { + "husky": "^8.0.3" + } + }, + "node_modules/husky": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/husky/-/husky-8.0.3.tgz", + "integrity": "sha512-+dQSyqPh4x1hlO1swXBiNb2HzTDN1I2IGLQx1GrBuiqFJfoMrnZWwVmatvSiO+Iz8fBUnf+lekwNo4c2LlXItg==", + "dev": true, + "bin": { + "husky": "lib/bin.js" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/typicode" + } + }, + "node_modules/markdown-include": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/markdown-include/-/markdown-include-0.4.3.tgz", + "integrity": "sha512-kw1f+iJ8jAH9SYljv2RXmhRQFr2oMPPVdyoKaZIH+uA1rrQqDjLk6EQZW65oVz1Y+BkC3V//9lEvKKjRZNb1Jg==", + "dependencies": { + "q": "^1.2.0" + }, + "bin": { + "markdown-include": "bin/cli.js" + } + }, + "node_modules/q": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/q/-/q-1.5.1.tgz", + "integrity": "sha512-kV/CThkXo6xyFEZUugw/+pIOywXcDbFYgSct5cT3gqlbkBE1SJdwy6UQoZvodiWF/ckQLZyDE/Bu1M6gVu5lVw==", + "engines": { + "node": ">=0.6.0", + "teleport": ">=0.2.0" + } + } + }, + "dependencies": { + "husky": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/husky/-/husky-8.0.3.tgz", + "integrity": "sha512-+dQSyqPh4x1hlO1swXBiNb2HzTDN1I2IGLQx1GrBuiqFJfoMrnZWwVmatvSiO+Iz8fBUnf+lekwNo4c2LlXItg==", + "dev": true + }, + "markdown-include": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/markdown-include/-/markdown-include-0.4.3.tgz", + "integrity": "sha512-kw1f+iJ8jAH9SYljv2RXmhRQFr2oMPPVdyoKaZIH+uA1rrQqDjLk6EQZW65oVz1Y+BkC3V//9lEvKKjRZNb1Jg==", + "requires": { + "q": "^1.2.0" + } + }, + "q": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/q/-/q-1.5.1.tgz", + "integrity": "sha512-kV/CThkXo6xyFEZUugw/+pIOywXcDbFYgSct5cT3gqlbkBE1SJdwy6UQoZvodiWF/ckQLZyDE/Bu1M6gVu5lVw==" + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..f51b7bb --- /dev/null +++ b/package.json @@ -0,0 +1,24 @@ +{ + "name": "charts-embed-sdk", + "version": "1.0.0", + "description": "

MongoDB Charts Embedding SDK

", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "build:md": "for i in examples/.markdown/compilation/chart/* examples/.markdown/compilation/dashboard/*; do ./node_modules/markdown-include/bin/cli.js ${i}; done;" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/mongodb-js/charts-embed-sdk.git" + }, + "license": "ISC", + "bugs": { + "url": "https://github.com/mongodb-js/charts-embed-sdk/issues" + }, + "homepage": "https://github.com/mongodb-js/charts-embed-sdk#readme", + "dependencies": { + "markdown-include": "^0.4.3" + }, + "devDependencies": { + "husky": "^8.0.3" + } +}