Getting Started with OfficeJS

If you are just getting started with OfficeJS, then this post is for you. I will assume you have some understanding of what Office Web Add-ins are. However, there is one very basic point I will demonstrate in this tutorial:

  • An Office Web Add-In is simply a web site and an XML “description” file. I detailed this in this blog post. And we are going to build on that.

So, you are brand new to OfficeJS, and want to get started. The first thing you need to do is get your development environment up and running. There is a script for that:

Microsoft Office Development Environment Script

NOTE: For more information on this script, please read my blog post.

Next, you will need to pull down the Web Add-in Side Loader tool. Keep this ZIP on your desktop. This will be used later in the steps below to make it really easy for you to install the Add-in to Excel. However, if you prefer to do the steps manually, see the link below. For more information on this tool, please see my blog post and/or the GitHub repository.

Now that you have the development environment setup, lets build your very first, super basic Excel add-in:

  • Create a folder on your desktop called “MyFirstAddIn”
  • Open Notepad and copy/paste the code from HERE, then click File, Save, name it “manifest.xml”, change the type to “All Files *.*”, browse to folder on your desktop, and click Save.

NOTE: In this step you created the manifest file. This file will be used to “install” the add-in into Excel. Essentially, it will tell Excel where the web page is for the task pane.

  • Close Notepad, then open it again. Copy paste this code HERE, then click File, Save, name it “home.html”, change the type to “All Files *.*”, browse to the folder on your desktop, and click Save.

NOTE: In this step you created the primary file for website. This one file contains both the HTML and JavaScript needed to make the taskpane load in Excel.

  • Now you need to side load the manifest and you do that by first opening the ZIP file on your desktop: Set-WebAddin (v1.0.0.0).zip and extracting the Set-WebAddin.exe to the “MyFirstAddIn” folder.
  • Press Window+R to open the run dialog, and type CMD and press enter.

NOTE: This will open the Windows Command Prompt which you will use to sideload the add-in and run it.

NOTE: The word “sideload” is a fancy way to say install it for only your instance of Excel. It is also known as Developer Sideloading.

  • Change the directory to the folder on your desktop with this command:
cd "%userprofile%\desktop\MyFirstAddIn"
  • Next, type this command:
Set-WebAddin -test -manifestPath "%userprofile%\desktop\myfirstaddin\manifest.xml"

NOTE: In this step you have sideloaded the add-in to Office. This essentially tells Office you have an added an Excel add-in via the information in the manifest file which, when loaded tells Excel everything it needs to know about it, including where to find it. If you prefer to do the sideloading steps manually, you can follow them here.

  • Now you are almost ready. Type this last command (that is a dot/period at the end, very important):
http-server .

NOTE: The above steps start a local the http-server on your computer so that it will serve the webpage in the browser from the folder (.) you are current inside. You can now test this by clicking this link.

  • You are now ready to go. Simply open Excel and a new Blank Workbook. Then on the Insert tab, click the down arrow next to My add-ins and click BasicAddin. It should look like this:
The BasicAddIn in the Developer Add-ins menu
  • Your add-in Task Pane should load.
  • Click in cell A1, type “Hello World!”, and then in your Task Pane, click the “Click here” button and you should see “Hello World!” in the bottom of the page.
  • Once you are done, you can press CTRL+C in the command prompt window to shutdown the server and then to uninstall the add-in you can use this command:
Set-WebAddin -cleanup -manifestPath "%userprofile%\desktop\myfirstaddin\manifest.xml"

And that is it. There are three things to note here:

  • You created your first web add-in.
  • You did not use VSCode or any Integrated Development Environment. You did this only with Notepad.
  • But as an added bonus – you have also installed VSCode and the tools you need to start doing more complex things with Office Web Add-ins.

JavaScript, HTML, Web, CSS, front-end, back-end, web server, ports, local hosts… some, if not all of these are new terms if you are just getting into this new world of the Web and Web add-ins. But it does not have to be that complicated. As I referred to earlier, the following posts should be your next two stops on your journey:

Getting started as an OfficeJS Developer

Start Developing in OfficeJS Today with ScriptLab

If you have any questions, please reach out to me.

Microsoft Office Development Environment Setup Script

