Initial check-in.

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/). 

LICENSE

@@ -1,3 +1,5 @@
+    Excel Custom Functions 
+
     MIT License
 
     Copyright (c) Microsoft Corporation. All rights reserved.

README.md

@@ -1,14 +1,46 @@
+# Custom functions in Excel (Preview)
 
-# Contributing
+Learn how to use custom functions in Excel (similar to user-defined functions, or UDFs). Custom functions are JavaScript functions that you can add to Excel, and then use them like any native Excel function (for example =Sum). This sample accompanies the [Custom Functions Overview](https://dev.office.com/docs/add-ins/excel/custom-functions-overview) topic.
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.microsoft.com.
+## Table of Contents
+* [Change History](#change-history)
+* [Prerequisites](#prerequisites)
+* [To use the project](#to-use-the-project)
+* [Questions and comments](#questions-and-comments)
+* [Additional resources](#additional-resources)
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+## Change History
 
-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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+* Oct 27, 2017: Initial version.
+
+## Prerequisites
+
+* Install Office 2016 for Windows and join the [Office Insider](https://products.office.com/en-us/office-insider) program. You must have Office build number 8711 or later.
+
+## To use the project
+
+Follow these instructions to use this custom function sample add-in:
+
+1. Publish the code files (HTML, JavaScript) in the same folder on a website.
+2. Replace `https://<INSERT-URL-HERE>` in the manifest file (there should be 3 occurrences) with the URL of your website. 
+3. Sideload the manifest using the instructions found at <https://aka.ms/sideload-addins>.
+4. Test your custom function by entering `=Contoso.ADD42(1,2)` in a cell.
+5. If you make changes to the sample add-in, copy the updated files to your website, and then close and reopen Excel. If your functions are not available in Excel, re-insert the add-in using **Insert** > **My Add-ins**.
+6. Follow @OfficeDev on Twitter for updates and send feedback to <excelcustomfunctions@microsoft.com>.
+
+## Questions and comments
+
+We'd love to get your feedback about this sample. You can send your feedback to us in the *Issues* section of this repository.
+
+Questions about Microsoft Office 365 development in general should be posted to [Stack Overflow](http://stackoverflow.com/questions/tagged/office-js+API). If your question is about the Office JavaScript APIs, make sure that your questions are tagged with [office-js] and [API].
+
+## Additional resources
+
+* [Office add-in documentation](https://msdn.microsoft.com/en-us/library/office/jj220060.aspx)
+* [Office Dev Center](http://dev.office.com/)
+* More Office Add-in samples at [OfficeDev on Github](https://github.com/officedev)
+
+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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Copyright
+Copyright (c) 2017 Microsoft Corporation. All rights reserved.

customfunctions.html

@@ -0,0 +1,16 @@
+<!-- Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. -->
+<!-- See LICENSE in the project root for license information -->
+
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="UTF-8" />
+	<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+	<meta http-equiv="Expires" content="0" />
+	<title></title>
+	<script src="https://appsforoffice.edog.officeapps.live.com/lib/beta/hosted/office.js" type="text/javascript"></script>
+	<script src="customfunctions.js" type="text/javascript"></script>
+</head>
+<body>
+</body>
+</html>

customfunctions.js

@@ -0,0 +1,198 @@
+/* 
+ * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+ * See LICENSE in the project root for license information.
+ */
+
+Office.initialize = function(reason){
+    // Define the Contoso prefix.
+    Excel.Script.CustomFunctions = {};
+    Excel.Script.CustomFunctions["CONTOSO"] = {};
+
+    // add42 is an example of a synchronous function.
+    function add42 (a, b) {
+        return a + b + 42;
+    }    
+    Excel.Script.CustomFunctions["CONTOSO"]["ADD42"] = {
+        call: add42,
+        description: "Finds the sum of two numbers and 42.",
+        helpUrl: "https://www.contoso.com/help.html",
+        result: {
+            resultType: Excel.CustomFunctionValueType.number,
+            resultDimensionality: Excel.CustomFunctionDimensionality.scalar,
+        },
+        parameters: [
+            {
+                name: "num 1",
+                description: "The first number",
+                valueType: Excel.CustomFunctionValueType.number,
+                valueDimensionality: Excel.CustomFunctionDimensionality.scalar,
+            },
+            {
+                name: "num 2",
+                description: "The second number",
+                valueType: Excel.CustomFunctionValueType.number,
+                valueDimensionality: Excel.CustomFunctionDimensionality.scalar,
+            }
+        ],
+        options:{ batch: false, stream: false }
+    };
+
+    // getTemperature is an example of an asynchronous function.
+    function getTemperature(thermometerID){
+        return new OfficeExtension.Promise(function(setResult, setError){
+            sendWebRequestExample(thermometerID, function(data){
+                setResult(data.temperature);
+            });
+        });
+    }
+    Excel.Script.CustomFunctions["CONTOSO"]["GETTEMPERATURE"] = {
+        call: getTemperature,
+        description: "Returns the temperature of a sensor.",
+        helpUrl: "https://www.contoso.com/help.html",
+        result: {
+            resultType: Excel.CustomFunctionValueType.number,
+            resultDimensionality: Excel.CustomFunctionDimensionality.scalar,
+        },
+        parameters: [
+            {
+                name: "thermometer ID",
+                description: "The ID of the thermometer to read.",
+                valueType: Excel.CustomFunctionValueType.string,
+                valueDimensionality: Excel.CustomFunctionDimensionality.scalar,
+            },
+        ],
+        options: { batch: false,  stream: false }
+    };
+
+    // incrementValue is an example of a streaming function.
+    function incrementValue(increment, setResult){    
+    	var result = 0;
+        setInterval(function(){
+            result += increment;
+            setResult(result);
+        }, 1000);
+    }
+    Excel.Script.CustomFunctions["CONTOSO"]["INCREMENTVALUE"] = {
+        call: incrementValue,
+        description: "Increments a counter that starts at zero.",
+        helpUrl: "https://www.contoso.com/help.html",
+        result: {
+            resultType: Excel.CustomFunctionValueType.number,
+            resultDimensionality: Excel.CustomFunctionDimensionality.scalar,
+        },
+        parameters: [
+            {
+                name: "period",
+                description: "The time between updates, in milliseconds.",
+                valueType: Excel.CustomFunctionValueType.number,
+                valueDimensionality: Excel.CustomFunctionDimensionality.scalar,
+            },
+        ],
+        options: { batch: false,  stream: true }
+    };
+
+    // The refreshTemperature and streamTemperature functions use global variables to save & read state, while streaming data.
+    var savedTemperatures = {};
+    function refreshTemperature(thermometerID){        
+        sendWebRequestExample(thermometerID, function(data){
+            savedTemperatures[thermometerID] = data.temperature;
+        });
+        setTimeout(function(){
+            refreshTemperature(thermometerID);
+        }, 1000);
+    }
+    function streamTemperature(thermometerID, setResult){    
+        if(!savedTemperatures[thermometerID]){
+            refreshTemperature(thermometerID);
+        }
+        function getNextTemperature(){
+            setResult(savedTemperatures[thermometerID]);
+            setTimeout(getNextTemperature, 1000);
+        }
+        getNextTemperature();
+    }
+    Excel.Script.CustomFunctions["CONTOSO"]["STREAMTEMPERATURE"] = {
+        call: streamTemperature,
+        description: "Updates the displayed temperature of the sensor in the Excel UI every second.",
+        helpUrl: "https://www.contoso.com/help.html",
+        result: {
+            resultType: Excel.CustomFunctionValueType.number,
+            resultDimensionality: Excel.CustomFunctionDimensionality.scalar,
+        },
+        parameters: [
+            {
+                name: "thermometer ID",
+                description: "The ID of the thermometer to read.",
+                valueType: Excel.CustomFunctionValueType.string,
+                valueDimensionality: Excel.CustomFunctionDimensionality.scalar,
+            },
+        ],
+        options: { batch: false,  stream: true }
+    };
+
+    // secondHighestTemp is a function that accepts and uses a range of data. The range is sent to the function as a parameter.
+    function secondHighestTemp(temperatures){ 
+        var highest = -273, secondHighest = -273;
+        for(var i = 0; i < temperatures.length;i++){
+            for(var j = 0; j < temperatures[i].length;j++){
+                if(temperatures[i][j] >= highest){
+                    secondHighest = highest;
+                    highest = temperatures[i][j];
+                }
+                else if(temperatures[i][j] >= secondHighest){
+                    secondHighest = temperatures[i][j];
+                }
+            }
+        }
+        return secondHighest;
+    }
+
+    Excel.Script.CustomFunctions["CONTOSO"]["SECONDHIGHESTTEMP"] = {
+        call: secondHighestTemp,
+        description: "Returns the second highest tempature in the supplied range of temperatures.",
+        helpUrl: "https://www.contoso.com/help.html",
+        result: {
+            resultType: Excel.CustomFunctionValueType.number,
+            resultDimensionality: Excel.CustomFunctionDimensionality.scalar,
+        },
+        parameters: [
+            {
+                name: "temps",
+                description: "The range of temperatures to compare.",
+                valueType: Excel.CustomFunctionValueType.number,
+                valueDimensionality: Excel.CustomFunctionDimensionality.matrix,
+            },
+        ],
+        options: { batch: false, stream: false }
+    };
+
+    // Register all the custom functions previously defined in Excel.
+    Excel.run(function (context) {        
+        context.workbook.customFunctions.addAll();
+        return context.sync().then(function(){});
+    }).catch(function(error){});
+
+    // The following are helper functions.
+
+    // sendWebRequestExample is intended to simulate a web request to read a temperature. The code in this function does not actually make a web request. 
+    function sendWebRequestExample(input, callback){
+        var result = {};
+        // Generate a temperature.
+        result["temperature"] = 42 - (Math.random() * 10);
+        setTimeout(function(){
+            callback(result);
+        }, 250);
+    }
+
+    // The log function lets you write debugging messages into Excel (first evaluate the MY.DEBUG function in Excel). You can also debug with regular debugging tools like Visual Studio.
+    var debug = [];
+    var debugUpdate = function(data){};
+    function log(myText){
+        debug.push([myText]);
+        debugUpdate(debug);
+    }
+    function myDebug(setResult){
+        debugUpdate = setResult;
+    }
+
+};