SPC046 – Creating apps for Excel, Word and PowerPoint – Rolando Jimenez

Rolando introduces the new investments by Microsoft for Apps for Office. This session is a deep dive into how to create apps in Excel, Word and PowerPoint.

Common App Architecture

 

The diagram shown highlights the architectural structure of the app model. The Office 2013 also contains a client side API. This allows apps to interact with the office content.

The session focus is on the client side logic so the:

App containing the HTML/CSS/JavaScript
Office JavaScript

Apps for Office – Recap

Web Page + App Manifest = App

Core concepts

• 3 shapes, Task Pane, Content and Mail shape
• Multi-platform and Cross App
  • Excel (web/desktop)
  • Outlook (Web/Desktop/Mobile Web)
  • Word (Desktop)
  • PowerPoint (Desktop)
  • Project (Desktop)
• JavaScript API
• Runtime sandbox

It is important to note that Apps for Office are agnostic to its host and is a core principle.

Principles

Cross Platform – designed from the ground up, providing abstraction, is async. Microsoft have not ported the old APIs (COM or .Net) into JavaScript they have built this from the first principles.

Cross App – common objects and methods across apps (selection, tables, settings) Principle is to present the office suite to a developer consistently and not really concern them whether they are in Word or PowerPoint. A selection is a selection.

Compatibility -Office version to version

Web standards – ECMAScript 5 e.g. Property get/set, strict mode, plain JS objects

Performance – async, limits. Things will be shut down which sap performance

Office JavaScript API Overview >

The diagram shows the hierarchy

• Office.context
  • Document
    • R/W selection
    • Bindings
    • Settings
    • CustomXmlParts
  • Mailbox
    • Item
    • User Profile
    • EWS
    • Properties & Settings
  • Project
    • Project Info
    • Tasks

This session will focus on the ‘document’ branch of the API

Demo

Basic Hello World example

Choose App for Office 2013 in VS2012

Demo app selection was all the Task Pane options

In the VS solution the Office App project is the top one, with the manifest file inside

Pressing F5 before any changes should run a working default code app

In the html there is a JS include for

<script src="../Scripts/Office/1.0/office.js"></script>

Which means the Office API is being included

But be aware that this file is actually on a MS CDN and this is actually commented out by default. So good practice is to change to use the CDN version. This will mean that as the API gets updated your app will get them.

The first step is to create the ‘Office.initialize’ function

This function is the runtime handshake, and the app will error if it is missing

For Excel, Word and PowerPoint the document object is the most important object to start from

To change the run client you can change the ‘start action’ to the client you want

You can change the type of data you can interact with you use the ‘coercionType:Office.CoercionType’ which allows you to set things like html, openXML etc.

During the demo Rolando used a snippet of html for bold text, enetered it into the task pane app and set data pasted it into the doc as bold text. Proving the API can interpret the html into the document.

Note: You can change the html during debugging if you just click save and F5 in the app window

Demo of the OpenXML and its power

This is very useful where you have complex information content.

Org chart example showed how the app can interact with OpenXML to fill an orgchart form data in the app

Bindings Example

Bing map example bound to the data

The project is a Content app

Used the OOTB Bing Map scripts

Technique: In Office Apps the JavaScript ‘alert’ has been suppressed so as a developer you need to implement somewhere to show messages and debugging markers.

Note: the selection supports text/matrix and tables

Demo showed a basic map insertion and setting pins on the map based on selection of cells

To add a binding to the document call into the ‘Office.context.document.bindings’ object

To have the content app react an event handler needs registering

This can then react and make the app change based on whether data or selections have changed.

Settings example

Code example:

_doc.settings.set("mode", _mode);
_doc.settings.saveAsync();

Which persists the mode setting of the app into the document.

Technique: think about this state persistence for you apps, as a usability aspect it would be important

Custom XML Parts

A hidden and powerful feature in Office

These were introduced in 2007, documents can store islands of xml data, these are called custom XML parts within a document file.

