From 73c6613dc54e488d6d43236858bbe9441d38af29 Mon Sep 17 00:00:00 2001 From: Courtney Owen Date: Fri, 27 Jul 2018 11:39:48 -0700 Subject: [PATCH] Merge over Yo Office custom functions template to Excel-Custom-Functions repo so we don't have two different repos --- Excel-Custom-Functions.yml | 19 ----- LICENSE | 2 +- README.md | 55 +++++---------- .../customfunctions.json | 4 +- customfunctions.xml => config/manifest.xml | 12 ++-- config/web.config | 10 +++ config/webpack.config.js | 42 +++++++++++ customfunctions.js | 69 ------------------- customfunctions.html => index.html | 19 ++--- package.json | 35 ++++++++++ src/customfunctions.js | 69 +++++++++++++++++++ 11 files changed, 189 insertions(+), 147 deletions(-) delete mode 100644 Excel-Custom-Functions.yml rename customfunctions.json => config/customfunctions.json (95%) rename customfunctions.xml => config/manifest.xml (75%) create mode 100644 config/web.config create mode 100644 config/webpack.config.js delete mode 100644 customfunctions.js rename customfunctions.html => index.html (72%) create mode 100644 package.json create mode 100644 src/customfunctions.js diff --git a/Excel-Custom-Functions.yml b/Excel-Custom-Functions.yml deleted file mode 100644 index 0feaf99..0000000 --- a/Excel-Custom-Functions.yml +++ /dev/null @@ -1,19 +0,0 @@ -### YamlMime:Sample -sample: -- name: Custom functions in Excel (Preview) - path: '' - description: 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 topic. - readme: '' - generateZip: FALSE - isLive: TRUE - technologies: - - Office Add-in - azureDeploy: '' - author: Reezali - platforms: [] - languages: - - JavaScript - extensions: - products: - - Excel - scenarios: [] diff --git a/LICENSE b/LICENSE index 8c1c5d3..89d8498 100644 --- a/LICENSE +++ b/LICENSE @@ -20,4 +20,4 @@ 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 + SOFTWARE \ No newline at end of file diff --git a/README.md b/README.md index 9caaa82..059cda5 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,11 @@ # Custom functions in Excel (Preview) -Custom functions (similar to user-defined functions, or UDFs) are JavaScript functions that you can add to Excel. This sample accompanies the [Custom Functions Overview](https://docs.microsoft.com/en-us/office/dev/add-ins/excel/custom-functions-overview) topic. +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://docs.microsoft.com/en-us/office/dev/add-ins/excel/custom-functions-overview) topic. ## Table of Contents * [Change History](#change-history) * [Prerequisites](#prerequisites) * [To use the project](#to-use-the-project) -* [Making changes](#making-changes) -* [Debugging](#debugging) -* [Intellisense for the JSON file in Visual Studio Code](#intellisense-for-the-json-file-in-visual-studio-code) * [Questions and comments](#questions-and-comments) * [Additional resources](#additional-resources) @@ -16,48 +13,28 @@ Custom functions (similar to user-defined functions, or UDFs) are JavaScript fun * Oct 27, 2017: Initial version. * April 23, 2018: Revised and expanded. -* May 7, 2018: Updated for the Build preview release of custom functions +* June 1, 2018: Bug fixes. ## Prerequisites -* Install Office 2016 for Windows or Mac and join the [Office Insider](https://products.office.com/en-us/office-insider) program. You must also have Office build build 9325+ on Windows or 13.329+ on Mac. +* 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: +On a machine with a valid instance of an Excel Insider build installed, follow these instructions to use this custom function sample add-in: -1. Publish the code files (HTML, JS, and JSON) to localhost. -2. Replace `http://127.0.0.1:8080` in the manifest file (there are 4 occurrences) with the URL you used, if needed (you might be using a different port number). -3. Sideload the manifest using the instructions found at . -4. Test a custom function by entering `=CONTOSO.ADD42` in a cell. -5. Try the other functions in the sample: `=CONTOSO.ADD42ASYNC`, `CONTOSO.ISPRIME`, `CONTOSO.NTHPRIME`, `CONTOSO.GETDAY`, `CONTOSO.INCREMENTVALUE`, and `CONTOSO.SECONDHIGHEST`. -7. Follow @OfficeDev on Twitter for updates, post suggestions to the [Excel Add-ins UserVoice page](https://officespdev.uservoice.com/forums/224641-feature-requests-and-feedback/category/163563-add-in-excel) and tag Stack Overflow questions with the [custom-functions-excel](https://stackoverflow.com/questions/tagged/custom-functions-excel) tag. +1. On the machine where your custom functions project is installed, follow the instructions to install the self-signed certificates (https://github.com/OfficeDev/generator-office/blob/master/src/docs/ssl.md) . +2. From a command prompt from within your custom functions project directory, run `npm run start` to start a localhost server instance. +3. Run `npm run sideload` to launch Excel and load the custom functions add-in. Additonal information on sideloading can be found at . +4. After Excel launches, you will need to register the custom-functions add-in to work around a bug: + a. On the upper-left-hand side of Excel, there is a small hexagon icon with a dropdown arrow. The icon is to right of the Save icon. + b. Click on this dropdown arrow and then click on the Custom Functions Sample add-in to register it. +5. Test a custom function by entering `=CONTOSO.ADD42(num)` in a cell. +6. Try the other functions in the sample: `=CONTOSO.ADD42ASYNC(num, num)`, `CONTOSO.ISPRIME(num)`, `CONTOSO.NTHPRIME(num)`, `CONTOSO.GETDAY()`, `CONTOSO.INCREMENTVALUE(increment)`, and `CONTOSO.SECONDHIGHEST(range)`. +7. 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**. +8. Follow @OfficeDev on Twitter for updates and send feedback to . -## Making changes -If you make changes to the sample functions code (in the JS file), close and reopen Excel to test them. - -If you change the functions metadata (in the JSON file), close Excel and delete your cache folder `Users//AppData/Local/Microsoft/Office/16.0/Wef/CustomFunctions`. Then re-insert the add-in using **Insert** > **My Add-ins**. - -## Debugging -Debugging is only available for asynchronous functions on Excel for Windows currently. To debug: - -1. Enable script debugging in Internet Explorer (IE > Options > Advanced). -2. Trigger an asynchronous function in Excel (like `CONTOSO.ADD42ASYNC`). This step ensures that the asynchronous function process is loaded invisibly and ready for debugging. -3. Attach a debugger to the hidden iexplore.exe script process (you could use the [Windows F12 debugger](https://docs.microsoft.com/en-us/office/dev/add-ins/testing/debug-add-ins-using-f12-developer-tools-on-windows-10) or Visual Studio). - -## Intellisense for the JSON file in Visual Studio Code -For intellisense to help you edit the JSON file, follow these steps: - -1. Open the JSON file (it has a .json extension) in Visual Studio Code. -2. If you are starting a new file from scratch, add the following to the top of the file: - - ```js - { - "$schema": "https://developer.microsoft.com/en-us/json-schemas/office-js/custom-functions.schema.json", - ``` -3. Press **Ctrl+Space** and intellisense will prompt you with a list of all items that are valid at the cursor point. For example, if you pressed **Ctrl+Space** immediately after the `"$schema"` line, you are prompted to enter `functions`, which is the only key that is valid at that point. Select it and the `"functions": []` array is entered. If the cursor is between the `[]`, then you are prompted to enter an empty object as a member of the array. If the cursor is in the object, then you are prompted with a list of the keys that are valid in the object. - -## Feedback +## 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. @@ -72,4 +49,4 @@ Questions about Microsoft Office 365 development in general should be posted to 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. +Copyright (c) 2017 Microsoft Corporation. All rights reserved. \ No newline at end of file diff --git a/customfunctions.json b/config/customfunctions.json similarity index 95% rename from customfunctions.json rename to config/customfunctions.json index e0059fd..83035c7 100644 --- a/customfunctions.json +++ b/config/customfunctions.json @@ -1,7 +1,8 @@ { + "$schema": "https://developer.microsoft.com/en-us/json-schemas/office-js/custom-functions.schema.json", "functions": [ { - "name": "ADD42", + "name": "ADD42", "description": "adds 42 to the input numbers", "helpUrl": "http://dev.office.com", "result": { @@ -97,6 +98,7 @@ "description": "gets the current day of the week", "helpUrl": "http://dev.office.com", "result": { + "dimensionality": "scalar", "type": "string" }, "parameters": [], diff --git a/customfunctions.xml b/config/manifest.xml similarity index 75% rename from customfunctions.xml rename to config/manifest.xml index 73a397c..bb82aa0 100644 --- a/customfunctions.xml +++ b/config/manifest.xml @@ -4,17 +4,17 @@ xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp"> - b12101b4-2706-4128-98b2-d8a1842131a3 + b12101b1-2706-4128-98b2-d6a1842131a3 1.0.0.0 Contoso en-US - + - + ReadWriteDocument @@ -38,9 +38,9 @@ - - - + + + diff --git a/config/web.config b/config/web.config new file mode 100644 index 0000000..dccc19c --- /dev/null +++ b/config/web.config @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file diff --git a/config/webpack.config.js b/config/webpack.config.js new file mode 100644 index 0000000..15a4498 --- /dev/null +++ b/config/webpack.config.js @@ -0,0 +1,42 @@ +const HtmlWebpackPlugin = require('html-webpack-plugin'); + +module.exports = { + entry: { + customfunctions: ["./src/customfunctions.js"], + }, + resolve: { + extensions: ['.ts', '.tsx', '.html', '.js'] + }, + module: { + rules: [ + { + test: /\.tsx?$/, + exclude: /node_modules/, + use: 'ts-loader' + }, + { + test: /\.html$/, + exclude: /node_modules/, + use: 'html-loader' + }, + { + test: /\.(png|jpg|jpeg|gif)$/, + use: 'file-loader' + } + ] + }, + plugins: [ + new HtmlWebpackPlugin({ + template: './index.html', + chunks: ['customfunctions'] + }) + ], + devServer: { + port: 3000, + hot: true, + inline: true, + headers: { + "Access-Control-Allow-Origin": "*" + } + } +}; \ No newline at end of file diff --git a/customfunctions.js b/customfunctions.js deleted file mode 100644 index 6ebba47..0000000 --- a/customfunctions.js +++ /dev/null @@ -1,69 +0,0 @@ -function ADD42(num1, num2) { - return num1 + num2 + 42; -} - -// The following function is an example of an asynchronous function: -function ADD42ASYNC(num1, num2) { - // waits 1 second before returning the result - return new OfficeExtension.Promise(function (resolve) { - setTimeout(function () { - resolve(num1 + num2 + 42); - }, 1000); - }); -} - -// The following function is an example that returns a boolean value: -function ISPRIME(num) { - if (num <= 1 || !Number.isInteger(num)) return false; // validates input - // checks natural numbers below the square root (not optimal) - for (var factor = Math.floor(Math.sqrt(num)); factor > 1; factor--) { - if (num % factor === 0) return false; - } - return true; -} - -// The following function is an example that's computation-intensive for high inputs: -function NTHPRIME(n) { - var primeCount = 0; - for (var num = 2; primeCount < n; num++) { - if (ISPRIME(num)) primeCount++; - } - return num - 1; -} - -// The following function is an example that returns a string: -function GETDAY() { - var d = new Date(); - var days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]; - return days[d.getDay()]; -} - -// The following function is an example that streams values: -function INCREMENTVALUE(increment, caller) { - var result = 0; - var myInterval = setInterval(function () { - result += increment; - caller.setResult(result); - }, 1000); - caller.onCanceled = function () { - clearInterval(myInterval); - }; -} - -// The following function is an example that uses a range of cells: -function SECONDHIGHEST(range) { - var highest = range[0][0], secondHighest = range[0][0]; - for (var i = 0; i < range.length; i++) { - for (var j = 0; j < range[i].length; j++) { - if (range[i][j] >= highest) { - secondHighest = highest; - highest = range[i][j]; - } - else if (range[i][j] >= secondHighest) { - secondHighest = range[i][j]; - } - } - } - return secondHighest; -} - diff --git a/customfunctions.html b/index.html similarity index 72% rename from customfunctions.html rename to index.html index 19c1d14..b7c65ec 100644 --- a/customfunctions.html +++ b/index.html @@ -1,20 +1,13 @@  - + - - + custom-functions-preview - - + @@ -27,8 +20,10 @@
  • =CONTOSO.NTHPRIME returns the Nth prime. Watch out - it needs a lot of calculation if N is big!
  • =CONTOSO.GETDAY returns the current day of the week as a string.
  • =CONTOSO.SECONDHIGHEST lets you select a range of data and finds the second highest number.
    • +
  • =CONTOSO.INCREMENTVALUE increments the value by the number specified.
    • - To change the functions, edit customfunctions.js and customfunctions.json. To change the prefix, edit customfunctions.xml. + To change the functions, edit src/customfunctions.js and config/customfunctions.json. To change the prefix, edit config/<%= projectDisplayName %>-manifest.xml. For more information, see https://aka.ms/customfunctions. + diff --git a/package.json b/package.json new file mode 100644 index 0000000..5bedca5 --- /dev/null +++ b/package.json @@ -0,0 +1,35 @@ +{ + "name": "excel-custom-functions", + "version": "1.0.0", + "description": "Create Excel functions using JavaScript.", + "main": "customfunctions.js", + "scripts": { + "start": "webpack-dev-server --mode development --https --key ./certs/server.key --cert ./certs/server.crt --cacert ./certs/ca.crt --port 3000 --hot --inline", + "sideload": "office-toolbox sideload -m ./config/<%= projectDisplayName %>-manifest.xml -a Excel", + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/OfficeDev/Excel-Custom-Functions.git" + }, + "author": "", + "license": "ISC", + "bugs": { + "url": "https://github.com/OfficeDev/Excel-Custom-Functions/issues" + }, + "homepage": "https://github.com/OfficeDev/Excel-Custom-Functions#readme", + "devDependencies": { + "typescript": "^2.8.1", + "office-toolbox": "^0.1.0", + "@types/office-js": "^0.0.37", + "@types/jquery": "^2.0.39", + "file-loader": "^1.1.11", + "html-loader": "^0.5.5", + "html-webpack-plugin": "^3.0.7", + "office-addin-validator": "^1.0.1", + "ts-loader": "^4.1.0", + "webpack": "^4.1.1", + "webpack-cli": "^2.0.12", + "webpack-dev-server": "^3.1.1" + } +} \ No newline at end of file diff --git a/src/customfunctions.js b/src/customfunctions.js new file mode 100644 index 0000000..e3c65bb --- /dev/null +++ b/src/customfunctions.js @@ -0,0 +1,69 @@ +function ADD42(num1, num2) { + return num1 + num2 + 42; +} + +// The following function is an example of an asynchronous function: +function ADD42ASYNC(num1, num2) { + // waits 1 second before returning the result + return new OfficeExtension.Promise(function(resolve) { + setTimeout(function() { + resolve(num1 + num2 + 42); + }, 1000); + }); +} + +// The following function is an example that returns a boolean value: +function ISPRIME(num) { + if(num <= 1 || !Number.isInteger(num)) return false; // validates input + // checks natural numbers below the square root (not optimal) + for(var factor = Math.floor(Math.sqrt(num)); factor > 1; factor--){ + if(num % factor == 0) return false; + } + return true; +} + +// The following function is an example that's computation-intensive for high inputs: +function NTHPRIME(n){ + var primeCount = 0; + for(var num = 2; primeCount < n; num++){ + if(ISPRIME(num)) primeCount++; + } + return num - 1; +} + +// The following function is an example that returns a string: +function GETDAY() { + var d = new Date(); + var days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]; + return days[d.getDay()]; +} + +// The following function is an example that streams values: +function INCREMENTVALUE(increment, caller){ + var result = 0; + var myInterval = setInterval(function(){ + result += increment; + caller.setResult(result); + }, 1000); + caller.onCanceled = function(){ + clearInterval(myInterval); + } +} + +// The following function is an example that uses a range of cells: +function SECONDHIGHEST(range){ + var highest = range[0][0], secondHighest = range[0][0]; + for(var i = 0; i < range.length;i++){ + for(var j = 0; j < range[i].length;j++){ + if(range[i][j] >= highest){ + secondHighest = highest; + highest = range[i][j]; + } + else if(range[i][j] >= secondHighest){ + secondHighest = range[i][j]; + } + } + } + return secondHighest; +} +