Did you miss the Message… box?

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:

• Download it from GitHub: https://github.com/davecra/OfficeJS.dialogs
• Add a script tag and point it at this CDN: https://cdn.rawgit.com/davecra/OfficeJS.dialogs/master/dialogs.js
• Or, use NPM to pull it into your node_modules: npm load officejs.dialogs

If you used NPM, you can reference then with a script tag like this:

[code lang=”html”]
<script type="language/javascript" src="./node_modules/officejs.dialogs/dialogs.js">
[/code]

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]

Here is what this will look like:

You can call up an InputBox like this:

[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]

Here is what the above code looks like:

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]

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]

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:

npm install –save @microsoft/office-js-helpers