Slides from MS Ignite Office Education day – Office Add-Ins Script Lab

Last month I was invited by the Office development team to present during the Office Education day at MS Ignite.

This presentation was given as part of the Office education day September 24th 2017. The presentation focused on Office Add-Ins and specifically how users could use the Script Lab Add-In to be able to get started with Office Add-Ins.

There are examples in the presentation of some of the Add-In samples available in the Script Labs and then a challenge

 

 

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 !!

 

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 🙂

 

Speaking at Dreamforce next week :)

Next week I will be in San Fransisco for the Dreamforce conference – this will be the biggest conference I have attended, never mind spoken at and I am really excited to go 🙂

If anyone is going to be around at the conference or in the area – ping me on Twitter @MarkyRoden – be good to meet up 🙂

 

Unleashing the power with Salesforce and Microsoft Office 365 Add-ins

https://success.salesforce.com/MyAgenda?eventId=a1Q3000000qQOd9EAG#/session/a2q3A000000LBjBQAW

TIME & LOCATION

Moscone West, Developer Lightning Theater

Using an Office Add-In to search and replace data in a Word Document

In this article I will demonstrate how we can use an Office Add-In to perform simple search and replace function within a Word document. This is particularly useful when you want to use an external cloud source to insert data into your documents.

Introduction 

This example comes directly from the Microsoft GitHub example on Word Add-In Document Assembly. (https://github.com/OfficeDev/Word-Add-in-DocumentAssembly). The reason I am blogging about it is that it did not appear in any searches for me and I stumbled across it purely by accident.

Filling a document template

Setup

I grabbed a sample word document template from Word Online (https://templates.office.com/en-sg/Formal%20business%20letter-TM00002133) and we are going to replace the items in this document programmatically.

r1

I created a blank Word Add-In locally and then inserted my local FirebugLite capability just to create a quick and easy demo without having to go through the trouble of hosting the code anywhere.

r2

Basic search and replace

The basic code for search and replace is as follows:

function handleSuccess() {
	app.showNotification("Replacement successful", "Success");
}

function handleError(result) {
	app.showNotification("Error", "ErrorCode = " + result.code + ", ErrorMessage = " + result.message);
}
	
Word.run(function (ctx) {

	// Queue a command to search the document for the string "Contoso".
	// Create a proxy search results collection object.
	var results = ctx.document.body.search("[Recipient Name]");      //Search for the text to replace

	// Queue a command to load all of the properties on the search results collection object.
	ctx.load(results);

	// Synchronize the document state by executing the queued commands,
	// and returning a promise to indicate task completion.
	return ctx.sync().then(function () {

	  // Once we have the results, we iterate through each result and set some properties on
	  // each search result proxy object. Then we queue a command to wrap each search result
	  // with a content control and set the tag and title property on the content control.
	  for (var i = 0; i < results.items.length; i++) {
		results.items[i].insertHtml("Marky The Receiver", "replace");     //Replace the text HERE
	  }
	})
	// Synchronize the document state by executing the queued commands.
	.then(ctx.sync)
	.then(function () {
	  handleSuccess();
	})
	.catch(function (error) {
	  handleError(error);
	})
});

Running this example we can see the replacement was successful in both places

r3

r4
So to complete this as an example for the whole document I use a sample data object as it would be returned from a cloud REST provider and cycle through all the elements to be replaced.

function handleSuccess() {
	app.showNotification("Replacement successful", "Success");
}

function handleError(result) {
	app.showNotification("Error", "ErrorCode = " + result.code + ", ErrorMessage = " + result.message);
}

var data = {

	date: "22 Aug 2016",
	sender: "Someone really important",
	company1: "The Boss | Company 1 | Somewhere | Here | There | 12345",
	company2: "The Bigger Boss | Company 2 | Somewhere else | Near | Canada | 98765"
}
	
Word.run(function (ctx) {

	var results = ctx.document.body.search("[Recipient Name]");      //Search for the text to replace
	ctx.load(results);

	return ctx.sync().then(function () {
	  for (var i = 0; i < results.items.length; i++) {
		results.items[i].insertHtml("Marky The Receiver", "replace");     //Replace the text HERE
	  }
	})
	.then(ctx.sync)
	.then(function () {
		var results = ctx.document.body.search("[Date]");      //Search for the text to replace
		ctx.load(results);

		return ctx.sync().then(function () {
		  for (var i = 0; i < results.items.length; i++) {
			results.items[i].insertHtml(data.date, "replace");     //Replace the text HERE
		  }
		})
		.then(ctx.sync)
		.then(function () {
			var results = ctx.document.body.search("[Title | Company | Address | City | State | Zip]");      //Search for the text to replace
			ctx.load(results);

			return ctx.sync().then(function () {
			  
				results.items[0].insertHtml(data.company1, "replace");     //Replace the text HERE
				results.items[1].insertHtml(data.company2, "replace");     //Replace the text HERE
			  
			})
			.then(ctx.sync)
			.then(function () {
				var results = ctx.document.body.search("[Sender Name]");      //Search for the text to replace
				ctx.load(results);

				return ctx.sync().then(function () {
				  for (var i = 0; i < results.items.length; i++) {
					results.items[i].insertHtml(data.sender, "replace");     //Replace the text HERE
				  }
				})
				.then(ctx.sync)
				.then(function () {
				  handleSuccess();
				})
			})
		})
	})
	.catch(function (error) {
	  handleError(error);
	})
});

And here’s the final output

r5

r6

Conclusion

Using the Word JavaScript API through an Office Add-In we are able to use a search and replace technique to take external data and complete a template. This is especially powerful when you consider it in the context of a cloud service integration like O365, or CRM clouds like MS Dynamics or Salesforce.