Office Add-in share global data with a shared runtime (#65)

* yo office creation of new sample

* store and retrieve values working

* custom function retrieves global state

* added CF for set key/value pair

* local storage working

* task pane working

* small fix

* remove unneeded html runtime starters

* added code comments

* remove unneeded files

* add readme steps and images

* edit fix

* Update Samples/excel-shared-runtime-global-state/README.md

Co-Authored-By: Linda Lu Cannon <[email protected]>

* Apply suggestions from code review

edit feedback

Co-Authored-By: Linda Lu Cannon <[email protected]>

* Update Samples/excel-shared-runtime-global-state/README.md

Co-Authored-By: Linda Lu Cannon <[email protected]>

* Update README.md

Co-authored-by: Linda Lu Cannon <[email protected]>

Author: davidchesnut

Samples/excel-shared-runtime-global-state/.eslintrc.json

@@ -0,0 +1,17 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint"
+  ], 
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    },
+    "project": "./tsconfig.json"
+    },
+  "extends": [
+    "eslint-config-office-addins"
+  ]
+}

Samples/excel-shared-runtime-global-state/.gitignore

@@ -0,0 +1,115 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.pnp.*

Samples/excel-shared-runtime-global-state/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contribute to this code sample 
+
+Thank you for your interest in this sample! Your contributions and improvements will help the developer community. 
+
+## Ways to contribute 
+
+There are several ways you can contribute to this sample: providing better code comments, fixing open issues, and adding new features. 
+
+### Provide better code comments 
+
+Code comments make code samples even better by helping developers learn to use the code correctly in their own applications. If you spot a class, method, or section of code that you think could use better descriptions, then create a pull request with your code comments.
+
+
+In general we want our code comments to follow these guidelines: 
+
+- Any code that has associated documentation displayed in an IDE (such as IntelliSense, or JavaDocs) has code comments.
+- Classes, methods, parameters, and return values have clear descriptions.
+- Exceptions and errors are documented.
+- Remarks exist for anything special or notable about the code.
+- Sections of code that have complex algorithms have appropriate comments describing what they do.
+- Code added from Stack Overflow, or any other source, is clearly attributed. 
+
+### Fix open issues 
+
+Sometimes we get a lot of issues, and it can be hard to keep up. If you have a solution to an open issue that hasn't been addressed, fix the issue and then submit a pull request. 
+
+### Add a new feature 
+
+New features are great! Be sure to check with the repository admin first to be sure the feature will fit the intent of the sample. Start by opening an issue in the repository that proposes and describes the feature. The repository admin will respond and may ask for more information. If the admin agrees to the new feature, create the feature and submit a pull request. 
+
+## Contribution guidelines 
+
+We have some guidelines to help maintain a healthy repo and code for everyone. 
+
+### The Contribution License Agreement 
+
+For most contributions, you'll be asked to sign a Contribution License Agreement (CLA). This will happen when you submit a pull request. Microsoft will send a link to the CLA to sign via email. Once you sign the CLA, your pull request can proceed. Read the CLA carefully, because you may need to have your employer sign it. 
+
+### Code contribution checklist 
+
+Be sure to satisfy all of the requirements in the following list before submitting a pull request: 
+
+- Follow the code style that is appropriate for the platform and language in this repo. For example, Android code follows the style conventions found in the [Code Style for Contributors guide](https://source.android.com/source/code-style.html).
+- Test your code.
+- Test the UI thoroughly to be sure nothing has been broken by your change.
+- Keep the size of your code change reasonable. if the repository owner cannot review your code change in 4 hours or less, your pull request may not be reviewed and approved quickly.
+- Avoid unnecessary changes. The reviewer will check differences between your code and the original code. Whitespace changes are called out along with your code. Be sure your changes will help improve the content. 
+
+### Submit a pull request to the master branch 
+
+When you're finished with your work and are ready to have it merged into the master repository, follow these steps. Note: pull requests are typically reviewed within 10 business days. If your pull request is accepted you will be credited for your submission. 
+
+1. Submit your pull request against the master branch.
+2. Sign the CLA, if you haven't already done so.
+3. One of the repo admins will process your pull request, including performing a code review. If there are questions, discussions, or change requests in the pull request, be sure to respond.
+4. When the repo admins are satisfied, they will accept and merge the pull request. 
+
+Congratulations, you have successfully contributed to the sample! 
+
+## FAQ 
+
+### Where do I get a Contributor's License Agreement? 
+
+You will automatically be sent a notice that you need to sign the Contributor's License Agreement (CLA) if your pull request requires one. 
+
+As a community member, you must sign the CLA before you can contribute large submissions to this project. You only need complete and submit the CLA document once. Carefully review the document. You may be required to have your employer sign the document. 
+
+### What happens with my contributions? 
+
+When you submit your changes, via a pull request, our team will be notified and will review your pull request. You will receive notifications about your pull request from GitHub; you may also be notified by someone from our team if we need more information. We reserve the right to edit your submission for legal, style, clarity, or other issues. 
+
+### Who approves pull requests? 
+
+The admin of the repository approves pull requests. 
+
+### How soon will I get a response about my change request or issue? 
+
+We typically review pull requests and respond to issues within 10 business days. 
+
+## More resources 
+
+- To learn more about Markdown, see [Daring Fireball](http://daringfireball.net/).
+- To learn more about using Git and GitHub, check out the [GitHub Help section](http://help.github.com/). 

Samples/excel-shared-runtime-global-state/LICENSE

@@ -0,0 +1,23 @@
+    Excel Custom Functions 
+
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

Samples/excel-shared-runtime-global-state/README.md

@@ -0,0 +1,119 @@
+---
+page_type: sample
+products:
+- office-excel
+- office-365
+languages:
+- typescript
+extensions:
+  contentType: samples
+  technologies:
+  - Add-ins
+  createdDate: 3/15/2020 1:25:00 PM
+description: "This sample shows how to share data across the ribbon, task pane, and custom functions."
+---
+
+# (Preview) Share global data with a shared runtime
+
+## Summary
+
+This sample shows how to set up a basic project that uses the shared runtime. The shared runtime runs all parts of the Excel add-in (ribbon buttons, task pane, custom functions) in a single browser runtime. This makes it easy to shared data through local storage, or through global variables.
+
+![Screen shot of the add-in with ribbon buttons enabled and disabled](excel-shared-runtime-global.png)
+
+> **Note:** The features used in this sample are currently in preview and subject to change. They are not currently supported for use in production environments. To try the preview features, you'll need to [join Office Insider](https://insider.office.com/join). A good way to try out preview features is to sign up for an Office 365 subscription. If you don't already have an Office 365 subscription, get one by joining the [Office 365 Developer Program](https://developer.microsoft.com/office/dev-program).
+
+## Features
+
+- Share data globally with ribbon buttons, the task pane, and custom functions.
+- To get started, use a provided manifest XML file to create a new project with a shared runtime.
+
+## Applies to
+
+-  Excel on Windows, Mac, and in a browser.
+
+## Prerequisites
+
+To use this sample, you'll need to [join Office Insider](https://insider.office.com/join).
+
+Before running this sample, you need a recent version of [npm](https://www.npmjs.com/get-npm) and [Node.js](https://nodejs.org/en/) installed on your computer. To verify if you've already installed these tools, run the commands `node -v` and `npm -v` in your terminal.
+
+## Solution
+
+Solution | Author(s)
+---------|----------
+Office Add-in share global data with a shared runtime | Microsoft
+
+## Version history
+
+Version  | Date | Comments
+---------| -----| --------
+1.0 | 3-15-2020 | Initial release
+
+## Disclaimer
+
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
+
+----------
+
+## Scenario: Sharing key/value pairs
+
+This sample enables a user to store and retrieve key/value pairs by using the task pane or custom functions. The user can select which type of storage is used. They can choose to store key/value pairs in local storage, or choose to use a global variable.
+
+## Build and run the solution
+
+1. In the command prompt, run the command `npm install`.
+2. Run the command `npm run start`. This starts the node server, and opens Excel on the desktop.
+
+If you're running Excel on the web or Mac, see the following articles for instructions on how to sideload:
+
+- [Sideload Office Add-ins in Office on the web for testing](https://docs.microsoft.com/office/dev/add-ins/testing/sideload-office-add-ins-for-testing) 
+- [Sideload Office Add-ins on iPad and Mac for testing](https://docs.microsoft.com/office/dev/add-ins/testing/sideload-an-office-add-in-on-ipad-and-mac)
+
+Once the add-in is loaded use the following steps to try out the functionality.
+
+1. On the `Home` tab, choose `Show TaskPane`.
+2. In the task pane, enter a key/value pair, and choose `Store key/value pair`.
+![Screen shot of both key and value input fields, and both store and get buttons.](task-pane-buttons.png)
+3. In any spreadsheet cell, enter the formula `=CONTOSO.GETVALUEFORKEYCF("1")`. Pass the value of the key you created from the task pane.
+4. In any spreadsheet cell, enter the formula `=CONTOSO.SETVALUEFORKEYCF("2","oranges")`. The formula should return the text `Stored key/value pair`.
+5. In the task pane, enter the key from the previous formula `2` and choose `Get value for key`. The task pane should display the value `oranges`.
+
+The task pane and custom function share data via a global variable in the shared runtime. You can switch the method of storage by choosing either the `Global variable` or `Local storage` radio buttons on the task pane.
+
+## Key parts of this sample
+
+The manifest.xml is configured to use the shared runtime by using the `Runtimes` element as follows:
+
+```xml
+<Runtimes>
+   <Runtime resid="Shared.Url" lifetime="long" />
+</Runtimes>
+```
+
+In other parts of the manifest, you'll see that the custom functions and task pane are also configured to use the `Shared.Url` because they all run in the same runtime. `Shared.Url` points to `taskpane.html` which loads the shared runtime.
+
+Global state is tracked in a window object retrieved using a `getGlobal()` function. This is accessible to custom functions, the task pane, and the ribbon (because all the code is running in the same JavaScript runtime.) 
+
+There are no commands.html or functions.html files. These are not necessary because their purpose is to load individual runtimes. These do not apply when using the shared runtime.
+
+## Security notes
+
+In the webpack.config.js file, a header is set to `"Access-Control-Allow-Origin": "*"`. This is only for development purposes. In production code, you should list the allowed domains and not leave this header open to all domains.
+
+You'll be prompted to install certificates for trusted access to https://localhost. The certificates are intended only for running and studying this code sample. Do not reuse them in your own code solutions or in production environments.
+
+You can install or uninstall the certificates by running the following commands in the project folder.
+
+```
+npx office-addin-dev-certs install
+npx office-addin-dev-certs uninstall
+```
+
+## Copyright
+
+Copyright (c) 2020 Microsoft Corporation. All rights reserved.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+<img src="https://telemetry.sharepointpnp.com/officedev/samples/excel-shared-runtime-global-state" />