Content Control Binding to parts

Word has content controls, these have been around since 2007 , these controls act as containers for specific kinds of content. Content controls can be mapped to nodes within the custom XML part.

There is now a new repeating section content control. This control provides the capability to bind to a collection of nodes.

Note: How to enable the Word developer tab, Backstage >> Options >> Customise Ribbon >> Right hand list has the ‘Developer’ and check it.

The developer tab allows the viewing and editing of the XML mapping pane

You can add a new part from that task pane.

Once the content is inserted into the xml mapping pane, you can right click and choose ‘insert content control’ and select the type of control you need.

Word also now has a repeating content control. So you can create a table, insert values from the XML and then highlight the entity and insert a repeating control to make it repeat for the length of the entity array.

Of course the example was done manually, but it can be done via the app code as well. This becomes powerful to embed data into the document.

Example used was an invoice document bringing in the data from another service. This is a very cool use case.

Operations that can be performed

1. Add/Delete custom XML parts
2. Get XML parts
3. Get/Set node values
4. Event handlers for node deleted, inserted, or replaces

Core objects for working with custom XML parts

1. CustomXmlPart
2. CustomXmlParts
3. CustomXmlNode
4. CustomXmlPrefixMappings

Connecting to SharePoint

How Apps for Office relate to SP

Now that Office365 contains Office, Exchange and SharePoint developers can now take advantage of this to create very complex solutions which span these technical capabilities.

Example is a simple task pane app which works in Word or Excel called ‘SPLister’

What this demo app does is allow the selection of any table that exists in the document, and then automatically generate a SharePoint list of it.

A key note is that the app needs to be told the SP url

The demo app is running from Azure so it will need to get into SP via Oauth

When invoked SP realises and asks the user to trust that app via Oauth consent flow page

Once SP issues the app with its access token it can start to communicate to the app.

The app is using the client side OM to create the list.

The demo app has both client and server side code. This was a little frustrating as it would have been great to see this being a JavaScript only hosted app.

Showed the ‘Seller Dashboard’ and the client ids

The ‘client id’ is the id which allows you permissions to request access to SharePoint in Office365

Code example for initialising the authentication to SharePoint.

function initAuthFlow(siteUrl, inSameWindow) {
authorizeUrl = siteUrl + "_layouts/15/OAuthAuthorize.aspx?IsDlg=1";
authorizeUrl += "&client)id=" + $("#clientId").val();
authorizeUrl += "&scope=Web.Manage";
authorizeUrl += "&response_type=code";
authorizeUrl += "&redirect_uri=" + $("#redirectUrl").val();
authorizeUrl += "&state=" + siteUrl;

if (inSameWindow) {
//Perform authorization flow in this window
window.location = authorizeUrl;
} else {
//Open a new window to perform the authorization flow
authWindow = window.open(authorizeUrl, "authWindow");
codeListener(); //Start listening for the auth code
}
}

This code will start the auth request, this allows the permission. The client id provides the identifier for the calling app. The code also requests the permissions it needs on SharePoint. The code asks for the auth code in the url and provides the call-back redirection url to send it too.

The example app has the handling logic for the returned auth code in the C# code behind of the aspx app page. The ‘TokenCache’ and ‘TokenHelper’ classes are used to handle storage of the returned token to reduce the need to keep asking for it.

Functional areas v’s App support summary

 

Functional area	Word	Excel/Excel WAC	PowerPoint	Outlook/OQA	Project
Get/Set data as text, table, matrix	X	X	X		X
Settings	X	X	X	X
Get File	X		X
Bindings	X	X
Custom XML Parts	X
Html and OOXML	X
Mailbox				X	X

Resources

http://dev.office.com

Summary

A good overview into the power of Apps for Office. It was disappointing that the question of how to host them within SharePoint (not AZURE) remained unanswered. I’m guessing that an ‘auto-hosted’ SharePoint app might be the answer, but only some trial and error will confirm that.