Office Development – Word Add-in, minimal code

So far it has been fairly complex, installing lots of components and doing all sorts of things before you get things to work. But what do you need for code to do just the minimal thing in a Word Add-in?

Initially it is said that a context is required by requesting a new context:

var ctx = new Word.RequestContext();

With this context you can do things the things you’d like to do.

function MinimalWordmethod() {
  
// Create the client request context. You’ll do this for al Word add-ins.

   var ctx = new Word.RequestContext();

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

   ctx.executeAsync()
     
.then(function () {})
     
.catch(function(error){
        
console.log("ERROR: " + JSON.stringify(error));
     
});
}

Interesting part is that this RequestContext is not to be found in the Yeoman boilerplate, so it looks like it is initialized by the framework these days …

I want to find out where this happened in the Yeoman boilerplate. As far as I can tell the documentation is not all too clear about this.

To be continued too Winking smile

Office Development – Installing Script Lab

Yesterday in my blog a short introduction to Script Lab, the Microsoft Garage project to work in some sort of a playground to develop your JavaScript for Office scripts so you can test-drive your code that you plan to use in your Add-in.

Today I will go over the installation process of Script Lab. Step by step I’ll follow the instructions and see what this looks like. How hard can it be ‘ey?

To start installing navigate to https://aka.ms/getscriptlab. It looks like this:

clip_image002

Click the Add button to arrive at the guided installation page:

clip_image004

To stay in the mood, we select Word again. I’ll will be using other clients like Excel or PowerPoint soon, but to be consistent I’ll select Word again. This will provide you with a comparable environment and maybe you get used to it. Now, to open in Word click the “Open in Word” option. This will ‘warn’ you that you are about to switch applications:

clip_image006

As this is the plan, you want to move into Word instead of staying in Microsoft Edge. Select ‘Yes’ to go on. This will launch Microsoft Word 2016 (assuming you have Office 2016 installed):

clip_image008

A document is opened, but not without warning. Because you open the document from the dark and dangerous Internet you are provided with a warning and start in the Protected View of Office:

clip_image010

In this case we tend to trust Microsoft in this we continue our journey by pressing “Enable Editing” but now we run into a second warning because the document also contained a Task pane that wants to run the Script Lab Add-in.

clip_image012

Again to make you feel safe, you don’t want any add-in to kick in without your confirmation, you get the option to “Trust this add-in” or “See Details”.

clip_image014

If you click “See Details” they bring you back to base. The installer page is provided where you can read information about the add-in. I guess you already did that, otherwise you wouldn’t get this far in the installation process (unless you just trusted my simple introduction and went ahead ). For now, not all that interesting, so we close this and leave it for what it is.

clip_image016

We go ahead, and decide to trust this add-in. This will bring us the Script Lab tab:

clip_image018

Showing you a balloon with the text “Code, Run and share your Add-in snippets directly from Office” and a “Got It” button to confirm:

clip_image020

Click the Script Lab and you’ll see a ribbon appear with the options:

Code, Run, Tutorial, Help, Reference Docs and Ask the Community

clip_image022

The most obvious thing to do would probably be to go through the Tutorial, at least that was what I picked as a starting point. The interesting thing is however that the Tutorial brings you to an Excel environment to explain you what you can do with the Add-in:

clip_image024

You basically go through all the same steps again, but ending up in Excel showing you all the same options. Open a script-lab-tutorial.xlsx from script-lab.azureedge.net :

clip_image026

This is an Excel starter document with more information about the Add-in and guiding you through the options:

clip_image028

Again the little Protected View warning and the Enable Editing button.

clip_image030

It didn’t provide me with the Script Lab Add-in tab though, only the instructions that you also saw when running the Word installer, except now for Excel.

clip_image032

This wasn’t really what I was looking for, probably useful if I just started from Excel but I didn’t. I went through the GitHub issues and noticed that getting a Word Tutorial is still in planning. Some patience here.

For now, at least the Word Script Lab Add-in is installed and ready to use.

To be continued

Office Development – Fixing Trusted Authority – Word Client

Office Development - Running Add-in Word Client

Yesterday we’ve seen an issue installing a Word Add-in when the certificate used in the Add-in is not (yet) trusted:

clip_image002

To solve this, we need to add the server certificate as a trusted authority to the certificate store. In my post Office Development – Fixing Certificate Issue with OpenSSL Certificate I already showed you how to create the certificate. I even announced that I had to add the certificate to the trusted root certificates but, in the end, never did that – resulting in the issue above.

Clean up the installed Add-in

First, let’s clean up the installed Add-in to re-do the installation later on to see if it installs correctly after adding the certificate to the trusted root certificates.

