diff --git a/README.md b/README.md index 9d9809a..402fec6 100644 --- a/README.md +++ b/README.md @@ -29,5 +29,7 @@ yarn add @mongodb-js/charts-embed-dom - [Installation & MongoDB Docs](https://docs.mongodb.com/charts/master/embedding-charts-sdk/) - [Examples](https://github.com/mongodb-js/charts-embed-sdk/blob/master/examples) - Guides 🀠 + - [Getting started with the MongoDB Charts SDK](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/unauthenticated) - [Getting started with custom JWT authentication](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/authenticated-custom-jwt) - [Getting started with Realm authentication](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/authenticated-realm) + - [Getting started with Google authentication](https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/authenticated-google) diff --git a/examples/authenticated-custom-jwt/package.json b/examples/authenticated-custom-jwt/package.json index 770afcc..9b2aec4 100644 --- a/examples/authenticated-custom-jwt/package.json +++ b/examples/authenticated-custom-jwt/package.json @@ -13,7 +13,8 @@ "express": "^4.16.3", "jsonwebtoken": "^8.3.0", "regenerator-runtime": "^0.13.3", - "request": "^2.88.2" + "request": "^2.88.2", + "parcel": "^1.12.4" }, "devDependencies": { "@babel/core": "^7.8.6", diff --git a/examples/authenticated-custom-jwt/readme.md b/examples/authenticated-custom-jwt/readme.md index f72f802..58d0c2e 100644 --- a/examples/authenticated-custom-jwt/readme.md +++ b/examples/authenticated-custom-jwt/readme.md @@ -18,6 +18,18 @@ This sample shows how to use the JavaScript Embedding SDK to render **authentica - πŸ”’ Only render charts to valid users - πŸ”‘ Custom JWT authentication via `jsonwebtoken` +## Quickstart +_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. + +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 + ## 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: @@ -46,24 +58,15 @@ This sample is preconfigured to render a specific chart. You can run the sample - 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 - -_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. - -2. Clone the Git repository or download the code to your computer. +## Running this Sample with your data -3. **Optional** +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 second `chartId`string with the same ID. (look for "\~REPLACE\~" in the comments) -4. Run `npm install` to install the package dependencies. -5. Run `npm install -g parcel-bundler` to install Parcel. You may need to run `sudo npm install -g parcel-bundler` if you lack permissions. - - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -6. Run `npm start`Β to start the application. + - 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. 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`. @@ -77,6 +80,6 @@ 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. - 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 simplifies the workflow even further. +- 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/unauthenticated) simplifies the workflow even further. Happy Charting! πŸš€πŸ“ˆ diff --git a/examples/authenticated-custom-jwt/src/index.js b/examples/authenticated-custom-jwt/src/index.js index 9795f39..a40d467 100644 --- a/examples/authenticated-custom-jwt/src/index.js +++ b/examples/authenticated-custom-jwt/src/index.js @@ -51,13 +51,12 @@ async function login(username, password) { async function renderChart() { const sdk = new ChartsEmbedSDK({ baseUrl: "https://charts-dev.mongodb.com/charts-test2-pebbp", // Optional: ~REPLACE~ with the Base URL from your Embed Chart dialog - chartId: "a2e775e6-f267-4c2c-a65d-fbf3fad4a4f2", // Optional: ~REPLACE~ with the Chart ID from your Embed Chart dialog getUserToken: async function() { return await login(getUser(), getPass()); } }); - const chart = sdk.createChart({ id: "a2e775e6-f267-4c2c-a65d-fbf3fad4a4f2" }); // Optional: ~REPLACE~ with the Chart ID from your Embed Chart dialog + const chart = sdk.createChart({ chartId: "a2e775e6-f267-4c2c-a65d-fbf3fad4a4f2" }); // Optional: ~REPLACE~ with the Chart ID from your Embed Chart dialog // render the chart into a container chart.render(document.getElementById("chart")); diff --git a/examples/authenticated-google/readme.md b/examples/authenticated-google/readme.md index 74c77a8..3322335 100755 --- a/examples/authenticated-google/readme.md +++ b/examples/authenticated-google/readme.md @@ -93,6 +93,6 @@ Once you gain an understanding of the API, consider the following - ![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 simplifies the workflow even further. +- 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/unauthenticated) simplifies the workflow even further. Happy Charting! πŸš€πŸ“ˆ diff --git a/examples/authenticated-realm/package.json b/examples/authenticated-realm/package.json index b54328c..44ac8a4 100644 --- a/examples/authenticated-realm/package.json +++ b/examples/authenticated-realm/package.json @@ -4,7 +4,7 @@ "description": "", "main": "index.html", "scripts": { - "start": "node app.js & parcel index.html --open", + "start": "parcel index.html --open", "build": "parcel build index.html" }, "dependencies": { diff --git a/examples/authenticated-realm/readme.md b/examples/authenticated-realm/readme.md index d596996..936d840 100644 --- a/examples/authenticated-realm/readme.md +++ b/examples/authenticated-realm/readme.md @@ -31,7 +31,7 @@ _The following steps presume the use of npm, though yarn works as well._ 3. Run `npm install` to install the package dependencies. -4. Run `parcel index.html`Β to start the application. +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. @@ -137,6 +137,6 @@ 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. - Play with Realms 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 simplifies the workflow even further. +- 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/unauthenticated) simplifies the workflow even further. Happy Charting! πŸš€πŸ“ˆ diff --git a/examples/readme.md b/examples/readme.md new file mode 100644 index 0000000..823cd4d --- /dev/null +++ b/examples/readme.md @@ -0,0 +1,22 @@ +# MongoDB Embedding SDK Examples + +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 the embed code 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 directory contains example applications making use of both unauthenticated and authenticated utilizations of the SDK. They are provided as a reference to kick start your development process. To run these examples, simply clone the directory, and run the following commands: +- `npm install` +- `npm start` + +in the example directory of your choosing. + +The [Unauthenticated](https://github.com/mongodb-js/charts-embed-sdk/blob/master/examples/unauthenticated) example is the best place to see all the current SDK features being used. Since it doesn't require authentication, it's the easiest example to set up and follow along with. + +Our **authenticated** examples are great references if you need help getting started creating Authenticated Embedded Charts. We have three examples, each tailored for the three Authentication Providers now available in MongoDB Charts. The three examples are: + - [Custom JWT](https://github.com/mongodb-js/charts-embed-sdk/blob/master/examples/authenticated-custom-jwt) + - [MongoDB Realm](https://github.com/mongodb-js/charts-embed-sdk/blob/master/examples/authenticated-realm) + - [Google](https://github.com/mongodb-js/charts-embed-sdk/blob/master/examples/authenticated-google) + +We hope these resources help, and as always, + +Happy Charting! πŸš€πŸ“ˆ \ No newline at end of file diff --git a/examples/unauthenticated/package.json b/examples/unauthenticated/package.json index 0ff38a1..e26ab2d 100755 --- a/examples/unauthenticated/package.json +++ b/examples/unauthenticated/package.json @@ -9,7 +9,8 @@ }, "dependencies": { "@mongodb-js/charts-embed-dom": "^1.0.0", - "regenerator-runtime": "^0.13.3" + "regenerator-runtime": "^0.13.3", + "parcel": "^1.12.4" }, "devDependencies": { "@babel/core": "^7.8.4", diff --git a/examples/unauthenticated/readme.md b/examples/unauthenticated/readme.md index f379e4a..3a41a7a 100644 --- a/examples/unauthenticated/readme.md +++ b/examples/unauthenticated/readme.md @@ -26,6 +26,21 @@ This sample shows how to use the JavaScript Embedding SDK to render unauthentica - 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 + +_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 `http://localhost:1234` in the url bar to see the sample. + ## 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: @@ -50,24 +65,15 @@ This sample is preconfigured to render a specific chart. You can run the sample - Update the query **field** in `src/index.js` - Update the query **values** in `index.html` -## Running this Sample - -_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. - -2. Clone the Git repository or download the code to your computer. +## Running this Sample with your data -3. **Optional** - If you do not wish to use our sample data and have completed the above steps to prepare your own chart for embedding, +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) -4. Run `npm install` to install the package dependencies. -5. Run `npm install -g parcel-bundler` to install Parcel. You may need to run `sudo npm install -g parcel-bundler` if you lack permissions. - - Optional Parcel.js documentation https://parceljs.org/ for more information on what this is -6. Run `parcel index.html` to launch the sample application +2. Run `npm install` to install the package dependencies. +3. Run `npm start` to launch the sample 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. @@ -76,7 +82,7 @@ This should create a local server running the Charts demo. Open a web browser an 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. -- Think whether an unauthenticated chart is the feature you're after. Embedding iframes from Charts is a great way to showcase your data if you don't need the user to interact with the chart. +- 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. Happy Charting! πŸš€πŸ“ˆ