DocumentSelectionChanged in Apps for Office

I have just posted a sample of how to hook the DocumentSelectionChanged event in the new Apps for Office programming model.

For the last two days of this week I am attending some training being put on by Microsoft around their new application framework being delivered with Office 2013 and SharePoint 2013. We’ve just taken the high level tour through the new Office 2013 application model. I’m really excited because it is just HTML + JavaScript running off a web-server rendered inside an office app. Integration between your code (JavaScript) and Office is achieved through a JavaScript library (JSOM).

To test our my new-found knowledge I slapped together a quick little demonstration which runs inside Excel 2013 records the various cell selections that users make. You can pull down the source from the ExcelSelectionChangedDemo repository on GitHub.

To get up and running with this on your local machine you are going to need a few things:

Given I am using a Git source code repository hosted up on GitHub you might also like to consider downloading the Git extensions for Visual Studio.

Getting back to the new application model. Apps for Office are literally just web-pages which pull in a special JavaScript file (office.js) and which is hosted within a frame within Office.

AppInOffice

In the screenshot above you can see the previously referenced code running in Excel 2013. The code that drives this is in the Gist below.

Looking through the code you can see that the HTML file is just referencing a bunch of JavaScript libraries and has some HTML which represents the UI. The interesting thing here (other than it runs in Office) is that they aren’t stopping me using any of the JavaScript libraries that I know and love – for example Knockout.js or jQuery (in fact the samples use jQuery by default).

The other file in the Gist (ExcelSelectionChangedDemo.js) is just a plain old JavaScript file. Let’s go through this one in a little bit more detail. On line 13 we register a function with the JSOM API (JavaScript Object Model for Office). In this case we are just telling Office to let us know when it is loaded so we can register a hook for the ready even from jQuery. The active ingredient is actually on line 20 where I can register to receive an event from Office when the DocumentSelectionChanged event is fired (EventTypes).

The SelectionChanged method handles the callback (line 27) and then uses JSOM to fetch the data that has been selected. This is a two step process. First you get notified that a data selection changed, then you ask the object model to give you the selected data via getSelectedDataAsync. As the name suggests, this is method asynchronously fetches the data so a callback is provided (in this case, DataSelected).

The DataSelected method takes a single JavaScript object which specifies the outcome of the call. If the call succeeded you will be able to get the data, if not, you will get some error details (refer to AsyncResult for details). Reasons for this call failing might include that you have asked the data to be coerced into a format that is not appropriate given the content selected in the document.

The rest of the code in the ExcelSelectionChangedDemo.js file is just code which drives Knockout.js to deliver data-binding. Each time the selection changes inside the Excel application a new element is added with a JSON representation of the AsyncResult object. Selecting any cell, or multiple cells in a rectangle on the screen should result in a successful output. If you use CTRL-click and select multiple random cells around the screen you should be able to trigger an failure.

I’m going to keep looking into the new application story around Office and SharePoint. I think it is a really positive step forward for Microsoft which might help win back some mind-share from web-developers. I hope the same that I created helps you get started too.

Thanks to Michael Stokesbary, Yina Arenas, and Russell Palmer for running the event. Also I just noticed that one of my colleagues at Readify, Jake Ginnivan is doing a presentation titled “Removing the shackles of the past – Office and SharePoint development in the Cloud” in Perth on the 12th of February. Check it out if you are interested and in the area.

One thought on “DocumentSelectionChanged in Apps for Office

  1. Pingback: F12 Developer Tools for Apps for Office | Mitch Denny

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s