Go back to the File/Options/Trust Center/Trust Center Settings … button and click it

clip_image004

Select the Trusted Catalog Address, click Remove and click OK to close the dialog. You’ll get a message that it will be effective when you close and open Word again.

Close Word to get it done.

Now start the certificate manager:
C:\Windows\System32\certmgr.msc

clip_image006

Select the Trusted Root Certification Authorities node, right click, All Tasks, Import …

clip_image008

clip_image010

Click Next to continue

clip_image012

Select the server certificate from the Add-in folder that you created while generating the certificate. Click Open and add the certificate.

clip_image014

Click Next

clip_image016

And … Finish to complete the certificate installation.

Install the Word Add-in again

Repeating the steps from the previous post, go to File/Options/Trust Center/Trust Center Settings … button and click it.

clip_image018

Add the network share again, don’t forget to check the checkbox. Close the dialogs and if you get this message below, close Word and start it again.

clip_image020

Now go to the Insert Tab and click My Add-ins.

clip_image022

Repeating the sequence that we did in our previous post, go to the Insert tab and click My Add-ins.

clip_image024

From the SHARED FOLDER tab select your Add-in again and click Add. Immediately you see the button at the Home Tab in the Commands Group.

clip_image026

And if you now click the button, the Add-in is now loaded without issues. No more warnings for security issues or incorrectly named certificates. It just runs.

clip_image028

So, what have we learned today

– Make sure your security is in place. Prepare your certificates with the correct names on the certificate and add it to the trusted root certificates.

(Note: most of these issues are originated by creating self signed certificates. When using commercially generated certificates most of these certificates already come from trusted root certificates)

– Cleaning (removing) installed Add-ins is not so trivial as you might expect. We had to remove the Catalog entry, closing Office and reopen Office clears the Add-in. It would be easier if the user interface provided an option to remove the Add-in in an easier manner.

(Note: removing the Add-in from Word Online is even worse. I asked the question on StackOverflow where it was confirmed that there is no easy remove option)

Recap

So far, we installed NodeJS, Git, Yeoman and created a simple Add-in. Next, we tried to install it on Word Online, fixed some security issues, installed it on the Word local client, fixed some more security issues and finally installed it on the local Word client again, this time without issues.

Not much interaction yet between the Add-in and Word but we’ll look at that later.

To be continued …

Office Development–Running Word Add-in on your local Word client

clip_image002

In my last post Office Development – Running Word Online Add-in I explained how to install your Add-in to use in Word Online. Today we will bring the same Add-in into your local Word client installation, Word 2016:

clip_image004

To do so you first need to start your ‘web server’ again by calling

npm start

from the root of your Add-in folder.

Now you have your ‘web server’ up and running and we need to make this visible for Word. Word is able to ‘see’ Add-ins that are exposed by manifest files in a shared network location or web URL. Today we will use the shared network location to expose the manifest file.

To create a shared network location, you simply create a dedicated folder on your machine:

clip_image006

In this case I just created an extra folder in the Add-in project called addinshare.

Don’t forget to copy the manifest file “my-first-addin-manifest.xml” to the just created folder!

Now create the network share by opening the Explorer. Go to “This PC” and select from the menu/ribbon “Manage”

clip_image008

This will open the Computer Management tool. Browse in the left tree to Computer Management\System Tools\Shared Folders\Shares, select it:

clip_image010

Select Action, New Share:

clip_image012

Go to the folder that you dedicated for your Add-in

clip_image014

clip_image016

Click Next to continue

clip_image018

If you like change the name of the share, and click Next

clip_image020

For now, add All Users have read-only access (you might want to change the access rights later on but for demo purposes pick the default) and click Finish.

clip_image022

Click Finish again to close the dialog and close the Management Tool.

Now back to Word, goto the Trust Center under File, Options, Tab Trust Center, Button “Trust Center Settings …”

clip_image024

On the left side select “Trusted Add-in Catalog” and in the Catalog URL enter the network share from your computer \\<computername>\<sharename> that you just created in the previous steps. Click Add catalog to push it in the list.

When added to the list, check the checkbox Show in Menu to make it available in Word.

Note: Before clicking “Add catalog” it would be a good thing to check in Explorer that your folder spelling of the shared folder is correct and is opened without issues.

clip_image026

Click OK twice to close the dialogs. You may see this as well:

clip_image028

If all went right you should be able to add your Add-in to Word. Close all instances of Word and restart Word.

Go to the Insert Tab, just like you did in Word Online from the previous post and click My Add-ins:

clip_image030

