From c4bf83337815f59cbf7ac4f0f002a3120902ce3e Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 12:28:32 +0200 Subject: [PATCH 01/17] adding asset search readme --- examples/asset-search/README.md | 97 +++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 23 deletions(-) diff --git a/examples/asset-search/README.md b/examples/asset-search/README.md index 184e775a7..5aaa38c92 100644 --- a/examples/asset-search/README.md +++ b/examples/asset-search/README.md @@ -1,21 +1,49 @@ -## Miro asset search +# Miro Asset Search App -** ℹ Note**: +This app shows how to implement asset searching and filtering by name and tags. -- We recommend a Chromium-based web browser for local development with HTTP. \ - Safari enforces HTTPS; therefore, it doesn't allow localhost through HTTP. -- All examples use `npm` as a package manager and `npx` as a package runner. \ - If you prefer, you can install and use equivalent alternatives, such as `yarn` or `pnpm`. -- For more information about implementing [drag and drop](https://developers.miro.com/docs/add-drag-and-drop-to-your-app), visit our [developer documentation](https://developers.miro.com). +# 👨🏻‍💻 App Demo -### About the app +# 📒 Table of Contents -This app shows how to implement asset searching and filtering by name and tags. \ -This app is bootstrapped using [create-miro-app](https://www.npmjs.com/package/create-miro-app). It uses React, Typescript, and Vite. +- [Included Features](#features) +- [Tools and Technologies](#tools) +- [Prerequisites](#prerequisites) +- [Associated Developer Tutorial](#tutorial) +- [Run the app locally](#run) +- [Folder Structure](#folder) +- [Contributing](#contributing) +- [License](#license) -To modify the `vite.config.js` configuration, see the [Vite documentation](https://vitejs.dev/guide/). +# ⚙️ Included Features -### How to start locally +- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) + - [drop event](https://developers.miro.com/docs/ui_boardui#drop-event) + - [createImage](https://developers.miro.com/docs/board_board#createimage) + - [viewport.zoomTo](https://developers.miro.com/docs/viewport_viewport#zoomto) + - [openPanel(options)](https://developers.miro.com/docs/ui_boardui#openpanel) + - [draggable elements](https://developers.miro.com/docs/add-drag-and-drop-to-your-app#add-draggable-elements-to-the-app-panel) + +# 🛠️ Tools and Technologies + +- [React](https://react.dev/) +- [TypeScript](https://www.typescriptlang.org/) +- [Vite](https://vitejs.dev/) + +# ✅ Prerequisites + +- You have a [Miro account](https://miro.com/signup/). +- You're [signed in to Miro](https://miro.com/login/). +- Your Miro account has a [Developer team](https://developers.miro.com/docs/create-a-developer-team). +- Your development environment includes [Node.js 14.13](https://nodejs.org/en/download) or a later version. +- All examples use `npm` as a package manager and `npx` as a package runner. + +# 📖 Associated Developer Tutorial + +> To view a more in depth developer tutorial +> of this app (including code explanations) see the [Asset Search and Filter tutorial](https://developers.miro.com/docs/adding-search-and-filter-to-an-sdk-app) on Miro's Developer documentation. + +# 🏃🏽‍♂️ Run the app locally 1. Run `npm install` to install dependencies. 2. Run `npm start` to start developing. \ @@ -26,21 +54,36 @@ To modify the `vite.config.js` configuration, see the [Vite documentation](https 3. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ In the app manifest editor, configure the app as follows: -- [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \ - It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on. -- [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ - To enable the app to read from and write to the board, add the following permissions: - - `boards:read` - - `boards:write` + - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \ + It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on. + - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ + To enable the app to read from and write to the board, add the following permissions: + - `boards:read` + - `boards:write` + + Your manifest file should look like the following: -4. Open a board: you should see your app in the apps toolbar or in the apps panel. + ```yaml + appName: Miro Asset Search + sdkUri: "http://localhost:3000" + scopes: + - boards:read + - boards:write + ``` + +4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. + +> ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ + +https://github.com/horeaporutiu/app-examples-template/assets/10428517/456108e8-7d9b-4067-94bb-e5511c736a23 -### How to build the app +5. Go to your developer team, and open your boards. +6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. +7. Search for your app `Asset Search` or whatever you chose to name it. Click on your app to use it, as shown in the video below. -- Run `npm run build`. \ - This generates a static output inside `dist/`, which you can host on a static hosting service. +https://github.com/horeaporutiu/app-examples-template/assets/10428517/b23d9c4c-e785-43f9-a72e-fa5d82c7b019 -### Folder structure +# 🗂️ Folder structure ``` . @@ -54,3 +97,11 @@ To modify the `vite.config.js` configuration, see the [Vite documentation](https ├── app.html <-- The app itself. This is loaded on the board inside the 'appContainer'. └── index.html <-- The app entry point. This is the value you assign to 'sdkUri' in the app manifest file. ``` + +# 🫱🏻‍🫲🏽 Contributing + +If you want to contribute to this example, or any other Miro Open Source project, please review [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md). + +# 🪪 License + +[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE). From 7c9414ade16e75944cca72c1ad4e9f9b7c28a482 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 12:30:45 +0200 Subject: [PATCH 02/17] adding asset search readme --- examples/asset-search/README.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/examples/asset-search/README.md b/examples/asset-search/README.md index 5aaa38c92..a078f11b6 100644 --- a/examples/asset-search/README.md +++ b/examples/asset-search/README.md @@ -52,16 +52,7 @@ This app shows how to implement asset searching and filtering by name and tags. http://localhost:3000 ``` 3. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ - In the app manifest editor, configure the app as follows: - - - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \ - It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on. - - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ - To enable the app to read from and write to the board, add the following permissions: - - `boards:read` - - `boards:write` - - Your manifest file should look like the following: + In the app manifest editor, configure the app as follows: ```yaml appName: Miro Asset Search @@ -71,6 +62,8 @@ This app shows how to implement asset searching and filtering by name and tags. - boards:write ``` + You can read more about Miro's [app manifest on the developer documentation](https://developers.miro.com/docs/app-manifest). + 4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. > ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ From 3996b38da0cf47516b74d5ab798fd7da28abfe0f Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 12:31:59 +0200 Subject: [PATCH 03/17] adding asset search readme --- examples/asset-search/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/asset-search/README.md b/examples/asset-search/README.md index a078f11b6..f5cdd5278 100644 --- a/examples/asset-search/README.md +++ b/examples/asset-search/README.md @@ -68,7 +68,7 @@ This app shows how to implement asset searching and filtering by name and tags. > ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ -https://github.com/horeaporutiu/app-examples-template/assets/10428517/456108e8-7d9b-4067-94bb-e5511c736a23 +https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf 5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. From a82a3e14ddd70f8015c986a61e4c9a16462d63c6 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 12:32:36 +0200 Subject: [PATCH 04/17] adding asset search readme --- examples/asset-search/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/asset-search/README.md b/examples/asset-search/README.md index f5cdd5278..f5f38b80d 100644 --- a/examples/asset-search/README.md +++ b/examples/asset-search/README.md @@ -64,7 +64,7 @@ This app shows how to implement asset searching and filtering by name and tags. You can read more about Miro's [app manifest on the developer documentation](https://developers.miro.com/docs/app-manifest). -4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. +4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. In the video we install a different app, but the process is the same regardless of the app. > ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ From 51172ed79f72749796b552e63e0f1e8fc7ec0ef2 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 12:37:28 +0200 Subject: [PATCH 05/17] remove unnecessary browser step --- examples/calendar/README.md | 2 +- examples/csv-to-mindmap/README.md | 2 +- examples/drag-and-drop/README.md | 2 +- examples/html-preview/README.md | 2 +- examples/stickynotes-to-shapes/README.md | 2 +- examples/template-builder/README.md | 2 +- examples/wordle/README.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/calendar/README.md b/examples/calendar/README.md index 69853006d..4e6c22d36 100644 --- a/examples/calendar/README.md +++ b/examples/calendar/README.md @@ -66,7 +66,7 @@ This app allows you to create a calendar consisting of shapes and text for the g https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `Calendar` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app. diff --git a/examples/csv-to-mindmap/README.md b/examples/csv-to-mindmap/README.md index 416050cef..7f94df6ce 100644 --- a/examples/csv-to-mindmap/README.md +++ b/examples/csv-to-mindmap/README.md @@ -66,7 +66,7 @@ This app shows how to import data from a CSV file and create a mind map on a Mir https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `CSV to Mind Map` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app. diff --git a/examples/drag-and-drop/README.md b/examples/drag-and-drop/README.md index 0dd1e6e12..45cd0fd81 100644 --- a/examples/drag-and-drop/README.md +++ b/examples/drag-and-drop/README.md @@ -67,7 +67,7 @@ https://github.com/horeaporutiu/app-examples-template/assets/10428517/3e9aa5ea-0 https://github.com/horeaporutiu/app-examples-template/assets/10428517/456108e8-7d9b-4067-94bb-e5511c736a23 -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `Drag and Drop` or whatever you chose to name it. Click on your app to use it, as shown in the video below. diff --git a/examples/html-preview/README.md b/examples/html-preview/README.md index dac73ff97..10dae00ef 100644 --- a/examples/html-preview/README.md +++ b/examples/html-preview/README.md @@ -79,7 +79,7 @@ MIRO_REDIRECT_URL=http://localhost:3000/api/redirect/ https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -6. Go to your developer team, and open your boards. Refresh your browser. +6. Go to your developer team, and open your boards. 7. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 8. Search for your app `HTML Preview App` or whatever you chose to name it. Click on your app to use it, as shown in the video below. diff --git a/examples/stickynotes-to-shapes/README.md b/examples/stickynotes-to-shapes/README.md index 90d61ec42..f4b3c3adf 100644 --- a/examples/stickynotes-to-shapes/README.md +++ b/examples/stickynotes-to-shapes/README.md @@ -67,7 +67,7 @@ This app shows how you can select items on the board, and then click the app ico https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `Sticky Notes to Shapes` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app. diff --git a/examples/template-builder/README.md b/examples/template-builder/README.md index 5aa2d46c9..294a7ff11 100644 --- a/examples/template-builder/README.md +++ b/examples/template-builder/README.md @@ -60,7 +60,7 @@ https://github.com/miroapp/app-examples/assets/10428517/24aacae3-5183-4142-bdae- https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `Template Builder` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app. diff --git a/examples/wordle/README.md b/examples/wordle/README.md index 930628c7f..53836a83b 100644 --- a/examples/wordle/README.md +++ b/examples/wordle/README.md @@ -64,7 +64,7 @@ https://github.com/miroapp/app-examples/assets/10428517/56fe0932-2608-47ae-9e08- https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf -5. Go to your developer team, and open your boards. Refresh your browser. +5. Go to your developer team, and open your boards. 6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. 7. Search for your app `Wordle` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app. From 076c81c001351d37a92707b226884dc79faf253a Mon Sep 17 00:00:00 2001 From: Horea Porutiu Date: Mon, 11 Sep 2023 12:38:10 +0200 Subject: [PATCH 06/17] Update README.md with asset search demo gif --- examples/asset-search/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/asset-search/README.md b/examples/asset-search/README.md index f5f38b80d..c9dedb6d9 100644 --- a/examples/asset-search/README.md +++ b/examples/asset-search/README.md @@ -4,6 +4,8 @@ This app shows how to implement asset searching and filtering by name and tags. # 👨🏻‍💻 App Demo +![asset-search-demo](https://github.com/miroapp/app-examples/assets/10428517/3a019e8c-60ce-4d61-9181-3109d098e56d) + # 📒 Table of Contents - [Included Features](#features) From 6023696cdba7a2bbabf1ae8b611c1079d77d0d63 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 13:52:15 +0200 Subject: [PATCH 07/17] add Glitch section --- examples/blob-maker/README.md | 163 ++++++++++++++++++++++++---------- 1 file changed, 116 insertions(+), 47 deletions(-) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index 1d015ea3a..2b469e607 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -1,20 +1,57 @@ -## Blob maker app +# Miro Blob Maker App -** ℹ Note**: +This app shows how to create dynamic blob SVGs on the fly, which you can then drag and drop to a Miro board. -- To make drag and drop available in this example, deploy the app to a publicly accessible location. \ - In this example, drag and drop functionality doesn't work if you serve the app on localhost. -- We recommend a Chromium-based web browser for local development with HTTP. \ - Safari enforces HTTPS; therefore, it doesn't allow localhost through HTTP. -- All examples use `npm` as a package manager and `npx` as a package runner. \ - If you prefer, you can install and use equivalent alternatives, such as `yarn` or `pnpm`. -- For more information about implementing [drag and drop](https://developers.miro.com/docs/add-drag-and-drop-to-your-app), visit our [developer documentation](https://developers.miro.com). +⚠️ Note that the drag and drop part of the app only works with a public URL, so you will need to use Glitch or another +service to host your app! ⚠️ -### About the app +# 👨🏻‍💻 App Demo -This app shows how to create dynamic blob SVGs on the fly, which you can then drag and drop to a Miro board. This app uses the Miro Web SDK. +# 📒 Table of Contents -### How to start locally +- [Included Features](#features) +- [Tools and Technologies](#tools) +- [Prerequisites](#prerequisites) +- [Associated Developer Tutorial](#tutorial) +- [Run the app locally](#run) +- [Folder Structure](#folder) +- [Contributing](#contributing) +- [License](#license) + +# ⚙️ Included Features + +- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) + - [drop event](https://developers.miro.com/docs/ui_boardui#drop-event) + - [createImage](https://developers.miro.com/docs/board_board#createimage) + - [viewport.zoomTo](https://developers.miro.com/docs/viewport_viewport#zoomto) + - [openPanel(options)](https://developers.miro.com/docs/ui_boardui#openpanel) + - [draggable elements](https://developers.miro.com/docs/add-drag-and-drop-to-your-app#add-draggable-elements-to-the-app-panel) + +# 🛠️ Tools and Technologies + +- [React](https://react.dev/) +- [TypeScript](https://www.typescriptlang.org/) +- [Vite](https://vitejs.dev/) + +# ✅ Prerequisites + +- You have a [Miro account](https://miro.com/signup/). +- You're [signed in to Miro](https://miro.com/login/). +- Your Miro account has a [Developer team](https://developers.miro.com/docs/create-a-developer-team). +- Your development environment includes [Node.js 14.13](https://nodejs.org/en/download) or a later version. +- All examples use `npm` as a package manager and `npx` as a package runner. +- [Glitch account](https://glitch.com/). + +# 📖 Associated Developer Tutorial + +> To view a more in depth developer tutorial +> of this app (including code explanations) see the [Asset Search and Filter tutorial](https://developers.miro.com/docs/adding-search-and-filter-to-an-sdk-app) on Miro's Developer documentation. + +# 🏃🏽‍♂️ Run the app locally (Not Recommended) + +⚠️ Note that the drag and drop part of the app only works with a public URL, so you will need to +use Glitch or another service to host your app! ⚠️ It is recommended to deploy this on Glitch. See +next section below for more details. 1. Run `npm install` to install dependencies. 2. Run `npm start` to start developing. \ @@ -23,45 +60,77 @@ This app shows how to create dynamic blob SVGs on the fly, which you can then dr http://localhost:3000 ``` 3. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ - In the app manifest editor, configure the app as follows: - - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \ - It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on. - - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ - To enable the app to read from and write to the board, add the following permissions: - - `boards:read` - - `boards:write` -4. Open a board: you should see your app in the apps toolbar or in the apps panel. - -### How to start with Glitch - -[Glitch Documentation](https://help.glitch.com/kb/article/20-importing-code-from-github/) - -- Create a Glitch account if you do not have one already. -- Click **New Project**. -- You should be able to select the option **Import from GitHub**. -- You can copy this app folder into a new GitHub repo and use this URL, or you can use [https://github.com/CharlieWinters/miro-blob-maker](https://github.com/CharlieWinters/miro-blob-maker). -- After the app starts up, it will have a unique URL that will serve the app over HTTPS. \ - Click **Preview** in the bottom bar, and then **Preview in a new window**. -- You should see **Great, your app is running locally!**. \ - Copy the URL. -- Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro). -- In the app manifest, paste the URL as the value of [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri). -- Open a board: you should see your app in the apps toolbar or in the apps panel. - -### How to build the app - -- Run `npm run build`. \ - This generates a static output inside `dist/`, which you can host on a static hosting service. - -### Folder structure + In the app manifest editor, configure the app as follows: + + ```yaml + appName: Blob Maker + sdkUri: "http://localhost:3000" + scopes: + - boards:read + - boards:write + ``` + + You can read more about Miro's [app manifest on the developer documentation](https://developers.miro.com/docs/app-manifest). + +4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. In the video we install a different app, but the process is the same regardless of the app. + +> ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ + +https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf + +5. Go to your developer team, and open your boards. +6. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`. +7. Search for your app `Blob Maker` or whatever you chose to name it. Click on your app to use it, as shown in the video below. + +https://github.com/horeaporutiu/app-examples-template/assets/10428517/b23d9c4c-e785-43f9-a72e-fa5d82c7b019 + +# 🏃🏽‍♂️ Run the app on Glitch (Recommended) + +1. Create a [Glitch account](https://glitch.com/) if you do not have one already. +2. Click New Project. +3. You should be able to select the option "Import from Github". +4. You can copy this app folder into a new github repo and use this url or you can use https://github.com/CharlieWinters/miro-blob-maker +5. After the app starts up, it will have a unique url that will serve the app over https. Click "Preview" in the bottom bar and then "Preview in a new window". +6. You should see "Great, your app is running locally", copy the url. +7. Go into your app settings, and click on edit manifest. +8. Add your public URL to your manifest like so: + +```yaml +appName: Blob Maker +sdkVersion: SDK_V2 +sdkUri: https://polar-near-sumac.glitch.me +boardPicker: + allowedDomains: [] +redirectUris: [] +redirectUriForSdk: "" +scopes: + - boards:write + - boards:read +icons: + colored: "" + outline: "" +``` + +9. Open a board & you should see your app in the main toolbar when you click the three dots. + +# 🗂️ Folder structure ``` . +. ├── src │ ├── assets │ │ └── style.css -│ ├── app.js // The code for the app lives here. -│ └── index.js // The code for the app entry point lives here. -├── app.html // The app itself. It's loaded on the board inside the 'appContainer'. -└── index.html // The app entry point. This is the value you assign to 'sdkUri' in the app manifest file. +│ ├── app.js // The code for the app lives here +│ └── index.js // The code for the app entry point lives here +├── app.html // The app itself. It's loaded on the board inside the 'appContainer' +└── index.html // The app entry point. This is what you specify in the 'App URL' box in the Miro app settings ``` + +# 🫱🏻‍🫲🏽 Contributing + +If you want to contribute to this example, or any other Miro Open Source project, please review [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md). + +# 🪪 License + +[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE). From 8bc6fa2ab3bba981cfb9a9ce8e5a70433201c79d Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 13:53:05 +0200 Subject: [PATCH 08/17] add Glitch section --- examples/blob-maker/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index 2b469e607..6734b3783 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -23,7 +23,6 @@ service to host your app! ⚠️ - [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) - [drop event](https://developers.miro.com/docs/ui_boardui#drop-event) - [createImage](https://developers.miro.com/docs/board_board#createimage) - - [viewport.zoomTo](https://developers.miro.com/docs/viewport_viewport#zoomto) - [openPanel(options)](https://developers.miro.com/docs/ui_boardui#openpanel) - [draggable elements](https://developers.miro.com/docs/add-drag-and-drop-to-your-app#add-draggable-elements-to-the-app-panel) From 1e4ff4f80577ee82489e7111a6d0146638626457 Mon Sep 17 00:00:00 2001 From: Horea Porutiu Date: Mon, 11 Sep 2023 13:53:56 +0200 Subject: [PATCH 09/17] Update README.md with demo video --- examples/blob-maker/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index 6734b3783..dce618f28 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -7,6 +7,8 @@ service to host your app! ⚠️ # 👨🏻‍💻 App Demo +https://github.com/miroapp/app-examples/assets/10428517/b9d570ce-a0b4-4f2e-a8e6-62a5b68be38f + # 📒 Table of Contents - [Included Features](#features) From b3d03d0932d3bf438afcbdc7e2d6a6e64a670081 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 13:59:03 +0200 Subject: [PATCH 10/17] add Glitch section --- examples/blob-maker/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index dce618f28..5f211cbad 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -112,7 +112,8 @@ icons: outline: "" ``` -9. Open a board & you should see your app in the main toolbar when you click the three dots. +9. From the app settings page, make sure to `Install app and get OAuth token` if you haven't. +10. Open a board & you should see your app in the main toolbar when you click the three dots. # 🗂️ Folder structure From 9a6f1a737180adccd797acea2dfef3133a91c5da Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 14:20:28 +0200 Subject: [PATCH 11/17] adding youtube room readme --- examples/youtube-room/README.md | 132 +++++++++++++++++--------------- 1 file changed, 70 insertions(+), 62 deletions(-) diff --git a/examples/youtube-room/README.md b/examples/youtube-room/README.md index bb182b7d3..8e25dbbe5 100644 --- a/examples/youtube-room/README.md +++ b/examples/youtube-room/README.md @@ -1,38 +1,60 @@ -## YouTube room +# YouTube Room Miro App -** ℹ Note**: +This app shows you how you can sync multiple YouTube players across different user sessions +on a Miro board. -- Developing the app involves creating 2 separate apps, and testing them with different user sessions. \ - We recommend opening 2 browser sessions with different users to test the full functionality of the app. -- We recommend a Chromium-based web browser for local development with HTTP. \ - Safari enforces HTTPS; therefore, it doesn't allow localhost through HTTP. -- All examples use `npm` as a package manager and `npx` as a package runner. \ - If you prefer, you can install and use equivalent alternatives, such as `yarn` or `pnpm`. -- For more information, visit our [developer documentation](https://developers.miro.com). +# 👨🏻‍💻 App Demo -This Miro Web SDK app shows you how you can sync multiple YouTube players across different user sessions. \ -The example uses an [Express server](https://expressjs.com/) and [Socket.IO](https://socket.io/), a library to implement a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) in web applications. \ -The app can be useful for teachers, workshop presenters, and others looking to broadcast a video to multiple users on the same board. +# 📒 Table of Contents -### How it works +- [Included Features](#features) +- [Tools and Technologies](#tools) +- [Prerequisites](#prerequisites) +- [Associated Developer Tutorial](#tutorial) +- [Run the app locally](#run) +- [Folder Structure](#folder) +- [Contributing](#contributing) +- [License](#license) + +# ⚙️ Included Features + +- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) + - [icon:click event](https://developers.miro.com/docs/ui_boardui#iconclick-event) + - [getInfo()](https://developers.miro.com/docs/board_board#getinfo) + - [openModal()](https://developers.miro.com/docs/ui_boardui#openmodal) + - [openPanel()](https://developers.miro.com/docs/ui_boardui#openpanel) + +# 🛠️ Tools and Technologies + +- [Express.js](https://expressjs.com/) +- [Socket.io](https://socket.io/) + +# ✅ Prerequisites + +- You have a [Miro account](https://miro.com/signup/). +- You're [signed in to Miro](https://miro.com/login/). +- Your Miro account has a [Developer team](https://developers.miro.com/docs/create-a-developer-team). +- Your development environment includes [Node.js 14.13](https://nodejs.org/en/download) or a later version. +- All examples use `npm` as a package manager and `npx` as a package runner. + +# 🏃🏽‍♂️ Extra app info This example contains 2 separate apps that are connected by a WebSocket: - A facilitator app, and - A participant app. + Each app serves different purposes that enable the functionality of the YouTube room. -Each app serves different purposes that enable the functionality of the YouTube room. - -#### Facilitator +## Facilitator -This app is meant to be installed by only one user: the facilitator of the Miro board. \ +This app is meant to be installed by only one user: the facilitator of the Miro board. It contains the functionality to start, update, and change a YouTube video. The video is in turn broadcasted and synced across all participants. -#### Participant +## Participant This app can be installed by multiple users. It contains the functionality that keeps the YouTube player in sync with the facilitator app. -### How to start locally +# 🏃🏽‍♂️ Run the app locally 1. Run `npm install` to install dependencies. 2. Run `npm start` to start developing. \ @@ -42,27 +64,35 @@ This app can be installed by multiple users. It contains the functionality that ``` 3. [Create a new Miro app](https://developers.miro.com/docs/build-your-first-hello-world-app#step-1-bootstrap-the-hello-world-app) for the _facilitator app_ component. 4. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ - In the app manifest editor, configure the the _facilitator app_ as follows: - - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000/facilitator` as a value for this property. \ - It defines the entry point of the _facilitator app_, and it corresponds to the URL of the server that the app runs on. - - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ - To enable the app to read from and write to the board, add the following permissions: - - `boards:read` - - `boards:write` + In the app manifest editor (see [app manifest docs](https://developers.miro.com/docs/app-manifest) to learn more), configure the the _facilitator app_ as follows: + + ```yaml + appName: YouTube Room Facilitator + sdkUri: "http://localhost:3000/facilitator" + scopes: + - boards:read + - boards:write + ``` + 5. [Create a new Miro app](https://developers.miro.com/docs/build-your-first-hello-world-app#step-1-bootstrap-the-hello-world-app) for the _participant app_ component. 6. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ - In the app manifest editor, configure the the _participant app_ as follows: - - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000/participant` as a value for this property. \ - It defines the entry point of the _participant app_, and it corresponds to the URL of the server that the app runs on. - - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ - To enable the app to read from and write to the board, add the following permissions: - - `boards:read` - - `boards:write` -7. Open a board: you should see your app in the apps toolbar or in the apps panel. + In the app manifest editor, configure the the _participant app_ as follows: + + ```yaml + appName: YouTube Room Participant + sdkUri: "http://localhost:3000/participant" + scopes: + - boards:read + - boards:write + ``` -### Folder structure +7. From the app settings page, make sure to Install both apps and get both OAuth tokens if you haven't. +8. Open two different Miro boards, one for the facilitator and one for the participant. Make sure each board opens their respective apps. The facilitator app should be opened for the facilitator and the participant app for the participant. Once you have done that, watch the video below to see how to use + the app. -This is an overview of important files in this example. +## Watch the video below to understand how to run the app + +# 🗂️ Folder structure ``` . @@ -80,32 +110,10 @@ This is an overview of important files in this example. └── server.js <-- The main server. This serves the HTML for both apps. It also initiates the WebSocket. ``` -### How to use the app - -Using both the facilitator and participant app is straightforward. Continue reading below to read a short description on how each of them work. \ -[Watch a video to see how they work](http://www.youtube.com/watch?v=_HTZFf8bkNI). - -#### Facilitator - -By opening the facilitator app, you'll be greeted with a modal that allows you to paste a YouTube URL in. After selecting the desired video, you're able to click the "Open Video for Participants" button, and in turn a modal will open on all of the participants boards that have the participant app installed. - -As a facilitator, you can play, pause, and stop the video, go to a new point, as well as completely replace the video with a different one. \ -Each of these actions is reflected in the participant app's modal. - -#### Participant - -After installing the participant app, no further setup in required. It will work out of the box, and a modal will appear with a YouTube video whenever the facilitator of the room starts presenting. - -### How to build the app - -When you're done developing your app, you will need to build your app before you can deploy it. - -- Run `npm run build`. \ - This generates a static output inside `dist/`, which you can host on a static hosting service. +# 🫱🏻‍🫲🏽 Contributing -### How to deploy your app +If you want to contribute to this example, or any other Miro Open Source project, please review [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md). -When you're done building your app, you will need to deploy your app before you can use it in production. \ -Host the built project on a service like [Heroku](https://www.heroku.com/), or [Glitch](https://glitch.com/). +# 🪪 License -If you get stuck or have questions, feel free to [join our Discord](https://bit.ly/miro-developers). +[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE). From 08162efef2613be88ed62943bd2b11708bd64968 Mon Sep 17 00:00:00 2001 From: Horea Porutiu Date: Mon, 11 Sep 2023 14:22:34 +0200 Subject: [PATCH 12/17] Update README.md with video to show how to run the app --- examples/youtube-room/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/youtube-room/README.md b/examples/youtube-room/README.md index 8e25dbbe5..3a50bfa32 100644 --- a/examples/youtube-room/README.md +++ b/examples/youtube-room/README.md @@ -91,6 +91,7 @@ This app can be installed by multiple users. It contains the functionality that the app. ## Watch the video below to understand how to run the app +[![how-to-run-youtube-room-app](https://github.com/miroapp/app-examples/assets/10428517/01a41ad7-0dea-412b-8368-64a8988fcd60)](https://www.youtube.com/watch?v=_HTZFf8bkNI) # 🗂️ Folder structure From 6d0d1e6a659968b0fcf6167eab6af3c83e201a53 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 14:24:38 +0200 Subject: [PATCH 13/17] adding youtube room readme --- examples/youtube-room/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/youtube-room/README.md b/examples/youtube-room/README.md index 3a50bfa32..07b2cb206 100644 --- a/examples/youtube-room/README.md +++ b/examples/youtube-room/README.md @@ -91,7 +91,8 @@ This app can be installed by multiple users. It contains the functionality that the app. ## Watch the video below to understand how to run the app -[![how-to-run-youtube-room-app](https://github.com/miroapp/app-examples/assets/10428517/01a41ad7-0dea-412b-8368-64a8988fcd60)](https://www.youtube.com/watch?v=_HTZFf8bkNI) + +[![how-to-run-youtube-room-app](https://github.com/miroapp/app-examples/assets/10428517/01a41ad7-0dea-412b-8368-64a8988fcd60 "YouTube-Room-App")](https://www.youtube.com/watch?v=_HTZFf8bkNI) # 🗂️ Folder structure From 8afbf5353db59178a83a5620e36ab26e54b0b6e2 Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 14:26:32 +0200 Subject: [PATCH 14/17] adding youtube room readme --- examples/youtube-room/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/youtube-room/README.md b/examples/youtube-room/README.md index 07b2cb206..241ca78f1 100644 --- a/examples/youtube-room/README.md +++ b/examples/youtube-room/README.md @@ -92,7 +92,7 @@ This app can be installed by multiple users. It contains the functionality that ## Watch the video below to understand how to run the app -[![how-to-run-youtube-room-app](https://github.com/miroapp/app-examples/assets/10428517/01a41ad7-0dea-412b-8368-64a8988fcd60 "YouTube-Room-App")](https://www.youtube.com/watch?v=_HTZFf8bkNI) +[![How to Run YouTube Room App](https://github-production-user-asset-6210df.s3.amazonaws.com/10428517/267016534-01a41ad7-0dea-412b-8368-64a8988fcd60.png)](https://www.youtube.com/watch?v=_HTZFf8bkNI) # 🗂️ Folder structure From 15056804a334b8089cff93890f97ffbfae90261b Mon Sep 17 00:00:00 2001 From: horeaporutiu Date: Mon, 11 Sep 2023 14:27:31 +0200 Subject: [PATCH 15/17] adding youtube room readme --- examples/youtube-room/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/youtube-room/README.md b/examples/youtube-room/README.md index 241ca78f1..6e1576dbb 100644 --- a/examples/youtube-room/README.md +++ b/examples/youtube-room/README.md @@ -5,6 +5,8 @@ on a Miro board. # 👨🏻‍💻 App Demo +[![How to Run YouTube Room App](https://github-production-user-asset-6210df.s3.amazonaws.com/10428517/267016534-01a41ad7-0dea-412b-8368-64a8988fcd60.png)](https://www.youtube.com/watch?v=_HTZFf8bkNI) + # 📒 Table of Contents - [Included Features](#features) From 9735335749ff70f7e2f450ab830cadfa3c15bec1 Mon Sep 17 00:00:00 2001 From: Horea Porutiu Date: Mon, 11 Sep 2023 17:07:02 +0200 Subject: [PATCH 16/17] Update examples/blob-maker/README.md Co-authored-by: Mettin Parzinski --- examples/blob-maker/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index 5f211cbad..8ca93a08f 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -2,8 +2,7 @@ This app shows how to create dynamic blob SVGs on the fly, which you can then drag and drop to a Miro board. -⚠️ Note that the drag and drop part of the app only works with a public URL, so you will need to use Glitch or another -service to host your app! ⚠️ +⚠️ Note that the drag and drop part of the app only works with a public URL, so you will need to use Glitch or another service to host your app! ⚠️ # 👨🏻‍💻 App Demo From 53e4ee15e3886c4fddce87487928024b4a19d315 Mon Sep 17 00:00:00 2001 From: Horea Porutiu Date: Mon, 11 Sep 2023 17:07:10 +0200 Subject: [PATCH 17/17] Update examples/blob-maker/README.md Co-authored-by: Mettin Parzinski --- examples/blob-maker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/blob-maker/README.md b/examples/blob-maker/README.md index 8ca93a08f..55b332ad4 100644 --- a/examples/blob-maker/README.md +++ b/examples/blob-maker/README.md @@ -70,7 +70,7 @@ next section below for more details. - boards:write ``` - You can read more about Miro's [app manifest on the developer documentation](https://developers.miro.com/docs/app-manifest). +You can read more about Miro's [app manifest on the developer documentation](https://developers.miro.com/docs/app-manifest). 4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. In the video we install a different app, but the process is the same regardless of the app.