Office Add-Ins: Working with Tables in Word. Part 1: Creation

In this article I will show how the Word JavaScript API can be utilized to add tables to your word document using an Office Add-In. This will be a multi part blog post as there are a lot of nuances and interesting ways in which you can play with tables in Word.

Introduction

In previous articles I have written about how to interact with a Word document to search and replace and even save the word document to Salesforce. Going back to a more basic level we are going to look at how to build tables in word.

We will be using the new Script Lab  which is a new Playground Add-In which can be used for development and general tinkering with Add-Ins. This and other articles on the topic are for demonstration purposes and are not hardened for production use.

The reference

For more information on Tables and how what methods/properties are available check out the documentation page – Table Object (JavaScript API for Word)

Creating a table 

At the most basic level a table is created by instantiating the table object and adding values to it.

insertTable(rowCount: number, columnCount: number, insertLocation: string, values: string[][])

This can be done from a number of different parents:

  • The body
  • A range
  • A contentControl
  • A paragraph

The method requires the following:

  • rowCount – a number
  • columnCount – a number
  • insertLocation – Depends on parent – either (body: Start/End/Replace) or (range: Before/After)
  • values: 2 dimentional Array – [[“This is”, “a table”], [“this is”, “a new row”]]

Using these parameters we can create a table from within the Script lab using the following code:

$("#run").click(run);

async function run() {
    try {
        await Word.run(async (context) => {

            var body = context.document.body;
            var range = context.document.getSelection();
            var myArray = [["a", "b"], ["c", "d"]];
            var table = range.insertTable(2, 2, "Before", myArray);            

            // Synchronize the document state by executing the queued commands,
            // and return a promise to indicate task completion.
                await context.sync().then(function () {
                    console.log('Table added before the start of the range.');
                });;
        });
    }
    catch (error) {
        OfficeHelpers.UI.notify(error);
        OfficeHelpers.Utilities.log(error);
    }
}

 

 

Conclusion

Using the Script Lab we have seen how we can easily insert a table into a Word document using the Office Add-In API. In future articles we will look at looking for the table we want to modify and then manipulating tables.

 

 

Advertisements

Office Add-Ins – JavaScript control over the Content Control lock in a Word document

In this article I will show how easy it is to programmatically lock and release the lock on a content control in a word document. This is very helpful when you are populating regions of a document but do not want users to mess with the format of the contents.

Introduction

In the Word 1.3 release of the office.js model, Microsoft release the new “cannotEdit” property of a content control. This is a get and settable property. More information on the properties available are found here in the documentation

https://github.com/OfficeDev/office-js-docs/blob/WordJs_1.3_Openspec/reference/word/contentcontrol.md

Unlocking a content control for editing

Here is my locked content control called “Checklist”. I am going to use the code to get it by Tagname and then unlock it.

In your JavaScript code when you are about to update the control you need to execute the following as a minimum. It seems like a lot of code but it is due to the Promised based architecture used for the Office Add-In APIs.

    Word.run(function (context) {

        var contentControlsWithTag = context.document.contentControls.getByTag('Checklist');
        // Queue a command to load the tag property for all of content controls.
        context.load(contentControlsWithTag, 'tag');

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            if (contentControlsWithTag.items.length === 0) {
                console.log('No content control found.');
            }
            else {
                return context.sync()
                    .then(function () {
                        //the contentControlsWithTag is always returned as an array of items
                        contentControlsWithTag.items[0].cannotEdit = false;
                        contentControlsWithTag.items[0].insertHtml("<b>Hello World</b>", 'Replace');
                    });
            }
        });
    })
    .catch(function (error) {
        console.log('Error: ' + JSON.stringify(error));
        if (error instanceof OfficeExtension.Error) {
            console.log('Debug info: ' + JSON.stringify(error.debugInfo));
        }
    });    