Clicking the My Add-ins button in the ribbon will give you the dialog below if you select the option SHARED FOLDER (notice that Word recognized the share and provided you with this menu option. If the share wasn’t recognized the option for SHARED FOLDER would not appear).

clip_image032

What is up? Didn’t we fix the certificate issue? We had it running in the browser, didn’t we?

Well, yes … but what I forgot was to add the certificate to the list of trusted authorities. For now we can go on, we know it is safe but we need to fix this later on (food for another blogpost ).

Click Yes to confirm, select the MyFirstAddin an click Add.

clip_image034

After closing the dialog by clicking Add a new Ribbon item is added to your Word Home Tab:

clip_image036

Kinda useless information, you are already on the HOME tab … nevertheless, click the “Show Taskpane” button to get started. For me this resulted in:

clip_image038

Sh*t happens so I refreshed the page, to see what happened:

clip_image040

A bit better, but still not right. This time we recognized the “not secure” warning. My own fault, it still needs the trusted authority fix. For now, click More information:

clip_image042

This opens up the option to Go on to the webpage (not recommended). We know it is ok in this case, if the source was unknown you should just back out and close the add-in. In this case we created it, know it is secure so we go on to the website, although it was not recommended. We like to be a little bit stubborn at times and there you have it, it worked:

clip_image044

Quite a journey again, still not flawless but cause by my own doing. We now have the Add-in running in both Word Online and in Word 2016 on your local machine.

In our next step, I’ll add the certificate to the trusted authorities to redo this without issues, hopefully…

To be continued

Office Development – Running Word Online Add-in

Office Development - Running Add-in

What we’ve seen so far is that we installed NodeJS, Git, Yeoman and fixed a security issue. All if this to create a basic ‘hello world’ Add-in. I must be honest and admit that running your first VBA add-in was a lot easier and running out of the box with just a few lines of code.

But let’s go on. We did run the Add-in as a website, but not as a real Add-in in the Word client. The instructions explain that the easiest thing to do would be to use Word Online. So here we go:

Open Word Online, go to the Insert Tab

clip_image002

Click the Office Add-ins button

clip_image004

On the top right select “Manage My Add-ins” to upload the Add-in manifest

clip_image006

Click Browse to find the Add-in manifest file

clip_image008

After uploading the manifest, you should see the Show Taskpane button appear in the Commands Group and if you click the button the Task pane appears showing you exactly what you’ve seen in our earlier blogpost:

clip_image010

And there you have it … your first Add-in running in the Word client. Congratulations.

I do have to admit that it didn’t work immediately … I had to upload the manifest more than once to get it to work. At first my icon didn’t appear, the group did but the Task pane didn’t load either after clicking the ‘no icon’-button. Trying again solved it (no clue to why the first attempt failed).

Obviously, the scenario we’ve seen so far won’t work ‘in production’. The Add-in website is currently still running on your local machine at a specific port (3000 in this case) and adding the Add-in using Word Online is not directly the most optimal way to get your Add-in up and running.

Our journey of research is apparently not ready yet. We need to overcome the ‘demo’ instructions and see if we can get it closer to a production ready system. I think my next step would be to find out how to run the Add-in in the Word client running on the desktop. Maybe the next step after that to run it on a Mac.

This all is still just running the Add-in, we haven’t seen any interaction with the documents. No fear, we will get there … I’m sure so keep with me and hang in here.

To be continued …

Office Development – Installing Git

Office Development - Git

In our previous step to build our first Word Add-in with JavaScript for Office we installed Nodejs. Today we continue with installing Git. Over time there will not be a need to install these tools again, by then you will be a professional web developer living in the world of these tools and probably have these installed already before jumping into another project.

For now I assume you didn’t have the tools installed, but you can check on the command line with the command:

git –version

If you already installed Git you probably see something like this:

clip_image002

You can find the Git installer just by GoogleBinging for “Git” and this will lead you to:

https://git-scm.com

