Category: JavaScript API for Office

While looking for references and/or resources to support my research on the ‘new’ Office Add-ins I repeatedly stumbled over the sample chapters of one book in particular:

Building Office Add-ins using Office.js

https://leanpub.com/buildingofficeaddins

The book is published on LeanPub and this means that it is work in progress. The author is continuously working on the manuscript and is potentially never finished. Even the pricing is flexible, the author specified a minimum and a recommended fee. You can decide if you want to pay the minimum, recommended or even a higher amount for the book. At this time, the minimum is set to $15.99 and the suggested price is set to $19.99 but as said you can up the price to $500 if you like

You don’t have to worry the information provided is legit, the book is written by Michael Zlatkovsky who works at the Office Extensibility Platform team at Microsoft. The information is therefor right from the source, even better … Michael has been a key participant in the design of the new Office 2016 wave of Office.js APIs:

https://leanpub.com/u/Zlatkovsky

Michael and I go back quite some time already, I met Michael years ago, I thinks around 2012, when we were all still developing VSTO Add-ins. Michael always was very helpful and supporting when I needed information or struggled with issues.

Now get on over to LeanPub site and buy the book!

Did I mention already where to get it?
https://leanpub.com/buildingofficeaddins

I’m sure it will help you and me in learning the details of developing Office Add-ins using Office.js

Yesterday we’ve seen the minimal code running to insert a bit of text at the selected Range using Word.RequestContext:

(() => {

   async function MinimalWordmethod() {

      // Create the client request context. You’ll do this for all Word add-ins.

      var ctx = new Word.RequestContext();

      // Do your things here, such as ..

      var range = ctx.document.getSelection();

      range.insertText("Test MinimalWordMethod", "After");

      await ctx.sync();

   }

   MinimalWordmethod();

})();

If you look however at the boilerplate code that is generated with a clean Yeoman project you find that RequestContext is never used, but instead of this you see Word.run(async (context) => { … });

Why is this and what is the difference? Well, I looked into this and found the answer on a piece of documentation from Michael Zlatkovsky, member of the Office Extensibility Platform team, here:

http://buildingofficeaddins.com/run

Michael explains it in his documentation but is written for Excel, however as you can read on the same page it is fully compliant with Word.run.

Here is a quote from the page:

You can think of the Excel.run as a boiler-plate preamble; it is the batch function that is the star of the show, but it needs a request context in order to start off the chain of OM calls. The Excel.run call is simply a means to that end, as it creates a new request context that it passes into the batch function.

Reading this quote explains that by using the <host>.run function you start a batch process, without the trouble of creating your context by yourself. The run function will take care of this for you. So instead of the code where you create your own context object as seen in the snippet above you should be able to run the following code:

(() => {
   async function MinimalWordmethod() {

         // Create the client request context. You’ll do this for al Word add-ins.
         await Word.run(async (context) => {

         // Do your things here, such as ..
         var range = context.document.getSelection();

         range.insertText("Test run MinimalWordMethod", "After");

         await context.sync();
      });
   }
   MinimalWordmethod();
})();

How to get the new minimal code running

Go back to the Yeoman project from yesterdays post, open the project folder and open the file app.ts in the src source folder.

Replace all the code from this file as seen in the top snippet with the code from the second, new snippet above. Save it and start your Add-in ‘server’ by running npm start in the root of your project.

Opening Word, with the installed Add-in will still show you the Add-in button:

By clicking the button the Taskpane is showing, just like we’ve seen before, but now you should see the words “Test run MinimalWordMethod” in your document:

Without creating your own context the Word.run function created its own context and the code still works. As you can see this helps you to take some effort out of your hand.

To be continued …