If you are new to Office Web Add-in Development, then this post is for you. Even if you are not new and you need to setup a new development environment, this post is for you too.

Now, as far as manually setting up a new Office web add-in development environment, there are a few sources for helping you get started. There is the official guide here:

Set up your development environment

And I have also written one here:

How to-Configure VSCode for Office Development

NOTE: Mine is a tad more complicated, but essentially walks you through setting up for full fledged development, including source control with Git. That article was actually more for me when I wrote it.

BUT WAIT, THERE’S MORE…

However, after a co-worker and fellow Office Developer (Marty Andren) and I got to talking about this topic, I had an idea to create a script essentially automating the entire process. That was how the Microsoft Office Development Setup script, or MODES was born. The script is posted in the following repository:

https://github.com/davecra/modes

The MODES script is provided as-is for folks who need to setup an Office development environment. It is a simple run it and done. Once you have completed this script you will have:

NOTE: This also installs http-server, a simple local web server that I hope to use in a forthcoming blog post that expands on a previous post demonstrating how easy it is to build a Web Add-ins from scratch.

NOTE: The script installs everything as local user, so there is no need for administrative permissions.

On the MODES GitHub post, you can follow the README directions to download and run the PowerShell script. If you are unfamiliar with PowerShell, you can just follow the steps and should walk you through what you need to do fairly quickly and easily.

If the above script cannot be run on your system (as a script), you can try to perform the steps manually by Copy/Pasting the following GIST into a PowerShell window and pressing enter:

This GIST is a “minified” version of the script on GitHib (no comments, no output and some lines are combined). So if you run this GIST, you will need to do give it time to complete as there is no feedback.

 

 

How to Fix IntelliSense in VSCode for OfficeJS

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.

Getting Started as an OfficeJS Developer

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:

  1. How JavaScript and HTML work together
  2. The HTML DOM model
  3. How to write HTML and define controls (buttons, text boxes, etc.) with an id
  4. 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:

  1. Setup and configure VSCode
  2. Start learning Office from the new quick start and tutorials on docs.office.com.
  3. You can also stick to the basics (no development environment needed) if you install and use Script Lab.

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.

Once you have your VSCode development environment setup for Office, and you are ready to start your first project, follow these steps I outlined for using the Yeoman generator.

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?

Happy coding.

Updated Outlook Web Add-in Sample

I will be presenting a demo at the MVP Summit 2018 for Outlook and also helping with some labs in Excel on the OfficeJS platform. In preparation, I updated my Outlook Sample on my GitHub. This sample was created in VSCode via a Yeoman template.

What the add-in does is a check of all users on the To/CC/BCC line, splits apart any groups (or groups in groups) and then checks to see if any of the user emails are external to your domain. If any external users are found it prompts you with dialog asking if you are sure you want to send:

Outlook Blocking Add-in

The updated add-in demonstrates:

  • The OnSend event
  • The use of dialogs
  • And the newly added ExpandDL function for Exchange Web Services through the makeEwsRequestAsync() call.

In this sample, I am using both of my libraries:

  • easyEws – to help with the ExpandDL call. Updated in a previous post.
  • OfficeJS.dialogs – to display the dialog you see above.

I also had to create a set of asynchronous functions and asynchronous recursive function calls to perform this work – which got a tad complex. For now all the code is in the function-file.js, but to help with splitting out all recipients and groups I might build this into a new library. For example, here is the function to recursively call itself asynchronously (splitting groups in groups in groups in groups…):

Anyway, I will be demonstrating this add-in and the functionality required at the MVP Summit. So if you are attending, I hope to see you there.

Outlook Email Reporting Sample

I just posted a new Outlook sample on GitHub. I have created something very similar to this sample for a couple of customers now and have been using this as a template. What this sample does is place a button on the Ribbon for users to report suspicious email to the administrator. The user will get the option to select why they think it is suspicious as well as provide a comment. When they click Send, it will email the administrator. The email address which receives this notification is configured in the URL for the add-in page via the manifest XML.

Anyway, I wanted to share this basic sample with the community so others can use this to quickly implement similar solutions in their environment.

All the details for configuring the add-in are in the README.md. Here is the link the new sample: https://github.com/davecra/Outlook.ReportAddin. I also created this in VS Code.