Now, on the right you see a nice downloader button that selects your installer based on the machine that you are on. Click this, and hit Run (usually you wouldn’t be so dumb and save the downloader first on your machine in order to have the anti-virus checker check your download but for now we just let it run #yolo … )

clip_image004

As usual the first dialog you’ll see are the GNU License terms, your only option is to agree by clicking next or abandon the installer and start reading a good book and continue living your life without the software. Today we’ll decide to go on however …

clip_image006

Now select a few components. You can add some icons to the desktop and I opt for the settings to add Windows Explorer Integration and the other defaults.

clip_image008

I also have it install the icons on the desktop for quick access, you can always throw ‘em in the bin if you think they are in your way.

clip_image010

The next dialog above is for adjusting the PATH environment. My option is to “Use Git from the Windows Command Prompt”. Note that with this option you’ll be able to use both Git Bash

Bash what? …

Ok, ok, I know, if you are native from Windows you probably won’t even know what Bash is. For now, you don’t need to know other than that this is some sort of a Linux command line option.

Don’t worry, you get the hang of it once you are moved over to the ‘other side’.

clip_image012

Choosing the HTTPS transport backend I opted to “Use the native Windows Secure Channel library” (just because we are still in the mood of Windows, you can change this later if you like).

clip_image014

Configuring the line ends I leave the default as it was the recommended setting on Windows “Checkout Windows-style, commit Unix-style line endings”

You already noticed it, there is a lot of Unix influencing here … Bash, LineFeeds … it takes me back to the time I studied Computer Science. #throwbackwednesday

The next dialog is no different. Configure the terminal emulator to use with Git Bash

clip_image016

The option selected allows you to use both MinTTY as terminal emulator as the common Windows Console (“cmd.exe”).

clip_image018

Again, select the defaults to enable file system caching and enabling the Git Credential manager. Hitting Install will kick off the Git Installer to install all the selected options you entered on the dialogs above:

clip_image020

clip_image022

Done, if you want to have a quick view at what Bash is tick the option to Launch Git Bash. Otherwise it will just lead you to the Release Notes (if you didn’t remove the check before “View Release Notes” that is). You now have Git on your machine, check the version again by running git –version again.

You should see this (or a newer version if you read this later than the day of the blogpost):

clip_image002[1]

Ready to go into the next step to install Yeoman.

Yeoman whaaaaaaaaaaaaaat?

Yes, Yeoman … more in my next blog post.

Hang in there and see you tomorrow! You get used to it … let it all get into your system, GoogleBing it a bit for some extra context, perform all the steps from above doing it yourself and be ready for the next step.

Office Development – Word

clip_image002

In my previous post I mentioned the confusion for the JavaScript APIs for Office in general. Today we’ll go deeper in and focus on the API support for the various Word clients. Let’s see what APIs are available for each of the Word clients in detail and finish off with the observations once we identified what is in each client for Word:

Word Online

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CustomXmlParts
DocumentEvents
ImageCoercion
MatrixBindings
MatrixCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word 2013 for Windows

Extension Points

Taskpane

APIs

Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
MatrixBinding
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word 2016 for Windows

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
Matrix Bindings
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Note that there is a difference between the MSI installed version or the Office365 version. The MSI version only contains WordApi 1.1. according to the specifications.

Word for iPad

Extension Points

Taskpane

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
Matrix Bindings
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word 2016 for Mac

Extension Points

Taskpane
Add-in Commands

APIs

Word API 1.1
Word API 1.2
Word API 1.3
Dialog API 1.1

Shared APIs

BindingEvents
CompressedFile
CustomXmlParts
DocumentEvents
File
HtmlCoercion
ImageCoercion
Matrix Bindings
MatrixCoercion
OoxmlCoercion
Settings
TableBindings
TableCoercion
Text File
TextBindings
TextCoercion

Word for iPhone

Word for Android

Word Mobile for Windows 10

clip_image004

Observations

So, what do we see here? First observation is that cross platform now means that besides the good old Windows system, additional clients are limited to: “Office Online”, “Office for iPad” and “Office 2016 for Mac”. None of the phone clients have support for add-ins.

A second observation is that all other clients are more or less in par with each other. Only “Office 2013 for Windows” is limited to the DialogApi 1.1 and also none of the WordApis. It also does not support Add-in Commands. This makes you think if you should build your add-ins for Office 2013 or not at all. My guess is that the limitations on this platform are so significant that it would be better to only focus on Office 2016 and up.

Third observation is the missing support for Add-in Commands on Office for iPad. I’m curious to know why this is the case. I thought the iPad also had something like the right click (press and hold for menu) but maybe not. I don’t own an iPad -darn, do I really need to buy one now- so I can’t check this at this time.

Fourth observation is the missing Shared APIs on “Office Online”:

CompressedFile
File
HtmlCoercion
OoxmlCoercion

Maybe these four APIs are just not logical to have in an “Office Online” environment, but that too is a wild guess as I don’t know yet what it is used for.

I’m not sure yet where to go next. We now know what APIs are available for each of the Word Office clients, so I think the next step would be building a starter Add-in for Word 2016 for Windows. This client has the biggest set of APIs supported making me think that this is the best candidate to experiment on and later on see how this fans out to the other clients such as Word Online or the Apple options.

To be continued …

%d bloggers like this: