Merge pull request #901 from OfficeDev/dev

Merge dev into main

.config/sample-config.json

@@ -0,0 +1,132 @@
+{
+    "filterOptions": {
+        "capabilities": [
+            "Word",
+            "Excel"
+        ],
+        "languages": [
+            "TypeScript",
+            "JavaScript"
+        ],
+        "technologies": [
+            "Custom Functions",
+            "Web Workers"
+        ]
+    },
+    "samples": [
+        {
+            "id": "excel-get-started-with-dev-kit",
+            "onboardDate": "2024-11-01",
+            "title": "Excel - Get started with the Office Add-ins Development Kit",
+            "description": "This sample demonstrates how to create a basic Excel add-in with a task pane that uses JavaScript.",
+            "types": [
+                "Excel"
+            ],
+            "tags": [
+                "JavaScript",
+                "Get Started",
+                "Excel"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "word-get-started-with-dev-kit",
+            "onboardDate": "2024-11-01",
+            "title": "Word - Get started with the Office Add-ins Development Kit ",
+            "description": "This sample demonstrates how to create a basic Word add-in with a task pane that uses JavaScript.",
+            "types": [
+                "Word"
+            ],
+            "tags": [
+                "JavaScript",
+                "Get Started",
+                "Word"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "excel-add-in-chart-analyze-data",
+            "onboardDate": "2024-11-11",
+            "title": "Analyze Excel data with charts",
+            "description": "This sample Excel add-in shows how to use charts to help analyze data.",
+            "types": [
+                "Excel"
+            ],
+            "tags": [
+                "TypeScript",
+                "Chart",
+                "Excel"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "excel-add-in-shape-dashboard",
+            "onboardDate": "2024-11-11",
+            "title": "Create a dashboard in Excel with shapes",
+            "description": "The sample Excel add-in uses shapes to create a dashboard in the workbook.",
+            "types": [
+                "Excel"
+            ],
+            "tags": [
+                "TypeScript",
+                "Shape",
+                "Excel"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "excel-add-in-custom-functions-using-web-workers",
+            "onboardDate": "2024-11-11",
+            "title": "Build asynchronous custom functions in Excel with web workers",
+            "description": "Use web workers in custom Excel functions to prevent your Office Add-in UI from being blocked.",
+            "types": [
+                "Excel"
+            ],
+            "tags": [
+                "JavaScript",
+                "Custom Functions",
+                "Excel",
+                "Web Workers"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "excel-add-in-mail-merge",
+            "onboardDate": "2024-11-11",
+            "title": "Send emails from Excel with Microsoft Graph",
+            "description": "This sample Office Add-in sends emails from inside Excel using the Microsoft Graph JavaScript SDK.",
+            "types": [
+                "Excel"
+            ],
+            "tags": [
+                "JavaScript",
+                "Excel",
+                "SSO",
+                "Graph"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        },
+        {
+            "id": "word-ai-generated-content",
+            "onboardDate": "2024-11-11",
+            "title": "Insert AI-generated content in a document",
+            "description": "Insert AI-generated or preset content into a Word document from an add-in.",
+            "types": [
+                "Word"
+            ],
+            "tags": [
+                "TypeScript",
+                "Word",
+                "React"
+            ],
+            "thumbnailPath": "assets/thumbnail.png",
+            "suggested": false
+        }
+    ]
+}

.gitignore

@@ -1,2 +1 @@
-.vscode/
 *.DS_Store

ADD_SAMPLE_INTO_DEV_KIT.md

@@ -0,0 +1,52 @@
+# How to add samples to the sample gallery of the Office Add-ins Development Kit
+
+The sample gallery provides samples from this repo in the [Office Add-ins Development Kit](https://marketplace.visualstudio.com/items?itemName=msoffice.microsoft-office-add-in-debugger).
+
+![The Office Add-ins Dev Kit sample gallery in VS Code.](assets/sample_gallery.png)
+
+## Branch
+
+For new samples, use `dev` as the target branch for pull requests. The `dev` branch will be merged into `main` after testing.
+
+`main` branch is the release branch. All content from the `main` branch appears in the [Office Add-ins Development Kit](https://marketplace.visualstudio.com/items?itemName=msoffice.microsoft-office-add-in-debugger)'s sample gallery.
+
+## Testing
+
+1. Uninstall the installed Office Add-ins Development Kit.
+2. Download the [test version of Dev Kit](./assets/dev-kit-test-package.vsix) and install it manually in VSCode.
+3. Set the environment variable `OTK_SAMPLE_CONFIG_BRANCH` to `dev` or other branch with a valid [sample-config.json](./.config/sample-config.json) of this repo on your development machine. Setting this variable will force sample gallery to use the config in the dedicated branch instead of `main`.
+4. Open Dev Kit. Select `View Samples` to view sample gallery and do testing. 
+
+## Check in the new sample into the sample gallery
+
+1. Add the new sample project folder under the **Samples** directory.
+    1. Be sure the sample project folder contains a `.vscode` folder with a `launch.json` file that has at least one launch config in it. This ensures that the user can press `F5` to launch, which is a key experience of the development kit. When the user presses `F5` to open the sample project, the first profile in `.vscode/launch.json` will be executed to launch the sample. Node and webpack is also required if you want support starting a local dev host and attaching the debugger.
+        * Refer to [this sample](./Samples/excel-get-started-with-dev-kit/) as an example.
+    2. Make sure the new sample runs correctly and has been tested on the supported platforms.
+    3. Add the **README.md** and **RUN_WITH_EXTENSION.md** files. Use the **README_TEMPLATE.md** under the root directory as a starting point.
+2. Add a new config to the [config file](./.config/sample-config.json) with following format.
+    * Make sure **id** has an identical value with the folder name you just created.
+
+## JSON config of sample gallery
+
+### Configure the sample for the developer kit
+
+The developer kit's sample gallery uses the [samples-config.json](./.config/sample-config.json) file from this repo's `main` branch. It uses the sample configuration ID to find the files. It also downloads a .zip file of the sample project from this repo, and unzips that file in the designated path.
+
+### JSON properties
+
+* `filterOptions`: Defines the options of the filter bar at the top of the sample gallery
+    * `capabilities`: platforms that samples in this sample gallery support, it's supposed to be a subset of the host apps of Office like ["Word", "Excel", "PowerPoint", "Outlook"]
+    * `language`: the programming language of samples
+    * `technologies`: technologies used in samples like "SSO", "Graph", "Azure"
+* `samples`: this property should be a list of sample configs in sample gallery.
+    * `id`: the configuration id and the folder name under Samples folder
+    * `onboardDate`: when this sample onboard sample gallery
+    * `title`: title of the sample add-in, will show in the sample card of sample gallery
+    * `description`: a description of the sample id, will used for sample matching when users search samples in sample gallery
+    * `types`: the platform type this sample supports, should be a subset of `capabilities` of `filterOptions`
+    * `tags`: tags of this sample, will show in the sample card of the sample gallery below title. You can set the tags referring the values in filterOptions
+    * `thumbnailPath`: the image (.png/.img) that shows in the sample card. Use relative path to the sample folder
+    * `suggested`: if this sample is suggested, default value is `false`. if set `true`, the suggested samples will be presented like showcases at the top of sample gallery above all other samples.
+
+![The Office Add-ins Dev Kit sample gallery with the parts of the UI labelled with corresponding JSON properties.](assets/config_definition.png)

CONTRIBUTING.md

@@ -44,6 +44,9 @@ When you are submitting a new sample solution, please name the sample solution f
 * If your solution is demonstrating multiple technologies, please use functional terms as the name for the solution folder.
 * Do not use a period in the folder name of the provided sample.
 
+### Add your sample to the Office Add-ins Development Kit
+To have your sample be included in Office Add-ins VS Code extension, follow the instructions in [How to add samples to sample gallery of Office Add-ins Development Kit](./ADD_SAMPLE_INTO_DEV_KIT.md).
+
 ## Add your code sample to a pull request
 
 Use the following steps to submit a pull request for your new code sample.

Samples/excel-add-in-chart-analyze-data/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "plugins": [
+    "office-addins"
+  ],
+  "extends": [
+    "plugin:office-addins/recommended"
+  ]
+}

Samples/excel-add-in-chart-analyze-data/.gitignore

@@ -0,0 +1,18 @@
+node_modules
+/dist
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+
+# Editor directories and files
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw*
+package-lock.json

Samples/excel-add-in-chart-analyze-data/.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+  // See http://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+  // List of extensions which should be recommended for users of this workspace.
+  "recommendations": [
+    "ms-edgedevtools.vscode-edge-devtools",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode"
+  ],
+  // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+  "unwantedRecommendations": []
+}

Samples/excel-add-in-chart-analyze-data/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Excel Desktop (Edge Chromium)",
+      "type": "msedge",
+      "request": "attach",
+      "port": 9229,
+      "timeout": 600000,
+      "webRoot": "${workspaceRoot}",
+      "preLaunchTask": "Debug: Excel Desktop",
+      "postDebugTask": "Stop Debug"
+    }
+  ]
+}

Samples/excel-add-in-chart-analyze-data/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "eslint.validate": [
+      "javascript",
+      "javascriptreact",
+      "typescript"
+    ]
+  }
+

Samples/excel-add-in-chart-analyze-data/.vscode/tasks.json

@@ -0,0 +1,105 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Build (Development)",
+      "type": "npm",
+      "script": "build:dev",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "presentation": {
+        "clear": true,
+        "panel": "shared",
+        "showReuseMessage": false
+      }
+    },
+    {
+      "label": "Build (Production)",
+      "type": "npm",
+      "script": "build",
+      "group": "build",
+      "presentation": {
+        "clear": true,
+        "panel": "shared",
+        "showReuseMessage": false
+      }
+    },
+    {
+      "label": "Debug: Excel Desktop",
+      "type": "shell",
+      "command": "npm",
+      "args": [
+        "run",
+        "start:desktop",
+        "--",
+        "--app",
+        "excel"
+      ],
+      "presentation": {
+        "clear": true,
+        "panel": "dedicated"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Dev Server",
+      "type": "npm",
+      "script": "dev-server",
+      "presentation": {
+        "clear": true,
+        "panel": "dedicated"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Install",
+      "type": "npm",
+      "script": "install",
+      "presentation": {
+        "clear": true,
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Lint: Check for problems",
+      "type": "npm",
+      "script": "lint",
+      "problemMatcher": [
+        "$eslint-stylish"
+      ]
+    },
+    {
+      "label": "Lint: Fix all auto-fixable problems",
+      "type": "npm",
+      "script": "lint:fix",
+      "problemMatcher": [
+        "$eslint-stylish"
+      ]
+    },
+    {
+      "label": "Stop Debug",
+      "type": "npm",
+      "script": "stop",
+      "presentation": {
+        "clear": true,
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Watch",
+      "type": "npm",
+      "script": "watch",
+      "presentation": {
+        "clear": true,
+        "panel": "dedicated"
+      },
+      "problemMatcher": []
+    }
+  ]
+}