Giter VIP home page Giter VIP logo

officedev / word-add-in-angular2-stylechecker Goto Github PK

View Code? Open in Web Editor NEW
46.0 20.0 21.0 1.19 MB

Office Word web add-in that uses the LocationRelation and compareLocationWith APIs of the Word JavaScript APIs to perform a search and replace that skips some ranges based on their location relative to other ranges. The add-in is built on the Angular 2.0 framework, and it also shows how to use the design samples from [Office Add-in UX Design Patterns Code](https://github.com/OfficeDev/Office-Add-in-UX-Design-Patterns-Code).

License: Other

CSS 2.99% TypeScript 8.94% HTML 3.08% JavaScript 84.98%

word-add-in-angular2-stylechecker's Introduction

page_type products languages extensions description
sample
office-word
office-365
javascript
contentType technologies createdDate
samples
Add-ins
8/9/2016 11:08:27 AM
Learn how to create an add-in that uses the `LocationRelation` and `compareLocationWith` APIs of the Word JavaScript APIs to perform a search and replace that skips some ranges based on their location relative to other ranges.

Word Style Checking Add-in Built on Angular 2.0

Important Note 1: This repo is being archived because we do not have the staff to update it or to support Angular. It can still be used for the educational purposes described below.

Important Note 2: This sample has several security alerts. These vulnerabilities do not pose a problem for running and modifying this sample on your development computer, but do not use the vulnerable libraries in a production add-in. For example, it uses the latest lite-server (version 2.6.1) to host the add-in. This server package has a dependency on a version of the xmlhttprequest-ssl package that has a security vulnerability.

Learn how to create an add-in that uses the LocationRelation and compareLocationWith APIs of the Word JavaScript APIs to perform a search and replace that skips some ranges based on their location relative to other ranges. The add-in is built on the Angular 2.0 framework, and it also shows how to use the design samples from Office Add-in UX Design Patterns Code.

Table of Contents

Change History

August 1, 2016:

  • Initial version.

September 15 - October 17th, 2016:

  • Minor updates.

December 11th, 2020:

  • Changed system for creating and installing the SSL certificates for HTTPS.

May 23rd, 2023:

  • Archiving.

Prerequisites

  • Word 2016 for Windows, build 16.0.6727.1000 or later.
  • Node and npm The project is configured to use npm as both a package manager and a task runner. It is also configured to use the Lite Server built into npm as the web server that will host the add-in during development, so you can have the add-in up and running quickly. You are welcome to use another task runner or web server.
  • Git Bash (Or another git client.)

Configure the project

  1. In the folder where you want to put the project open a git bash shell and take these steps:

    1. Run git clone {URL of this repo} to clone this repo to your local machine. Your project will be created in a subfolder.
    2. In the bash shell, navigate to the root of the new project.
    3. Run npm install to install all of the dependencies itemized in the package.json file.
  2. Open a system Command Prompt as an administrator and take these steps:

    1. Navigate to the root of the project.

    2. Run the command: npx office-addin-dev-certs install --machine.

      If you get the following prompt, click Yes.

      Screenshot of a dialog that warns about the SSL certificate and asks user to accept or deny installation of it.

    3. Leave the Command Prompt open.

  3. In your code editor, open the bs-config.json file in the root of the project.

  4. Replace the string "YOUR-USER-NAME-ON-COMPUTER" in both places with your username on the computer.

  5. Save and close the file.

Deploy the add-in

Now you need to let Microsoft Word know where to find the add-in.

  1. Create a network share, or share a folder to the network.
  2. Place a copy of the Word-Add-in-Angular2-StyleChecker.xml manifest file, from the root of the project, into the shared folder.
  3. Launch Word and open a document.
  4. Choose the File tab, and then choose Options.
  5. Choose Trust Center, and then choose the Trust Center Settings button.
  6. Choose Trusted Add-ins Catalogs.
  7. In the Catalog Url field, enter the network path to the folder share that contains Word-Add-in-Angular2-StyleChecker.xml, and then choose Add Catalog.
  8. Select the Show in Menu check box, and then choose OK.
  9. A message is displayed to inform you that your settings will be applied the next time you start Microsoft Office. Close Word.

Run the project

In the Command Prompt, run npm start to start the web service. (The home page of the project may open in the default browser. Just close it. Add-ins can only run correctly in the context of an Office application.)

Start the add-in

  1. Restart Word and open a Word document.
  2. On the Insert tab in Word 2016, choose My Add-ins.
  3. Select the SHARED FOLDER tab.
  4. Choose Style Checker, and then select OK.
  5. If add-in commands are supported by your version of Word, the UI will inform you that the add-in was loaded.
  6. On the Home ribbon is a new group called Style Checker with a button labeled Show and a blue pencil icon. Click that button and the add-in will open to a page of instructions.

Note: The add-in will load in a task pane if add-in commands are not supported by your version of Word.

Test the add-in

  1. When you are finished with the instructions, click Get Started.
  2. When the Find and Replace page opens, there is a command bar at the top with a menu button. Click the button to open the menu.
  3. Select Insert sample content. Click the button again to close the menu. The document now has unformatted text about Office Add-ins, including a fictional quotation. The writer has used an "OAI" to abbreviate "Office Add-in" and so does the anonymous quotation.
  4. In the Find box enter "OAI".
  5. In the Replace box enter "Office Add-in".
  6. The change should not be made in the paragraph that is a direct quotation, so enter the number 2 in the Skip Paragraph Number box. This is the zero-based number of the paragraph.
  7. Select Replace. Every instance of "OAI" except the one in the skipped paragraph is changed.
  8. Experiment with other search and replace strings.

Note: This sample add-in accepts only one number in the Skip Paragraph Number box and you must have some number in the box. A production add-in would allow no paragraphs to be skipped or multiple paragraphs to be skipped and would have additional ways of designating which paragraphs should be skipped; such as skipping based on paragraph style.

Change the settings of the add-in

  1. Open the menu button on the command bar again and select Settings.
  2. On the Settings page, you'll see that by default the instructions page opens every time the add-in is run. Use the radio buttons to specify that the instructions page will appear only the first time that the add-in is run.
  3. Close the task pane and then relaunch the add-in by selecting the Show button again. The add-in will open with the Find and Replace page instead of the instructions page.
  4. Navigate to the Settings page again. You can select the Show Instructions button to open the instructions page, or change the instructions setting back to open the instructions page every time the add-in is run.

Understand the code

All of the code that uses the Office and Word JavaScript APIs is in the file word.document.service.ts. The compareLocationWith() method that this sample demonstrates is in the replaceFoundStringsWithExceptions() method.

The code first gets a collection of all the ranges that match the user's search term. It then gets a collection of all the paragraph ranges in the document.

let foundItems: Word.SearchResultCollection = context.document.body.search(searchString, { matchCase: false, matchWholeWord: true }).load(); let paras : Word.ParagraphCollection = context.document.body.paragraphs.load();

After the collections are loaded with a call of context.sync(), the code creates an array of the paragraph ranges that the user excludes from the replacement. (Note that excludedParagraph is a parameter passed to the method.)

let excludedRanges: Array<Word.Range> = []; excludedRanges.push(paras.items[excludedParagraph].getRange('Whole'));

The code then loops through the iterables to determine which search results are inside excluded paragraphs and which are not. For each search result, this fact is recorded in a IReplacementCandidate object. The compareLocationWith() method returns "Inside" if the search result is inside the excluded paragraph. It returns "Equal" if the search result is a paragraph by itself and has been excluded.

for (let i = 0; i < foundItems.items.length; i++) {
    for (let j = 0; j < excludedRanges.length; j++) {
        replacementCandidates.push({
            range: foundItems.items[i],
            locationRelation: foundItems.items[i].compareLocationWith(excludedRanges[j])
        });
    }
}

The replacement candidate objects are loaded with a call to context.sync() and then the code iterates through them, replacing the search string with the replace string only in the paragraphs which are not in an excluded paragraph.

replacementCandidates.forEach(function (item) {
    switch (item.locationRelation.value) {
        case "Inside":
        case "Equal":
            break;
        default:
            item.range.insertText(replaceString, 'Replace');
    }
});

See the replaceDocumentContent method of the same file to see how the Word insertText and nsertParagraph methods are used to insert sample content into the document.

See the rest of the code files to see how the design patterns from Office Add-in UX Design Patterns Code have been integrated into the Angular 2.0 framework.

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. If your question is about the Office JavaScript APIs, make sure that your questions are tagged with [office-js] and [API].

Additional resources

Copyright

Copyright (c) 2016 and 2020 Microsoft Corporation. All rights reserved.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

word-add-in-angular2-stylechecker's People

Contributors

alexjerabek avatar davidchesnut avatar dependabot[bot] avatar lauragra avatar lindalu-msft avatar microsoft-github-policy-service[bot] avatar o365devx avatar rick-kirkham avatar v-dobr avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

word-add-in-angular2-stylechecker's Issues

Add-in won't run due to certificate error

Unable to launch Style Checker demo add-in in Word 2016, Windows 10. Other sample add-ins work, but something is not right w/this particular add-in's certificate on my machine. Error appears at top of task pane: The content is blocked because it isn't signed by a valid security certificate. Have done the necessary steps to configure project, and tried the suggestions mentioned in
OfficeDev/generator-office#486 (although changing the bconfig.json file did not work for me, so I reverted to the original). Any tips beyond what has been suggested in #486 would be appreciated.

Update to use office generator

Thanks for the sample. This is good stuff. My question is that when I try to follow the current documentation on building my own Office add-in using angular, it suggests that we use the office generator and yeoman. It works great and creates an initial project, but I do not seem to be able to use any of the advanced Angular or typescript (javascript) stuff, like interfaces and types. Whenever I try to use those, the compiler complains.

Is there any way you can update this project to use Office generator? Or, should we be modeling our new add-ins after this style of programming?

Build issue

Hi
I have created word add-in using this sample but i'm facing issue to deploy application on server .
since it doesn't have angular cli i'm not able to create build. Can anyone suggest how to create production build ?
Its urgent

regads
chetan

.vscode directory

I cloned your repo and was playing around with it to start my own add-in project using Angular. I noticed you have a .vscode directory. What exactly is this for? I noticed that if I remove that directory a bunch of JS files are generated when running the server and put into my app directory. However, if I keep it, then those are removed from the app directory. Is this something necessary for any add-in using angular?

Using IIS Instead of Node.js

Hi,

I'm looking to expand the sample to incorporate some ASP.NET WebAPI services. How do I convert the sample to run in ISS rather than Node? Any help appreciated.

Failed on ng serve

Getting this error on ng serve

The serve command requires to be run in an Angular project, but a project definition could not be found.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.