Once you have unlocked the control your code can be inserted and the control is editable. In a real application you just have to make sure you lock averything again with

   contentControlsWithTag.items[0].cannotEdit = false;
   contentControlsWithTag.items[0].insertHtml("<b>Hello World</b>", 'Replace');
   contentControlsWithTag.items[0].cannotEdit = true

Conclusion

Nice, simple to use locking control. Yes the users cant unlock this manually and mess with the document, but if they are going there, then it is their own fault. This way no changes can be made “by mistake”.

 

Azure Machine Learning Studio Office Add-In

I am currently in the process of learning more about Azure Machine Learning Studio . Within there you can create and train predictive models. As I am going through some of the examples I came across a great example of an Office Add-In.

I am creating a simple weather predicting example based on data I downloaded from an API service. More on that later. From my model I created a sample Web Service with the click of a button. This exposes an End point for me to send data to be “predicted on”.

a2

When you create a Web Service from your trained model you can access a test screen through the application.

a1

 

From there I spotted a link to an Excel App and I figure I would see what was going on there. Turns out it is an Office Add-In… !!

When the Excel sheet opened I was presented with the option to test the web service

a3

Once you load your test data into the sheet you can then use the Add-In to select the data to test – and designate where the answer will be added back to the sheet.

a4

And you push Predict !!!

Looking at the application using the F12 tool we can see the hosted Office Add-In location and also see the prediction in action.

a7

a5

The web service is called and the response is a JSON string with all the answers and the scored confidence in the answer.

The Add-In then inserts those answers back into the Excel spreadsheet for you

a6

As you can see, my predicting needs some work but the Add-In and sample web service worked like a charm !!!

Poking around the site I can see it is built using Knockout.js and some jQuery – very cool 🙂

a8

Once I have properly figured out how this all Machine Learning lark works I am going to create some blog posts on the predictive side of this – but I wanted to share how cool this out of the box for free Add-In is

GREAT USE CASE !!

 

19 Jan – Speaking at Northwest Chicago JavaScript meetup – Office.js

We have been hosting the NWCJS meetup here at PSC Group for the past few months. We have had some great speakers talking about React Native, How Chrome works under the covers, ES6, Web Components and others. This time it is my turn to speak.

I am going to be talking about Office.js the framework library which is the underpinning of Office Add-Ins. I will be talking about how the framework works, how it’s intended to be used and present lots of examples of how you can use JavaScript alone to automate functionality within the Office suite of products (Word, Excel, Outlook etc). The Office.js library is intended to replace the main functionality of VBA but in a way that works not only on Windows machines, but also on the web and on Mac clients.

For more information on time and place check it out 🙂

Office.js

Thursday, Jan 19, 2017, 6:00 PM

PSC Group, LLC
1051 Perimeter Drive Suite 500 Schaumburg, IL

21 Javascripters Attending

Office.js – Using JavaScript to build functionality into Microsoft Office by Marky RodenMarky Roden is Principal Architect for the PSC Group LLC and Head of the PSC Labs emerging technologies group, tasked with using cutting edge technologies to transform solutions offerings for customers.**************Schedule 6:00 – begin arriving and sociali…

Check out this Meetup →

Building Office Add-ins using Office.js – the book, the website

I wanted to show some love for the new website and book by Michael Zlatkovsky. Michael is a Software Developer and Program Manager in the Microsoft Office Extensibility team. I met Michael at the MS MVP Summit back in October and we had a great conversation or two about Office Addins and their future development.

So Michael’s new leanpub book is called Building Office Add-Ins using Office.js and can be purchased through leanpub. The new supporting website http://buildingofficeaddins.com/ provides some of the key information from the book and gives a nice overview thereof while introducing the reader to the more technical aspects of using Office.js.

Michael’s a great guy and this is a very valuable resource for Office Add-In developers. I heartily recommend it.

Sharing data between Office Add-Ins using localStorage

