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:
- Setup and configure VSCode
- Start learning Office from the new quick start and tutorials on docs.office.com.
- 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.
