Hporutiu readme updates to node.js stickies CSV app (#183)

* adding example csv file, env sample, readme template * Update README.md add demo video, and update the folder structure with sample csv data * add line about installing app process is same * update contributing guide to mention the app examples template sections * adding readme template to base app examples folder * add a copy and paste app manifest yaml for the template * update the template with correct link to folder structure example --------- Co-authored-by: Horea Porutiu <[email protected]>
miroapp · Sep 5, 2023 · c912756 · c912756 · vercel · Sep 5, 2023
1 parent 21fc015
commit c912756
Show file tree

Hide file tree

Showing 5 changed files with 207 additions and 52 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -99,3 +99,28 @@ Congratulations! The Miro team is happy to have you contribute.
 Once your PR is merged, your contributions will be publicly visible on the relevant repository.
 
 Now that you are part of the Miro community, make sure to join us in our [Discord](https://bit.ly/miro-developers) as well!
+
+## Contributing to App Examples
+
+<b>Please look at [README.template.md](https://github.com/miroapp/app-examples/README.template.md)<b> for an example of
+how your README should look in order to contribute to App Examples.
+
+If you want to add an app into our [App Examples folder](https://github.com/miroapp/app-examples/tree/main/examples) please
+<b>make sure the README it follows the same structure as our other app examples</b>. You can take a look at [Drag and Drop
+README](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop) for example. In order for your app
+example and PR to get approved, please make sure you have the following components in your README:
+
+1. [App title section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#miro-drag-and-drop-app) with simple 1 line description of what you app example does.
+2. 15-60 second [App Demo section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#-app-demo). The shorter the better.
+3. [Table of contents section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#-table-of-contents)
+4. [Included Features section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#%EF%B8%8F-included-features-), which details which Miro SDK or API methods are used in the example.
+5. [Tools and Technologies section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#%EF%B8%8F-tools-and-technologies-), which details which any technologies you are using, i.e. Node.js, React.
+6. [Prerequisistes section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#-prerequisites-), which details any dependencies or additional CLIs that may need to be installed before running the app.
+7. [Run the app section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#%EF%B8%8F-run-the-app-locally-). This section should go over how to run the app locally. Please be as descriptive as possible to ensure the developer can install
+   and configure your app easily, even if it is their first time using these tools and technologies.
+8. [Folder Structure section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#%EF%B8%8F-folder-structure-). This section outlines what each file is for in the app so a developer can quickly
+   understand the file layout of your app.
+9. [Contributing section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#-contributing-). Here you
+   can just link to [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md).
+10. [License section](https://github.com/miroapp/app-examples/tree/main/examples/drag-and-drop#-license-). This should
+    indicate what license you want to use.
diff --git a/README.template.md b/README.template.md
@@ -0,0 +1,100 @@
+# Miro Example App
+
+<b>Use this template to contribute to Miro's App Examples!</b>
+
+This app shows how to use a certain Miro SDK or API functionality to accomplish a certain task.
+
+# 👨🏻‍💻 App Demo
+
+<b>Insert app demo here.</b>
+
+# 📒 Table of Contents
+
+- [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 <a name="features"></a>
+
+- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference)
+  > Insert SDK methods here which your project uses
+
+# 🛠️ Tools and Technologies <a name="tools"></a>
+
+> Insert tools and technologies here which your project uses and link to them.
+
+# ✅ Prerequisites <a name="prerequisites"></a>
+
+- 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.
+
+> Add any other prerequisites here!
+
+# 🏃🏽‍♂️ Run the app locally <a name="run"></a>
+
+> <b>Add steps to run the app locally. Try to make them as similar as possible to other example apps for consistency.</b>
+
+1. Run `npm install` to install dependencies.
+2. Run `npm start` to start developing. \
+   Your URL should be similar to this example:
+   ```
+   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:
+
+   ```yaml
+   # See https://developers.miro.com/docs/app-manifest on how to use this
+   appName: Example app
+   sdkUri: "http://localhost:3000"
+   scopes:
+     - 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`
+
+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. <b>In the video we install a different app, but the process is the same regardless of the app.</b>
+
+> ⚠️ 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. <b>Refresh your browser</b>.
+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. <b>In the video we search for a different app, but the process is the same regardless of the app.</b>
+
+https://github.com/horeaporutiu/app-examples-template/assets/10428517/b23d9c4c-e785-43f9-a72e-fa5d82c7b019
+
+# 🗂️ Folder structure <a name="folder"></a>
+
+<b>Explain your folder structure so a developer can quickly understand the layout of your code.</b>
+
+It should look something like [this](https://github.com/miroapp/app-examples/tree/main/examples/html-preview#folder).
+
+```
+.
+├── src
+└── initMiro.ts <-- This is where the Node Client is initialized.
+```
+
+# 🫱🏻‍🫲🏽 Contributing <a name="contributing"></a>
+
+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 <a name="license"></a>
+
+[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE).
diff --git a/examples/node-stickies-csv/.env.example b/examples/node-stickies-csv/.env.example
@@ -1,4 +1,4 @@
-MIRO_CLIENT_ID:
-MIRO_CLIENT_SECRET:
-MIRO_REDIRECT_URL:
-MIRO_BOARD_ID:
+MIRO_CLIENT_ID=
+MIRO_CLIENT_SECRET=
+MIRO_REDIRECT_URL=
+MIRO_BOARD_ID=
diff --git a/examples/node-stickies-csv/README.md b/examples/node-stickies-csv/README.md
@@ -1,72 +1,87 @@
-### About the app
+# Node.js Stickies to CSV Miro App
 
-This app shows you how to use the [Miro Node.js client](https://www.npmjs.com/package/@mirohq/miro-api) to interact with the [Miro REST API](https://developers.miro.com/reference/api-reference). The app uses the available CRUD (create, read, update, delete) methods to add and manage sticky notes with tags on a Miro board. This is a backend app built on Node.js and Express.js, with Handlebars.js for rendering.
+This web app shows how to manage stickes using CRUD (create, read, update, delete) methods on a Miro board.
 
-Miro capabilities covered in this app:
+# 👨🏻‍💻 App Demo
 
-1. [x] Miro sticky note items
-2. [x] Miro tag items
-3. [x] CSV data to Sticky notes with tags
+https://github.com/miroapp/app-examples/assets/10428517/d4f1017c-bcea-42a6-9864-7aa01ddfade9
 
-### Prerequisites
+# 📒 Table of Contents
 
-1. Create an [app in Miro](https://miro.com/app/settings/user-profile/apps).
-2. Create a board in Miro that you'd like to import / create sticky notes to.
+- [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)
 
-### Dependencies
+# ⚙️ Included Features <a name="features"></a>
 
-- [Miro Node.js client](https://www.npmjs.com/package/@mirohq/miro-api)
-- [Node.js](https://nodejs.org/en/download/)
-- [Express](https://expressjs.com/en/starter/installing.html)
-- [Axios](https://www.npmjs.com/package/axios)
+- [Miro Node.js Client](https://developers.miro.com/docs/web-sdk-reference)
+  - [MiroApi.getBoard()](https://miroapp.github.io/api-clients/classes/index.MiroApi.html#getBoard)
+  - [Miro.handleAuthorizationCodeRequest()](https://miroapp.github.io/api-clients/classes/index.Miro.html#handleAuthorizationCodeRequest)
+  - [Miro.isAuthorized()](https://miroapp.github.io/api-clients/classes/index.Miro.html#isAuthorized)
+  - [Miro.getAuthUrl()](https://miroapp.github.io/api-clients/classes/index.Miro.html#getAuthUrl)
+  - [board.getAllItems()](https://miroapp.github.io/api-clients/classes/index.Board.html#getAllItems)
+
+# 🛠️ Tools and Technologies <a name="tools"></a>
+
+- [Node.js](https://nodejs.org/en)
 - [Handlebars](https://handlebarsjs.com/)
-- [Fast-CSV](https://www.npmjs.com/package/fast-csv)
-- [Bootstrap](https://www.npmjs.com/package/bootstrap)
-- [Dotenv](https://www.npmjs.com/package/dotenv)
 
-### Setup
+# ✅ Prerequisites <a name="prerequisites"></a>
+
+- 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.
 
-1. Clone or download the repo.
-2. `cd` to the root repo folder.
-3. `npm install` to install dependencies.
-4. Create a copy of the `.env.example` file in the root folder or rename it to `.env`, and ensure the following variables are set (see [How to run the project](#how-to-run-the-project) for more info):
+# 🏃🏽‍♂️ Run the app locally <a name="run"></a>
+
+1. Rename the `.sample.env` file to `.env` and then add in your environmental variables. Once completed your `.env` file should
+   look something like this:
 
 ```
-clientID="<YOUR_CLIENT_ID>"
-clientSecret="<YOUR_CLIENT_SECRET>"
-redirectURL="http://localhost:8000/authorized"
-boardId="<MIRO_BOARD_ID>"
+MIRO_CLIENT_ID=<YOUR_CLIENT_ID>
+MIRO_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+MIRO_REDIRECT_URL=http://localhost:8000/authorized
+MIRO_BOARD_ID=<YOUR_MIRO_BOARD_ID>
 ```
 
-### How to start
-
-1. Open a new terminal in the root folder of the project.
-2. Run `npm run start`
-3. Your console should return `Listening on localhost, port 8000`
-4. In your account profile, go to **Your apps**, and then select the app you just created to access its settings page. \
-   On the app settings page:
-   - Go to **App Credentials**, and copy the app **Client ID** and **Client secret** values. \
-     Paste these details to your `.env` file `clientID` and `clientSecret` variables.
-   - Go to your desired Miro board, copy the board ID from the URL, and paste it to your `.env` file `boardId` variable.
-   - Assign `http://localhost:8000/authorized` as a value for your `.env` file `redirectURL` variable.
-5. Then, 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**. \
+> MIRO_BOARD_ID can be found [here](https://community.miro.com/developer-platform-and-apis-57/where-can-i-find-board-id-3154).
+
+2. Run `npm install` to install dependencies.
+3. Run `npm start` to start developing. \
+   Your URL should be similar to this example:
+   ```
+   http://localhost:8000
+   ```
+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 app as follows:
 
-   - [`redirectUris`](https://developers.miro.com/docs/app-manifest#redirecturis): assign `http://localhost:8000/authorized` as a value for this property. \
-     It defines the redirect URL that starts the OAuth 2.0 code grant flow for the REST API.
-     - [`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:
+   - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:8000` as a value for this property.
+   - [`redirectUris`](https://developers.miro.com/docs/app-manifest?utm_source=app_manifest_editor#redirecturis): assign `http://localhost:8000/authorized/` as a value for this property. \
+   - [`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`
 
-6. To use the app, go to `http://localhost:8000/`.
+5. 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. <b>In the video we install a different app, but the process is the same regardless of the app.</b>
+
+> ⚠️ 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.⚠️
 
-ℹ️ Note:
+https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf
 
-- To reinitialize your project's servers, it may be necessary to to restart the server.
-- When the server restarts, your auth token is invalidated, and you have to re-authorize.
+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 `Node.js Stickies to CSV` or whatever you chose to name it. Click on your app to use it, as shown in the video below.
 
-### Folder structure
+https://github.com/horeaporutiu/app-examples-template/assets/10428517/b23d9c4c-e785-43f9-a72e-fa5d82c7b019
+
+# 🗂️ Folder structure <a name="folder"></a>
 
 ```
 .
@@ -87,5 +102,13 @@ boardId="<MIRO_BOARD_ID>"
       └── home.hbs <-- main Handlebars file to render universal/root rendering
       └── layouts
             └── main.hbs <-- the Handlebars 'app' itself
-
+node-stickies-csv-demo-data.csv <-- sample CSV data to create stickies
 ```
+
+# 🫱🏻‍🫲🏽 Contributing <a name="contributing"></a>
+
+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 <a name="license"></a>
+
+[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE).
diff --git a/examples/node-stickies-csv/node-stickies-csv-demo-data.csv b/examples/node-stickies-csv/node-stickies-csv-demo-data.csv
@@ -0,0 +1,7 @@
+Sticky Title,Sticky Description,Tag1,Tag2,Tag3,Tag4
+I'm a sticky!,Just happy to be here,lorem,ipsum,dolor,sit
+Another Sticky?,"Yeah, why not!",tempor,incididunt,magna,aliqua
+One more sticky,Sticky life = best life,nostrud,exercitation,ullamco,laboris
+I'm a sticky!,Just happy to be here,lorem,ipsum,dolor,sit
+Another Sticky?,"Yeah, why not!",tempor,incididunt,magna,aliqua
+One more sticky,Sticky life = best life,nostrud,exercitation,ullamco,laboris