Please let me know if you have any questions or suggestions for other samples you would like to see.

Yo! Create an add-in from your Script Lab code

Let’s say you created the trappings of an add-in with Script Lab and now you want to make it into a stand-alone add-in. You can export your code (just the manifest and html), copy and paste it into an existing project, or upload to GitHub to share it, but you cannot easily convert it into a fully functional Web Add-in project from Script Lab. I took the time to figure this out, so you do not have to. wlEmoticon-hotsmile.png These steps will show you how to export your solution from Script Lab, import into VSCode, apply a Yeoman Office template and then begin testing it in Office Online with, ah… minimal effort (more or less). wlEmoticon-confusedsmile.png

Here are the steps:

      1. First install Script Lab in Excel. You can follow my post for that here: Start Developing in OfficeJS Today with Script Lab
      2. Next, we will load one of the sample. On the Script Lab ribbon, click Code. yo-scriptlab1
      3. Click the Samples button and then select Basic API Call.
      4. Next, click the Share button ( yo-scriptlab2 )and click Export for publishing, this will download a ZIP file in an Internet Explorer download dialog. Click Openyo-scriptlab3
      5. If you get a warning open the file, click Allow: yo-scriptlab4
      6. Select these two files, right-click and then click Copy:
        • basic-api-call.html
        • basic-api-call-manifest.xml.
      7. Leave the ZIP folder and download window open for now.
      8. Next, create a folder on your computer, call it “sample-1” then Paste (press CTRL+V) the two files into the folder. You can now close the ZIP folder you copied from and the download window.
      9. Next, you will need to have VSCode installed and configured for Office development. You can following my post for that here: How to Configure VSCode for Office Development.
      10. Open VSCode and press [CTRL+`] to open the Integrated Terminal.
      11. Change to the “sample-1” folder you created above, using the command: cd c:\\sample-1
      12. Type the following command: yo office sample-1
      13. You will then select the option as detailed below: yo-scriptlab5
      14. Once completed, on the File menu, click Open Folder. Browse to the sample-1 folder and click Select location.
      15. Delete the following files and folder:
        • app.js
        • app.css
        • index.html
        • rousource.html
        • and the function-file folder
      16. If you want to use Chrome as your debug environment, I would suggest this step which you will click to open the bsconfig.json file and add the following line: “browser”:”chrome” like this:
      17. Click to open the basic-api-call.html file and remove the following Script Lab lines:
      18. Save, close, then rename the file to index.html.
      19. Click to open the basic-api-call-manifest.xml and then CTRL+click to open the sample-1–manifest.xml in a side by side window (on the right).
      20. Copy the following lines from the left pane and replace the same lines by pasting them in the right pane:
      21. Save and close all open files. You can now delete the basic-api-call-manifest.xml file.
      22. Your project is now ready. Press [CTRL+`] to open the Integrated Terminal and type: npm start. Make sure it launches on port 3000 or your add-in will not load: yo-scriptlab6
      23. Your browser will open, if you have a wanting page, click Advanced and then click Proceed to the website. You will not see your index.html.
      24. Open a new tab and browse to https://office365.com and then sign in with your credentials.
      25. From the Office menu, click Excel, then open a new blank workbook.
      26. On the Insert tab, click Office Add-ins.
      27. In the upper right of the dialog, click Upload my add-in. Click Browse and then select the file: c:\<path>\sample-1\sample-1-manifest.xml.
      28. Your adding will now be loaded. On the Home tab, you can click to open the taskpane, click the button and it should highlight the selected cell.

One major caveat is that this is not a preferred way to make a Web Project. This is bare bones and really just to get you going with minimal effort (if you can call ~30 steps minimal effort). The important thing to know is that all your code in going to be embedded in script tags inside the the HTML file and not in a separate JS file (as preferred – a.k.a. Separation of Concerns). So keep that in mind as you perform this work. If eventually your project turns into something much bigger, you will need to do some housekeeping.

So, ~30 steps… It would be nice if there were a way to do this more simply, but for now, this is the best way to do this. I have had a discussion with the product team in charge of Script Lab and they agree with such a feature, so I will update this post if it becomes available at some future point. wlEmoticon-hotsmile.png