In this article I will show how the underlying dependence on the browser (in this case IE11 in Windows) allows us to pass data between Office Add-Ins through the use of HTML5 localStorage. At this point this is a theoretical post as I haven’t thought of a good use case yet, I am sure I will at some point…

Introduction 

Earlier this year I created a demo for the Salesforce global conference (Dreamforce) which showed how to create an Office Add-In to extract and manipulate Salesforce data from within an Office Add-In (you can see the presentation here). For the main demo I actually created one “Web Page” and reused it in the context of Word and Excel. In this article I will demonstrate how we can easily set a localStorage value in IE11 or in an Office Add-In and have that readable in the other client environments.

localStorage

localStorage is part of the HTML5 Web Storage API which allows the permanent storage of string values in a browser. Like cookies the ability to read and write is tied to a domain. You can get/set values very easily by using the following notation:

  localStorage.setItem('name', 'Marky');
  localStorage.getItem('name'); //Marky

or even as simple as

  localStorage.name = 'Marky';
  localStorage.name; //Marky

The Embedded Browser 

When utilizing an Office Add-In within the Office client apps we are really using an embedded browser session within the context of the external client. In the case of Windows it is Internet Explorer. What this means though is that when we access a web domain, and set a localStorage value, that value is always available to us, when using Internet Explorer on that domain. Let me show you.

The Example

Here is my application running hosted on Azure in the xomino365.azurewebsites.net domain

ls1

Through the console I created a new value

  localStorage.Marky = "This value set in IE11";

and as you can see below that is now accessible from localStorage

ls2

If I now load up my Office Add-In within Word we can see (using the F12 tool) that  it is the same URL (same web page). Because it is in the Add-In “host_Info=Word” is added to the URL but other than that it is the basically same.

ls3

Looking at the localStorage value we can also see “marky”

ls4

We can set a value here in Word

ls5

and then open the Add-In in Excel and retrieve the localStorage values previously set

ls6

Caveat

If you have Word and Excel open you cannot set a localStorage value in one and have it picked up in the other, it seems that they only pick up the new values once they are opened. If you wanted to pass information between them in real time you could do that using WebSockets (something for a future demo).

Persistence between different Add-Ins

Now that I have set these values using the same application, we can also demonstrate that the principle is still applicable between different Add-Ins hosted in the same domain. In this example I have a different Add-In, still hosted on xomino365.azurewebsites.net (this time in Outlook). All the localStorage values are still available to me.

ls7

Conclusion

In this article we have seen how we are able to set a localStorage value in Internet Explorer and then Word and have those values available in Excel. We have also seen that these values are actually available in other Add-Ins as long as they are hosted on the same domain.

This capability is all due to the underlying fact that Internet Explorer is the browser used to create all the demonstrated functionality.

 

Using “F12” in Windows to get an Office Add-In development developer console

In this article I will demonstrate the ability to activate and use the Internet Explorer developer console from within an Office Add-In.

Introduction

As I have discussed before, without using the debugging tools available within Visual Studio it is hard to debug Office Add-In development. In the past I have used firebug lite to assist in this but it is far from ideal. Within Windows 10 there is a new capability to open a developer console which help alleviate this issue to an extent.

F12

On a Windows 10 operating system you will find F12 in the %system32% directory. Normally this would be c:\windows\system32\F12\F12chooser.exe

f1

 

Open up you favorite Office Add-In and or one you are working on and then open F12Chooser


f2

f3

 

Selecting TaskPane.html in this case will open the Internet Explorer developer tools for that web page. In Windows the Office Add-In is surfaced through an embedded IE windows within the office client.

f4

Using the developer console you can execute commands as normal

f5

You can also use the selector tool to look at styles

f6

 

Thanks to Michael Zlatkovsky (Microsoft Office Add-In dev – this guy) for showing me this 🙂

Conclusion

This is a major improvement for me over having to use firebuglite – interestingly though Michael was very intrigued that I had got that to work as well 🙂