In writing my new Outlook Add-in (Send to Trello), I got stuck on attachments. The first version did not include an attachments option because of two unique problems that compounded each other:
The Office Add-in API no longer provides a Media Type/MIME Type with an attachment request. I am able to get the “blob()” from Office, but other than the file extension there is not a way to determine the type. But sometimes a file does not have an extension, or the extension is wrong, etc.
The Trello API will not let you upload without supplying a MIME type, you cannot just give it a Base64 string as an attachment and let them figure it out.
So, I found out something interesting while researching a workaround. Most every base64 string of a specific file type starts with the same “prolog” of text. Using this, combined with the fallback of the file extensions, I was able to get attachments to work (for the attachment types supported by Trello). So, v1.02 will now include attachments.
Anway, as for the workaround I found, this might be ugly, but wanted to share it anyway:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I have been using Trello for a while now and one of the features I have found most useful is to take an email I received and turn it into a Kanban item on my backlog to address later. This allows me to archive the email but keeps it on my “Trello radar” as I work at my own pace through my personal backlog.
Recently, Trello removed their add-in from the Microsoft Office store. If you have the add-in installed, you will see this error:
Well, since they say necessity is the mother of all invention and I really had to fill the gap as it is part of my routine, I rolled my own. 🤓 To add a degree of difficulty, I wrote this in VS Code in Linux running in Windows Subsystem for Linux (WSL). See my previous post. It was a fun exercise as I am on vacation and using the time tom learn new things, engage in self-improvement and relax (coding is relaxing to me 🤓🤓🤓). In the end, I learned something and created something for everyone to enjoy.
Another recent announcement that has me excited is the ability to debug Office Web Add-ins directly from VS Code. Before this recent announcement, it was a hit or miss proposition. There was Visual Studio 2019, that did a pretty good job. But I liked the lightweight simplicity of VS Code. Visual Studio 2019 seemed too too heavy-weight. It’s hard to put my finger on how or why, but I really enjoy VS Code for Web Add-in development so much better. Except for debugging…
So, to debug, I actually did most of my dev/test in the web versions of Office (Excel online, Outlook online, etc.). Then came the Edge Developer Tools Preview which helped debug task pane add-ins in the full clients. But that did not help with things like the On Send event in Outlook or other UI-less functions. So, it was a struggle at times.
The process is a tad more complicated than I like, but it does work. Essentially, you need to:
Run VS Code as administrator
Install the extension in VS Code by pressing CTRL + SHIFT + X and searching for the “Microsoft Office Add-in Debugger”
Add the following code to the .vscode\launch.json file to enable Office Debugging in your project. You will need to update line #7, and replace the uppercase HOST text with the host application for your Office add-in.
NOTE: If you create a new Office project with Yeoman, you will not need to add this line, it will be part of the default template going forward.
Press CTRL+SHIFT+D to then open the Debug pane, select Attach to Office Add-in option from the drop down list at the top of the pane, and press F5 to start debugging.
You can now set breakpoints, see variable values, etc.
I have made a few minor updates to easyEws. First, was a fix for distribution lists with an “&” in the name. The second is a few minor JSDoc updates for better linting. And finally, I changed a couple forEach loops to traditional for loops for performance reasons.
I have published the update to NPM and to my GitHub.
Please let me know if you have any issues or questions.
Like yesterday with easyEws, it has been a while since I have touched the OfficeJS.Dialogs library. I updated it yesterday with a quick fix and some content updates. I have had questions about using it from a CDN. The primary issue is that the displayDialogAsync() API does not support CDN. It just displays the HTML as raw text in the dialog. There are some ways I can provide this as a workaround, but it involves me support infrastructure. So, the better thing is to just wait for the API to support CDN’s.
I spent the better part of this morning trying to figure out why a new Yeoman generated Outlook add-in was not working with IntelliSense in VSCode. I would type “Office.” and nothing would appear. I would press CTRL+{SPACE} and still nothing.
After a lot of digging and comparing projects that did work to those that did not, I found that the @types were missing. So I then installed @types/office-js:
npm install @types/office-js
Once I did this, viola! IntelliSense started working like a charm. From my experience this has happened to me a few different times, in these given scenarios:
Moving an OfficeJS project from VS2017 to VSCode
Moving a Script Lab project to VSCode
Creating a blank OfficeJS project from scratch with just two files (manifest and webpage).
In my continued research I found that the way VSCode handles types is through NPM and you need to have data type definition files to get it all to work, that is why you need to install both NPM and the OfficeJS @types to get this to work. Per this page: https://code.visualstudio.com/Docs/languages/javascript
Automatic Type Acquisition (ATA) uses npm, the Node.js package manager, to install and manage Type Declaration (typings) files. To ensure that Automatic Type Acquisition works properly, first ensure that you have npm installed on your machine.
Secondly to that, for OfficeJS development, make sure you have @types/office-js.
At the MVP Summit 2018, I have had a number of conversations with various MVP’s that there really should be more documentation on how to get started with OfficeJS from scratch. Like web developer – from scratch.
So, this blog post is my attempt to get you started as if you have little to no web developer experience. The hope is that once you have read this and studied the linked content you will be able to:
Write HTML and JavaScript
Understand what JQuery is and how to use it
Setup your VSCode environment
Identify the key parts of an add-in (source code files)
Begin writing, and debugging your own code.
To get started, if you are completely new to web development (or even a little rusty and need a refresher), you might want to read the following articles/tutorials. If you already know this stuff, then you can move on:
NOTE: From these links you need to come away with an understanding of these basic fundamental concepts that are used heavily in OfficeJS:
How JavaScript and HTML work together
The HTML DOM model
How to write HTML and define controls (buttons, text boxes, etc.) with an id
How to use JQuery(*) to get a reference to a control on the HTML page and then manipulate it with JavaScript.
(*) JQuery is simply a library that, for simplicity sake, makes it easy for you to access and manipulate HTML controls via the DOM. You access it with a “$” character. This is why you might see so many “$”‘s in the sample/example code out there.
Once you know the basics of creating a web page, and manipulating it, you can then begin by setting up VSCode and learning how to code OfficeJS solutions. As for development environments, there are many out there, and many are nearly the same, but I suggest VSCode because it is simply a better environment to learn “webby” development. Especially if you are on a Mac. With that said, you will want to:
NOTE: A fundamental concept you need to come away with after working through the tutorials is to understand the “parts” of an add-in. I think the best way to understand the PARTS of an add-in:
All you really need for an OfficeJS solution are two files. A manifest and an HTML file.
To understand the anatomy of an add-in, you can read this post where I describe the most basic add-in you can create. Here is a simplified explanation to get your started:
The Manifest – an XML file that defines to Office your add-in. It defines things like the name, a unique id (GUID), the platform and app it supports, and most importantly your Ribbon (text, icons, etc), and what happens when you click those buttons. Specifically, it tell Office where to navigate when that button is clicked. Then this XML file is what gets “installed” in your Office app. Office reads it, places the button(s) on the Ribbon which loads the defined web page when clicked.
The HTML file – this contains “script” tags which point to all your code, supporting libraries (like JQuery) which similar to VBA/VSTO references. The HTML page also contains your Task Pane user interface (buttons, etc.).
The JavaScript file – This is your code, which will contain an Office.initialize() function that Office locates and executes when the HTML page is loaded. This can be a separate file or like the most basic add-in an inline script tag in your HTML file.
The entire load and run process for an add-in works like this:
The Manifest is loaded by Office and adds a button to the ribbon.
When the button is clicked, the HTML file specified in the manifest is loaded in the task pane.
When the HTML file is loaded, all the script tags (references and your own JS file) are loaded.
Once all the scripts are loaded, Office locates the Office.initialize() function and executes it.
It is in this code block that you can initialize your controls, like buttons on the HTML page, and what happens when the user clicks them.
I hope this is enough to get even the most novice non-web developer going. If you have any questions, please post them below. If there is any additional content you would like to see, please let me know.
The last thing I will leave you with is to answer an interesting question that arose this week:
Why would I learn to develop in OfficeJS? I am not interested in just making a web widget for Excel.
I think this is a common misconception. Office 365 Web Add-ins (OfficeJS) are at all not like Windows Vista Sidebar Gadgets for Office. They are actually quite powerful and there are many useful scenarios. Here are a few:
Integration with internal applications like CRM
Document tagging, or placing metadata on parts of the document, possibly linked with internal systems, controls or processes
Document building, either interactively through a task pane or dialog or from predefined rules
Advanced content editing, identifying and replacing specific content based on more complex rules than simple search/replace
Sending data from the document for more complex analysis and/or manipulation via back-end services and then updating the document with the results.
Once you delve a bit more into the object model and the capabilities, you will learn that you do not always have to open a task pane. You can open a dialog instead. Or, you can have no user interface at all, just have a button click on the ribbon perform work against the document like a macro used to do.
And here is another thought: Office is used by one-billion people world-wide across each of the supported platforms of Windows, Mac, web, iOS, and Android. The goal of these add-ins is to support the same code base (mostly) across all of these different platforms. You really can write-once/run-anywhere. You can build an add-in and then place it in the Microsoft Store and have it reach a huge audience. Do you need more of a reason to get started?
Recently, I have been working with a tool from Microsoft Garage which allows you to quickly develop OfficeJS projects in Word, Excel and PowerPoint. It is called Script Lab. You can find more information about it here:
To install Script Lab, open Word, Excel or PowerPoint and on the Insert tab, click Store.
Type “script lab in” the search box and hit enter. Then select Script Lab from the list and click Add.
Once added, you will see a new Script Lab tab. From there, you click the Code button to open the task pane.
This tool comes with a lot of options:
If you click the hamburger menu you will see an option to Sign Into GitHub. This will allow you to create Gist’s and access and save code snippets to GitHub.
You can import Samples from GitHub (with a URL) and access Snippets.
There are options to change the color in the editor at the bottom from Dark to Light.
And once in your solution, you can change the template (the html page), the CSS Style and any references libraries.
NOTE: You are dealing with a subset of the whole solution here. You cannot create Ribbon buttons or dialogs. You can only develop task pane add-ins. You can work with Script Labs in Word, Excel and PowerPoint, but not Outlook (yet).
Script Lab allows you to test things in a quick fashion. Here is what the code pane looks like:
NOTE: Script Lab defaults to TypeScript. It emits code in JavaScript on Export. There is no option to switch to only JavaScript. If you want to program in JavaScript that does not matter because JavaScript will work just fine as well. But in a shout out to Michael Zlatkovsky – who says Office of TypeScript are a match made in heaven – I look at this as an opportunity to get better at TypeScript.
One of the more difficult part of working in OfficeJS is to be able to quickly test how some feature of function or a block of code will work. In the VSTO and VBA days, I would pop open the Visual Basic Editor in Word, Excel or PowerPoint (ALT+F11), then open the Immediate Window (CTRL+G) and then start typing away to test specific object model items. There was nothing similar to this with OfficeJS, until now.
Script Lab is just that, a laboratory for you to test your ideas, your snippets, your work in progress. It is a way to test something before you put it into your full blown solution. You can then save code snippets as Gist (on GitHub) and export the solution.
And once you have written your code and are ready to test it, you very easily run it in the Taskpane or (my favorite) you can run side-by-side. From the Ribbon click the Run button and then you can still edit your code/html and then refresh and reload it in the side-by-side Run window. This makes developing a solution or just testing ideas VERY easy:
Once you are running you (kind of) have debugging tools, can see the DOM and see console messages. And my favorite part, is that once you have hacked out a basic add-in concept with buttons and text in the HTML and code in the script file, you can export your solution (Export for publishing). This will create a ZIP which will contain the XML manifest and HTML (with script inline), which is very similar to the minimalist add-in I outlined in a previous blog post:
NOTE: If you do write async/await code the exported result will be very ugly and hard to follow. This is why you might want to export to GitHub if you use async/awat code (TypeScript) so you can keep the original source and then transpile to ES5 later.
However, I really like VS Code and the power of NPM and Browser-Sync, so I worked on converting a Script Lab project into an NPM project. This took quite a lot of work and that will be a topic for a future blog post, but the gist of it is to create a new Office Yeoman (yo office) project for the same application and then gut and Frankenstein it with the Script Lab code.
Bottom line, I love Script Lab. If you are working on an OfficeJS project and/or planning on creating an OfficeJS project and/or want to learn how to develop in OfficeJS, this is definitely THE tool to have.
Several customers have asked me if OfficeJS has something similar to a Visual Basic or C# MessageBox.Show() function. The answer is no. And for a long time there was not even a dialog option. With the latest releases of the OfficeJS libraries comes a new dialog feature. Yet to get a standard MessageBox, you will still need to create it from scratch. Or, at least until this blog post you did. I have created a helper library the consists of two files:
dialogs.js
dialogs.html
To reference this library you can do any of the following:
NOTE: This assumes your page is in the root of your project. The key point is that it is added to your node_modules when you use NPM and this is how you will reference it.
Once referenced you can then call a MessageBox like this:
[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
MessageBox.Reset();
MessageBox.Show("This is a test with a lot of text that simply has not point but to show you what " +
"happens when you place a lot of text in a MessageBox for any point other than to " +
"place a whole lot of text in the MessageBox.",
"This is the Caption",
MessageBoxButtons.AbortRetryCancel,
MessageBoxIcons.Stop,
true, "Check this if you want me to stop nagging you.",
function(buttonPressed, checked) {
console.log("The button pressed was: " + buttonPressed);
console.log("The checkbox was checked? " + checked);
});
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
InputBox.Reset();
InputBox.Show("What value do you want to enter?",
"InputBox caption",
"Default value", function(result) {
var msg = "";
if(result.length == 0) {
msg = "The user pressed cancel.";
} else {
msg = "The user entered: " + result;
}
console.log(msg);
});
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
You can show a custom form of your own design like this:
[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
Form.Reset();
Form.Show("/test.html",10,20,false,function(result){
var yourJSON = JSON.parse(result).Result;
// if you placed false in the 4th param you must
// handle the close of the form
Form.DialogClose();
});
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Here is an example of what the above code looks like:
It is important to note that like everything else in the OfficeJS world this is an async dialog. This also means it is non-blocking. This means any code you do not have in your callback method will continue to run. And if you are wanting to display multiple message boxes at the same time – you cannot. The last one you try to display wins, the others will be gone. Most everything in this dialog is just like you will remember from the good ol’ Visual Basic/C# MessageBox and InputBox. Even the constants for MessageBoxButtons and MessageBoxIcons are the same. But, I added a little flare and it probably helps with the best practices in OfficeJS to not nag the user with dialogs, and that is the ability to add a check box to the form so you can ask the user if they do not want to be bothered by your code anymore.
For the MessageBox, the withcheckbox and checkboxtext are there to give you that ability. Additionally, you see the callback method (asyncResult) that will return once the use dismissed the dialog. It will return with two pieces of information:
The button the user clicked in string format. So “Yes” or “Cancel” will be what you see here.
A Boolean representing whether the check box was checked or not.
For the InputBox, the callback method (asyncResult), will return one piece of information. If will return the text the user entered, or it will return nothing (an empty string), if the user pressed cancel.
The Form method will return a JSON object:
Error: { }, // Error object
Result: { }, // JSON from form
Cancelled: false // boolean if formed cancelled with X
The Result object will be the JSON from your own form. In your code you will need to call back to the parent like this:
[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
Office.initialize = function(reason) {
$(document).ready(function () {
$("#okButton").click(function() {
// notify the parent
Office.context.ui.messageParent("My custom message.");
});
});
};
[/code]
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
You will also see in the examples above, I call .Reset() before I issue a new dialog request. This is because the objects are global and this is a way to be certain to clean up anything in memory that might be associated with a previous dialog. In my testing, I never really had problems like this, but I added it as an extra precaution.
Also, note, I have only tested this in Outlook OWA, I have not had a chance to test it in Excel, Word, PowerPoint or even in the full Outlook client. So, if you encounter issues in those other clients, please let me know.
Finally, I want to call out the OfficeJS Helpers. This library provides a lot of help with authorization dialogs, but also has a simple method for displaying messages using OfficeHelpers.ui.notify(). You can install it into your project using NPM:
As I delve ever deeper into the world of Node, I have found the ability to install packages with NPM quite handy. I do this from VS Code using the Terminal window. I just type:
npm install <packagename>
As I have been developing different packages for my customers, I have found the need to install code that I have been reusing over and over again. Most importantly, easyEws. So, I created a npmjs account (davecra) and I published easyEws. But what is even better and what I was after, is I can now install the latest version of easyEws by going into the Terminal window in VS Code and typing this: