Leanpub Header

Skip to main content
Go to Leanpub.comLeanpub

Building Office Add-ins using Office.js

Michael Zlatkovsky

This book is a guide to building Office Add-ins, describing the principles and design patterns shared by the new 2016+ APIs for Excel, Word, and OneNote.

Download some sample book content, or buy it today. All proceeds from the book go to humanitarian work / disaster-relief, matched by Microsoft's generous Employee Match program. More info here.

Minimum price

$15.99

$19.99

You pay

$19.99

Author earns

$15.99

Packages

Details
$

...Or Buy With Credits!

You can get credits with a paid monthly or annual Reader Membership, or you can buy them here.
PDF
EPUB
WEB
1,185
Readers
261
Pages
53,426Words
About

About

About the Book

This book is about creating Office Add-ins – and in particular, about the Office 2016+ wave of Office.js APIs.

Want to get started with just the very core concepts, before buying the book? Download some sample chapters, or better yet, buy the book regardless: I am sure you'll find the topics therein new and useful for writing add-ins; and if you don't, LeanPub's Happiness Guarantee will let you get a full refund anytime in the first 45 days.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All proceeds from this book will be donated to humanitarian work / disaster relief (and also get matched by Microsoft's generous Employee Match program, for double impact). See the detailed accounting here.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Office 2016 has seen a major re-birth of the API model, with hundreds of new APIs created for Excel and Word and OneNote. These APIs are cross-platform, are built on a modern web framework, and offer some of the same powerful functionality that previously was only available on the Desktop.

In spirit, the new Office.js APIs are reasonably similar to their VBA/VSTO counterparts, but with the notable difference of being async – which brings with it a new set of concepts and best practices. This book will begin by address the core concepts to help you get over the initial learning curve, and get started on using the APIs. The subsequent chapters will expand upon these topics, covering more advanced scenarios, and offering debugging advice, tips, FAQs, and so forth.

Yours truly,

- Michael Zlatkovsky, the author (and member of the Office API team from 2015-2019)

Share this book

Categories

JavaScriptSoftware

Feedback

Email the Author

Packages

Pick Your Package

All packages include the ebook in the following formats: PDF, EPUB, and Web

The Book

Minimum price

Suggested price$19.99

$15.99

    3 Copy Package

    Minimum price

    Suggested price$55.00

    This package is for THREE copies of the book, to distribute among your Dev team, at a small discount. After checkout, in the confirmation/download page, you will see "You have purchased multiple copies of this Book. Click here to manage your download tokens." You can use this to send out the individual tokens to team members. That way, only one person (e.g., a team admin with a corporate credit card) needs to go through the checkout process, and the rest can just download the book.

    $45.00

      This book is also available in the following packages:

      • 5 Copy Package

        This package is for FIVE copies of the book, to distribute among your Dev team. After checkout, in the confirmation/download page, you will see "You have purchased multiple copies of this Book. Click here to manage your download tokens." You can use this to send out the individual tokens to team members. That way, only one person (e.g., a team admin with a corporate credit card) needs to go through the checkout process, and the rest can just download the book.

        Minimum price
        $75.00
        Suggested price
        $85.00

      Author

      About the Author

      Michael Zlatkovsky

      This book is written for Office Developers, by an Office Developer. By the latter, I mean both that I had been a developer who used Office technology extensively for a number of years, and that I am now a developer on the Office Extensibility Platform team – the very team that created Office Add-ins.

      Having been a key participant in the design of the new Office 2016 wave of Office.js APIs – and having seen folks embrace the framework, but struggle with some of the more concepts – I wanted to share some insights & techniques, as well as the full end-to-end story, of how to create Office Add-ins.

      You can find me on StackOverflow, where I frequently answer questions tagged as "[office-js]" (which has been a source of inspiration for many sections of this book).  I have a backlog of topics I want to cover in this book: some already fleshed out, others less so.  In the spirit of the "lean" methodology, I will be updating the book frequently as I cover more and more topics.  Thanks for reading, and please feel free to contact me for feedback on the book, requests for topics, etc.

      Yours truly,

      - Michael Zlatkovsky

      Contents

      Table of Contents

      1The book and its structure

      1. 1.1The “evergreen”, in-progress book
      2. This book is published using a “lean” methodology – publishing early, and publishing often.
      3. 1.2Release notes
      4. Version 1.6 (August 26, 2017) [261 pages]
      5. Version 1.5 (August 2, 2017) [249 pages]
      6. Version 1.4 (July 19, 2017) [232 pages]
      7. Version 1.3 (May 23, 2017) [217 pages]
      8. Version 1.2 (Feb 20, 2017) [210 pages]
      9. Version 1.1 (Jan 22, 2017) [189 pages]
      10. Version 1.0 (Dec 12, 2017) [144 pages]
      11. 1.3Bug reports / topic suggestions
      12. 1.4Twitter
      13. 1.5Who should read this book
      14. 1.6From the author
      15. 1.7A few brief notes
      16. 1.8Acknowledgments

      2Introduction to Office Add-ins

      1. Chapter structure & planned content
      2. 2.1What’s “new” in the Office 2016 APIs (relative to 2013)?
      3. 2.2What about VBA, VSTO, and COM Add-ins?
      4. 2.3“But can Office.js do XYZ?”
      5. 2.4A word on JavaScript and TypeScript
      6. 2.5Office.js: The asynchronous / deferred-execution programming model
      7. 2.5.1Why is Office.js async?
      8. 2.5.2What is meant by “the server”

      3Getting started: Prerequisites & resources

      1. Chapter structure
      2. 3.1Script Lab: an indispensable tool
      3. Import someone else’s snippet, or export your own
      4. 3.2The optimal dev environment
      5. 3.3API documentation resources

      4JavaScript & Promises primer (as pertaining to our APIs)

      1. Chapter structure & planned content
      2. 4.1“JavaScript Garden”, an excellent JS resource
      3. 4.2JavaScript & TypeScript crash-course (Office.js-tailored)
      4. 4.2.1Variables
      5. 4.2.2Variables & TypeScript
      6. 4.2.3Strings
      7. 4.2.4Assignments, comparisons, and logical operators
      8. 4.2.5if, for, while
      9. 4.2.6Arrays
      10. 4.2.7Complex objects & JSON
      11. 4.2.8Functions
      12. 4.2.9Functions & TypeScript
      13. 4.2.10Scope, closure, and avoiding polluting the global namespace
      14. 4.2.11Misc.
      15. 4.2.12jQuery
      16. 4.3Promises Primer
      17. 4.3.1Chaining Promises, the right way
      18. 4.3.2Creating a new Promise
      19. Native promises, vs. polyfills, vs. OfficeExtension.Promise.
      20. 4.3.3Promises, try/catch, and async/await
      21. JavaScript-only

      5Office.js APIs: Core concepts

      1. Chapter structure
      2. 5.1Canonical code sample: reading data and performing actions on the document
      3. Try it out
      4. JavaScript-only
      5. 5.2Excel.run (Word.run, etc.)
      6. 5.3Proxy objects: the building-blocks of the Office 2016 API model
      7. 5.3.1Setting document properties using proxy objects
      8. 5.3.2The processing on the JavaScript side
      9. 5.3.3The processing on the host application’s side
      10. 5.3.4Loading properties: the bare basics
      11. 5.3.5De-mystifying context.sync()
      12. Looking for a JavaScript-based (non-async/await) template instead, for a multi-sync scenario?
      13. 5.4Handling errors
      14. 5.4.1The basics of Office.js errors
      15. 5.4.2Don’t forget the user!
      16. 5.4.3Some practical advice
      17. 5.5Recap: the four basic principles of Office.js
      18. Try it out

      6Implementation details, if you want to know how it really works

      1. Chapter structure
      2. 6.1The Request Context queue
      3. 6.2The host application’s response
      4. 6.3Back on the proxy object’s territory
      5. 6.4A special (but common) case: objects without IDs

      7More core load concepts

      1. Chapter structure
      2. 7.1Scalar vs. navigation properties – and their impact on load
      3. KNOWLEDGE CHECK:
      4. 7.2Loading and re-loading
      5. 7.3Loading collections
      6. Common error when accessing items on a collection:
      7. 7.4Understanding the PropertyNotLoaded error
      8. 7.4.1What does it even mean?
      9. 7.4.2Signaling your intentions: an analogy
      10. 7.4.3Common mistake: re-invoking get methods (and in general, loading on methods versus properties)
      11. 7.4.4Another common mistake: loading nonexistent properties
      12. 7.4.5A rarer and more befuddling case: when using an object across run-s
      13. 7.5Methods that return “primitive” types (strings, numbers, etc). E.g.: tables.getCount(), chart.getImage(), etc.

      8More core sync concepts

      1. Chapter structure
      2. 8.1Real-world example of multiple sync-calls
      3. SCENARIO: A grade book tool
      4. Looking for a similar JavaScript-based (non-async/await) sample, instead?
      5. Download sample code
      6. 8.2When to sync
      7. 8.3The final context.sync (in a multi-sync scenario)
      8. 8.4A more complex context.sync example:
      9. Scenario: Stock-tracker and net-worth calculator
      10. Splitting work across multiple subroutines
      11. Download sample code
      12. 8.5Avoiding leaving the document in a “dirty” state

      9Checking if an object exists

      1. Chapter structure
      2. 9.1Checking via exception-handling – a somewhat heavy-handed approach
      3. An analogy
      4. 9.2A gentler check: the *OrNullObject methods & properties
      5. 9.2.1Case 1: Performing an action, and no-op-ing otherwise
      6. Important: Objects may be weirder than they appear, once you enter *OrNullObject territory!
      7. 9.2.2Case 2: Checking whether the object exists, and changing behavior accordingly
      8. A corollary to the OrNullObject pattern: there is no need to check for isNullObject unless you are in *OrNullObject land.

      10Excel.run (Word.run, etc.) advanced topics

      1. Chapter structure & planned content
      2. 10.1What does “.run” do, and why do I need it?
      3. 10.2Using objects outside the “linear” Excel.run or Word.run flow (e.g., in a button-click callback, in a setInterval, etc.)
      4. 10.2.1Re-hydrating an existing Request Context: the overall pattern, proper error-handling, object.track, and cleanup of tracked objects.
      5. Try it out
      6. Try it out, midway
      7. Try it out, the completed code
      8. 10.2.2A common, and infuriatingly silent, mistake: queueing up actions on the wrong request context
      9. 10.2.3Resuming with multiple objects
      10. 10.2.4Why can’t we have a single global request context, and be one happy family?

      11Other API Topics

      1. Chapter structure & planned content

      12The practical aspects of building an Add-in

      1. Chapter structure & planned content
      2. 12.1Walkthrough: Building an Add-in using Visual Studio
      3. 12.2Getting started with building TypeScript-based Add-ins
      4. 12.2.1Using Visual Studio
      5. 12.2.2Using Yeoman generator & Node/NPM
      6. 12.3Debugging: the bare basics
      7. 12.4IntelliSense
      8. 12.5Office versions: Office 2016 vs. Office 365 (MSI vs. Click-to-Run); Deferred vs. Current channels; Insider tracks
      9. The golden path
      10. Why you should care
      11. 12.6Office.js API versioning
      12. 12.6.1The JavaScript files
      13. 12.6.2The host capabilities
      14. Important: Version numbers are per API SET
      15. 12.6.3The Beta Endpoint
      16. Tip: writing isSetSupported for the Beta endpoint
      17. 12.6.4How can you know than an API is “production-ready”?

      13Appendix A: Using plain ES5 JavaScript (no async/await)

      1. Chapter structure
      2. 13.1Passing in functions to Promise .then-functions
      3. JavaScript-only
      4. 13.2JavaScript-only version of the canonical code sample
      5. JavaScript-only
      6. Try it out
      7. 13.3JavaScript-specific sync concepts
      8. 13.3.1A JavaScript-based multi-sync template
      9. 13.3.2Returning the context.sync() promise
      10. 13.3.3Passing values across .then-functions
      11. 13.3.4JavaScript example of multi-sync calls
      12. Download sample code

      14Appendix B: Miscellanea

      1. Chapter structure
      2. 14.1Script Lab: the story behind the project

      The Leanpub 60 Day 100% Happiness Guarantee

      Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

      Now, this is technically risky for us, since you'll have the book or course files either way. But we're so confident in our products and services, and in our authors and readers, that we're happy to offer a full money back guarantee for everything we sell.

      You can only find out how good something is by trying it, and because of our 100% money back guarantee there's literally no risk to do so!

      So, there's no reason not to click the Add to Cart button, is there?

      See full terms...

      Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

      We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

      (Yes, some authors have already earned much more than that on Leanpub.)

      In fact, authors have earned over $14 million writing, publishing and selling on Leanpub.

      Learn more about writing on Leanpub

      Free Updates. DRM Free.

      If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

      Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

      Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

      Learn more about Leanpub's ebook formats and where to read them

      Write and Publish on Leanpub

      You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

      Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

      Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

      Learn more about writing on Leanpub