diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 000000000..b54f7a970 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,38 @@ + + +## Expected Behavior + + +## Current Behavior + + + +## Steps to Reproduce, or Live Example + + + +* Link to live example: ______ + + +* Additional details: + 1. ______ + 2. ______ + 3. ______ + +## Context + + + +## Your Environment + +* Platform [PC desktop, Mac, iOS, Office Online]: ______ +* Host [Excel, Word, PowerPoint, etc.]: ______ +* Office version number: ______ +* Operating System: ______ +* Browser (if using Office Online): ______ + +## Useful logs + +- [ ] Console errors +- [ ] Screenshots +- [ ] Test file (if only happens on a particular file) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..24143f8e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,58 @@ +--- +name: Bug report +about: Create a report to help us improve office.js +title: '' +labels: '' +assignees: '' + +--- + + +# Provide required information needed to triage your issue + +## Your Environment + +* Platform [PC desktop, Mac, iOS, Office on the web]: ______ +* Host [Excel, Word, PowerPoint, etc.]: ______ +* Office version number: ______ +* Operating System: ______ +* Browser (if using Office on the web): ______ + +## Expected behavior + + +## Current behavior + + + +## Steps to reproduce + +1. ______ +2. ______ +3. ______ + +## Link to live example(s) + + + +1. ______ +2. ______ +3. ______ + +# Provide additional details + +1. ______ +2. ______ +3. ______ + +## Context + + + +## Useful logs + +- [ ] Console errors +- [ ] Screenshots +- [ ] Test file (if only happens on a particular file) + +Thank you for taking the time to report an issue. Our triage team will respond to you in less than 72 hours. Normally, response time is <10 hours Monday through Friday. We do not triage on weekends. diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 000000000..d49332811 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,15 @@ +--- +name: Feature request +about: To request a new feature in office.js or any other aspect of the Office developer + platform, post your request on the Microsoft 365 Developer Platform Ideas Forum +title: '' +labels: '' +assignees: '' + +--- + +## Microsoft 365 Developer Platform Ideas Forum + +We're moving away from UserVoice feedback sites on a product-by-product basis throughout the 2021 calendar year. Later in 2021, we will leverage a 1st party solution for customer feedback. Meanwhile, please post feature requests and suggestions at the [Microsoft 365 Developer Platform Ideas Forum](https://techcommunity.microsoft.com/t5/microsoft-365-developer-platform/idb-p/Microsoft365DeveloperPlatform). + +For more information, see [UserVoice pages](https://support.microsoft.com/topic/uservoice-pages-430e1a78-e016-472a-a10f-dc2a3df3450a). diff --git a/.github/ISSUE_TEMPLATE/how-to-question.md b/.github/ISSUE_TEMPLATE/how-to-question.md new file mode 100644 index 000000000..9c5345889 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/how-to-question.md @@ -0,0 +1,21 @@ +--- +name: How-to question +about: To ask questions about how to use office.js or the Office developer platform, + please post your question on Microsoft Q&A +title: '' +labels: '' +assignees: '' + +--- + +## Post how-to questions about your code on Microsoft Q&A + +We have several forums where you can ask the developer community questions about your code. Try one of the following forums to ask technical questions about: +- [Developing Office Add-ins for Word, Excel, PowerPoint, Outlook, Project, Visio, and OneNote](https://docs.microsoft.com/answers/topics/office-addins-dev.html) +- [Access programming in Office](https://docs.microsoft.com/answers/topics/office-access-dev.html) +- [Developing COM or VSTO Add-ins for Office](https://docs.microsoft.com/answers/topics/office-vsto-com-dev.html) +- [Office JavaScript API](https://docs.microsoft.com/answers/topics/office-js-dev.html) +- [SharePoint and OneDrive development](https://docs.microsoft.com/answers/topics/sharepoint-dev.html) +- [Deploying and publishing Office or SharePoint apps to AppSource](https://docs.microsoft.com/answers/topics/microsoft-365-apps-publishing-dev.html) + +For additional information about JavaScript programming, see the [JavaScript at Microsoft](https://docs.microsoft.com/javascript/) community hub. diff --git a/.github/fabricbot.json b/.github/fabricbot.json new file mode 100644 index 000000000..e624e953b --- /dev/null +++ b/.github/fabricbot.json @@ -0,0 +1,681 @@ +{ + "version": "1.0", + "tasks": [ + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "config": { + "taskName": "Add needs triage label to new issues", + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "opened" + } + }, + { + "operator": "not", + "operands": [ + { + "name": "isAssignedToSomeone", + "parameters": {} + } + ] + }, + { + "operator": "and", + "operands": [ + { + "operator": "not", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Host [Excel, Word, PowerPoint, etc.]: Word" + } + } + ] + }, + { + "operator": "not", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Word.run" + } + } + ] + }, + { + "operator": "not", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Host [Excel, Word, PowerPoint, etc.]: Excel" + } + } + ] + }, + { + "operator": "not", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Excel.run" + } + } + ] + } + ] + } + ] + }, + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Needs: triage :mag:" + } + } + ], + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "config": { + "taskName": "Add no recent activity label to issues", + "frequency": [ + { + "weekDay": 0, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 1, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 2, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 3, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 4, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 5, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 6, + "hours": [ + 1, + 4, + 7, + 10, + 13, + 16, + 19, + 22 + ], + "timezoneOffset": -8 + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: author feedback" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 4 + } + }, + { + "name": "noLabel", + "parameters": { + "label": "Status: no recent activity" + } + } + ], + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Status: no recent activity" + } + }, + { + "name": "addReply", + "parameters": { + "comment": "This issue has been automatically marked as stale because it is marked as needing author feedback but has not had any activity for **4 days**. It will be closed if no further activity occurs **within 3 days of this comment**. Thank you for your interest in Office Add-ins!" + } + } + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "config": { + "taskName": "Close stale issues", + "frequency": [ + { + "weekDay": 0, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 1, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 2, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 3, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 4, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 5, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + }, + { + "weekDay": 6, + "hours": [ + 0, + 3, + 6, + 9, + 12, + 15, + 18, + 21 + ], + "timezoneOffset": -8 + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: author feedback" + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "Status: no recent activity" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 3 + } + } + ], + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "This issue has been closed due to inactivity. Please comment if you still need assistance and we'll re-open the issue." + } + }, + { + "name": "closeIssue", + "parameters": {} + } + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "config": { + "taskName": "Remove no recent activity label when there is activity in an issue", + "conditions": { + "operator": "and", + "operands": [ + { + "operator": "not", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "closed" + } + } + ] + }, + { + "name": "hasLabel", + "parameters": { + "label": "Status: no recent activity" + } + } + ] + }, + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "Status: no recent activity" + } + } + ], + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueCommentResponder", + "version": "1.0", + "config": { + "taskName": "Remove no recent activity label when an issue is commented on", + "conditions": { + "operator": "and", + "operands": [ + { + "name": "hasLabel", + "parameters": { + "label": "Status: no recent activity" + } + } + ] + }, + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "Status: no recent activity" + } + } + ], + "eventType": "issue", + "eventNames": [ + "issue_comment" + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueCommentResponder", + "version": "1.0", + "config": { + "taskName": "Replace needs author feedback label with needs attention label when the author comments on an issue", + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "created" + } + }, + { + "name": "isActivitySender", + "parameters": { + "user": { + "type": "author" + } + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: author feedback" + } + } + ] + }, + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Needs: attention :wave:" + } + }, + { + "name": "removeLabel", + "parameters": { + "label": "Needs: author feedback" + } + } + ], + "eventType": "issue", + "eventNames": [ + "issue_comment" + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "opened" + } + }, + { + "operator": "not", + "operands": [ + { + "name": "isAssignedToSomeone", + "parameters": {} + } + ] + }, + { + "operator": "or", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Host [Excel, Word, PowerPoint, etc.]: Word" + } + }, + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Word.run" + } + } + ] + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Area: Word" + } + }, + { + "name": "assignToUser", + "parameters": { + "user": "ZYUN-MSFT" + } + }, + { + "name": "addLabel", + "parameters": { + "label": "Needs: attention :wave:" + } + }, + { + "name": "addReply", + "parameters": { + "comment": "Thank you for letting us know about this issue. We will take a look shortly. Thanks." + } + } + ], + "taskName": "Add label for Word API related issues and assign it to OCE driver." + }, + "disabled": false + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "opened" + } + }, + { + "operator": "not", + "operands": [ + { + "name": "isAssignedToSomeone", + "parameters": {} + } + ] + }, + { + "operator": "or", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Host [Excel, Word, PowerPoint, etc.]: Excel" + } + }, + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Excel.run" + } + } + ] + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "Add label for Excel API related issues and assign it to OCE driver.", + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Area: Excel" + } + }, + { + "name": "assignToUser", + "parameters": { + "groupId": "", + "user": "ZYUN-MSFT" + } + }, + { + "name": "addLabel", + "parameters": { + "label": "Needs: attention :wave:" + } + }, + { + "name": "addReply", + "parameters": { + "comment": "Thank you for letting us know about this issue. We will take a look shortly. Thanks." + } + } + ] + } + } + ], + "userGroups": [] +} diff --git a/.github/images/script-lab-substitute-refs.png b/.github/images/script-lab-substitute-refs.png new file mode 100644 index 000000000..c76a55139 Binary files /dev/null and b/.github/images/script-lab-substitute-refs.png differ diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 000000000..5280e7a85 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,38 @@ +# This workflow will run the deployment.script +# GitHug Action Reference: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions + +name: NPM Package Publish Script + +on: + push: + branches: [ custom-*, beta, release ] + +jobs: + build: + + runs-on: windows-latest + + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Use Node.js + uses: actions/setup-node@v2 + with: + node-version: '14.x' + - name: Clean Install + run: npm ci + working-directory: deployment.script + - name: Build + run: npm run build --if-present + working-directory: deployment.script + - name: Deploy + env: + BRANCH_NAME: ${{ github.ref }} + # Override Previous Travis environment variables + TRAVIS: true + TRAVIS_BRANCH: ${{ github.ref }} + TRAVIS_PULL_REQUEST: false + TRAVIS_BUILD_DIR: ${{ github.workspace }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: npm run deploy --if-present + working-directory: deployment.script \ No newline at end of file diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..6baa06c36 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,19 @@ +language: node_js + +git: + depth: 4 + +node_js: +- 10.10.0 + +before_install: +- cd deployment.script + +install: +- npm install + +before_script: +- npm run build + +script: +- npm run deploy diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 000000000..eada16bef --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,76 @@ +# MICROSOFT SOFTWARE LICENSE TERMS + +## MICROSOFT OFFICE JAVASCRIPT (OFFICE.JS) API LIBRARY + +These license terms are an agreement between Microsoft Corporation (or based on where you live, one of its affiliates) and you. Please read them. They apply to your use of the software named above, which includes the media on which you received it, if any, and supersede any other agreement referenced in the software that may apply to your use of the software. The terms also apply to any Microsoft + +- updates, +- supplements, +- Internet-based services, and +- support services + +for this software, unless other terms accompany those items. If so, those terms apply. + +**By using the software, you accept these terms. If you do not accept them, do not use the software.** + +**YOU MAY USE THE SOFTWARE SOLELY IN APPS DEVELOPED BY YOU THAT INTEROPERATE WITH MICROSOFT 365 PRODUCTS, APPS, AND SERVICES (REFERRED TO AS "AUTHORIZED APPS").** + +**IF YOU RECEIVE THE SOFTWARE AS PART OF OR IN CONNECTION WITH AN APPLICATION DEVELOPED BY A THIRD PARTY, THESE LICENSE TERMS DO NOT APPLY TO YOU. THE LICENSE TERMS APPLICABLE TO THE THIRD PARTY APPLICATION APPLY TO YOUR USE OF THE SOFTWARE.** + +**If you comply with these license terms, you have the rights below.** + +1. **INSTALLATION AND USE RIGHTS.** You may install and use any number of copies of the software on your devices to design, develop and test Authorized Apps. You may also use any number of copies of the software as part of the Authorized Apps you develop for your internal business purposes. +1. **ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS.** + 1. **Distributable Code.** The software contains code that you are permitted to distribute (a) as part of the Authorized Apps you develop; or (b) in a stand-alone manner, but for the sole purpose of enabling the use of or updating the Authorized Apps you develop, if you comply with the terms below. + 1. **Right to Use and Distribute. "Distributable Code" is code from the Office.JS API Library.** + - You may copy and distribute all the code provided in the source code form in the software in its original form. + - Third Party Distribution. You may permit the distributor of the Authorized Apps to copy and distribute the Distributable Code as part of the Authorized Apps, or in a stand-alone manner solely for the purpose of enabling the use of or updating the Authorized Apps. + 1. **Distribution Requirements. For any Distributable Code you distribute, you must** + - add significant primary functionality to it in Authorized Apps; + - distribute the Distributable Code only for use with the Authorized Apps; + - require distributors and external end users to agree to terms that protect it at least as much as this agreement; include in these terms, user interface or documentation, a notice that Microsoft is not responsible for maintaining, updating or supporting the Authorized Apps + - display your valid copyright notice on Authorized Apps; and + - indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of Authorized Apps. + 1. **Distribution Restrictions. You may not** + - alter any copyright, trademark or patent notice in the Distributable Code; + - use Microsoft’s trademarks in the names of Authorized Apps in a way that suggests Authorized Apps come from or are endorsed by Microsoft; + - include Distributable Code in malicious, deceptive or unlawful programs; + - modify the Distributable Code; or + - modify or distribute the source code of any Distributable Code so that any part of it becomes subject to an Excluded License. An Excluded License is one that requires, as a condition of use, modification or distribution, that + - the code be disclosed or distributed in source code form; or + - others have the right to modify it. +1. **PRE-RELEASE SOFTWARE.** If you are using a pre-release or beta version of the software, the terms of this section also apply to the pre-release or beta software: + 1. The software is a pre-release version and is provided "AS-IS," "WITH ALL FAULTS," AND "AS AVAILABLE." It may not operate correctly, and it may be different from the commercially released version. + 1. **Confidential Information.** The software, including its user interface, features and documentation, is confidential and proprietary to Microsoft and its suppliers. + 1. **Use.** For five years after installation of the software or its commercial release, whichever is first, you may not disclose confidential information to third parties. You may disclose confidential information only to your employees and consultants who need to know the information. You must have written agreements with them that protect the confidential information at least as much as this agreement. + 1. **Survival.** Your duty to protect confidential information survives this agreement. + 1. **Exclusions.** You may disclose confidential information in response to a judicial or governmental order. You must first give written notice to Microsoft to allow it to seek a protective order or otherwise protect the information. Confidential information does not include information that: + 1. becomes publicly known through no wrongful act; + 1. you received from a third party who did not breach confidentiality obligations to Microsoft or its suppliers; or + 1. you developed independently. +1. **FEEDBACK.** If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You also give to third parties, without charge, any patent rights needed for their products, technologies and services to use or interface with any specific parts of a Microsoft software or service that includes the feedback. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because we include your feedback in them. These rights survive this agreement. +1. **SCOPE OF LICENSE.** You may only use the software in Authorized Apps. The software is licensed, not sold. This agreement only gives you some rights to use the software. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways. You may not + - work around any technical limitations in the software; + - use the software in any way that intentionally harms services provided by Microsoft or impairs anyone else’s use of such services; + - use the software to try to gain unauthorized access to any service, data, account or network by any means; + - make more copies of the software than specified in this agreement or allowed by applicable law, despite this limitation; + - publish the software for others to copy; or + - rent, lease or lend the software. +1. **BACKUP COPY.** You may make one backup copy of the software. You may use it only to reinstall the software. +1. **DOCUMENTATION.** Any person that has valid access to your computer or internal network may copy and use the documentation for your internal, reference purposes. +1. **TRANSFER TO A THIRD PARTY.** The first user of the software may transfer it and this agreement directly to a third party. Before the transfer, that party must agree that this agreement applies to the transfer and use of the software. The first user must uninstall the software before transferring it separately from the device. The first user may not retain any copies. +1. **EXPORT RESTRICTIONS.** The software is subject to United States export laws and regulations. You must comply with all domestic and international export laws and regulations that apply to the software. These laws include restrictions on destinations, end users and end use. For additional information, see www.microsoft.com/exporting. +1. **SUPPORT SERVICES.** Because this software is "as is," we will not provide support services for it. +1. **ENTIRE AGREEMENT.** This agreement, and the terms for supplements, updates, Internet-based services and support services that you use, are the entire agreement for the software and support services. +1. **APPLICABLE LAW.** + 1. **United States.** If you acquired the software in the United States, Washington state law governs the interpretation of this agreement and applies to claims for breach of it, regardless of conflict of laws principles. The laws of the state where you live govern all other claims, including claims under state consumer protection laws, unfair competition laws, and in tort. + 1. **Outside the United States.** If you acquired the software in any other country, the laws of that country apply. +1. **LEGAL EFFECT.** This agreement describes certain legal rights. You may have other rights under the laws of your country. You may also have rights with respect to the party from whom you acquired the software. This agreement does not change your rights under the laws of your country if the laws of your country do not permit it to do so. +1. **DISCLAIMER OF WARRANTY. The software is licensed "as-is." You bear the risk of using it. Microsoft gives no express warranties, guarantees or conditions. You may have additional consumer rights under your local laws which this agreement cannot change. To the extent permitted under your local laws, Microsoft excludes the implied warranties of merchantability, fitness for a particular purpose and non-infringement.** +1. **LIMITATION ON AND EXCLUSION OF REMEDIES AND DAMAGES. You can recover from Microsoft and its suppliers only direct damages up to U.S. $5.00. You cannot recover any other damages, including consequential, lost profits, special, indirect or incidental damages.** + This limitation applies to + + - anything related to the software, services, content (including code) on third party Internet sites, or third party programs; and + - claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law. + + It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages. diff --git a/README.md b/README.md new file mode 100644 index 000000000..fd64fc75b --- /dev/null +++ b/README.md @@ -0,0 +1,133 @@ +[![NPM Deployment Status](https://travis-ci.org/OfficeDev/office-js.svg?branch=release)](https://travis-ci.org/OfficeDev/office-js/builds) + +# Office JavaScript APIs + +The JavaScript API for Office enables you to create web applications that interact with the object models in Office host applications. Your application will reference the office.js library, which is a script loader. The office.js library loads the object models applicable to the Office application running the add-in. + +
+ +## About the NPM package + +The NPM package for Office.js is a copy of what gets published to the official "evergreen" Office.js CDN, at ****. + +The Office.js CDN contains all currently available Office.js APIs at any moment in time. + +Each Office.js NPM package contains only Office.js APIs available on the Office.js CDN when the NPM package version was created. + +### Target scenarios + +The NPM package for Office.js is intended as a way to obtain an offline copy (non-CDN) of the Office.js files, which can then be statically serve from your own site instead of using the CDN. + +This NPM package is provided for the following scenarios. + +1. Development of an add-in behind a firewall, when accessing the Office.js CDN isn't possible. +2. Offline access to the Office.js APIs to facilitate offline debugging. + +**Important**: Office Add-ins published to AppSource must use the CDN reference. Offline Office.js references are only appropriate for internal development and debugging scenarios. + +### Best practices + +Best practices for using the Office.js NPM package include: + +- Refreshing the NPM package periodically to access new APIs and bug fixes. + +- [Using the NPM package according to the instructions](#use-the-npm-package). Do not import the NPM package as commonly done with other NPM packages. + +- Do not use the NPM package in an add-in intended for publication to [AppSource](https://appsource.microsoft.com/marketplace/apps?product=office). Add-ins that are published to AppSource must use the Office.js CDN. + +- [Using TypeScript definitions for Office.js](#intellisense-definitions). + +### Support + +The Office.js CDN is the official supported source for Office Add-ins. + +For the NPM package sourced through this repository, only the latest version of the package is supported. No support and no patches will be provided for previous versions of the package. The frequency of the updates to this repository and related NPM package to match the CDN version is not guaranteed. + +Outlook add-ins don't support hosting Office.js offline due to network access requirements for dependencies like the Microsoft Ajax library. + +
+ +## Install the NPM package + +To install "office-js" locally via the NPM package, run the following command. + +> npm install @microsoft/office-js --save + +
+ +Our policy requires that developers always reference the latest version of Office.js library. This is to ensure that essential product updates are served quickly to the Office Add-ins by always referencing the latest release of the library for a given version, such as Generally Available (GA) version. Given that the latest Office.js release is backward-compatible with prior releases, it's safe to update to the most recent release of the library when one is available. Hence, only the latest version of Office.js NPM package is made available for installation. + +## Use the NPM package + +Installing the NPM package locally creates a set of static Office.js files in the `node_modules\@microsoft\office-js\dist` folder of the directory where you ran the `npm install` command. To use the NPM package, do the following: + +1. Either manually or as part of a build script (e.g., `CopyWebpackPlugin` if you're using Webpack) have the files served from a destination of your choosing (e.g., from the `/assets/office-js/` directory of your web server). + +2. Reference that location in a ` +``` + +
+ +## IntelliSense definitions + +TypeScript definitions for Office.js are available. + +- latest **RELEASE** version of Office.js: + - DefinitelyTyped: + - @types: `@types/office-js` + > npm install @types/office-js --save-dev +- latest **BETA** version of Office.js: + - DefinitelyTyped: + - @types: `@types/office-js-preview`. + > npm install @types/office-js-preview --save-dev +- **any** version: + - Inside of the NPM package, under `dist/office.d.ts` + - In this repo: [dist/office.d.ts](dist/office.d.ts) + +### Use TypeScript definitions with the NPM package + +If you're using the Office.js NPM package for the [firewall scenario](#target-scenarios) and want a d.ts file that precisely matches the JS contents, use the d.ts file that's located within the `/dist/office.d.ts` folder of the NPM package. Achieve this by using a [triple-slash reference](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). + +- **TIP**: If you create a `references.ts` file at the root of the project, simply point the reference to `office.d.ts` there. + +If you don't need the [firewall scenario](#target-scenarios), don't use the Office.js NPM package. Obtain the TypeScript definitions by using `@types/office-js` and reference the Office.js CDN at . + +### Enable IntelliSense in Visual Studio + +Visual Studio 2017+ can use these same TypeScript definitions, even for regular JavaScript. For JavaScript IntelliSense in earlier versions of Visual Studio, an `office-vsdoc.js` is available alongside the `office.js` file. As long as you have a `Scripts/_references.js` file in your VS project, and as long as you substitute the existing triple-slash reference (`/// `) with the new location (the `-vsdoc` part gets substituted automatically, so use it just as you would in a `