Writing data from apps to Office documents
Inserting content into your Office documents is an important part of the app model. In this post, we'll talk about the Wikipedia app, how it inserts information into your documents, and ways you can use these APIs in your own apps.
A key feature of Office extensibility is that you can interact with your documents. For example, the Wikipedia app for Word and Excel, which we just released to the marketplace, enables you to insert content into Word documents or Excel spreadsheets. Although we do not recommend directly quoting Wikipedia in your papers (even Wikipedia says not to use Wikipedia in as an authoritative source), the app is a great way to assemble notes or quickly understand ideas from your reading.
Figure 1. Wikipedia app in Word
Although the Wikipedia app is a great example of adding content via apps, you can add even more content types on your own. In this article, we walk through the types of content you can use and provide some samples you can refer to as you get started.
What data can I write with my apps?
The data you can put into documents changes depending on the kind of document your app is inserted into. Apps for Word and Excel are particularly good candidates for inserting content.
| Platform | Content | |||||
|---|---|---|---|---|---|---|
| Images | Text | Matrices1 | Tables | HTML | OOXML2 | |
| Word 2013 | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| Excel 2013 | ✔ | ✔ | ✔ | |||
| Excel Web App | ✔ | ✔ | ✔ | |||
| PowerPoint 2013 | ✔ | |||||
1- Matrices are tables without headers and are manipulated as 2D arrays rather than JavaScript objects
2- Word documents can be edited by directly adding/removing/changing their XML nodes
Understanding where the app model’s features are enabled is key to creating quality apps. The Wikipedia app is usable in Word and Excel 2013, but it handles insertion differently depending on what Office product the user is working from. Apps written for Outlook or Project are for other scenarios, so we disabled using the app there from the app manifest.
Interacting with documents through Office.js
The JavaScript library file Office.js provides the APIs used to insert content into your documents. There are three major objects within Office.js that are key to inserting content into your document: Office.context, Office.context.document, and Office.documentMode.
Office.context
Office.context represents the runtime environment of the app—this object gets you the locales of the application, information on the document/mailbox (through Office.context.document), and any saved custom Outlook settings that the app may have. It’s useful if you want to change your inserted content depending on your user’s location or language.
Office.context.document
This API contains everything you need to directly manipulate your documents. There’s a whole lot this object can do, but to keep it simple here, we just focus on its setSelectedDataAsync method.
Office.documentMode
Office.documentMode is called to see if you have the proper permissions to read and write to your document. It returns a DocumentMode enumeration value (either Office.DocumentMode.ReadWrite or Office.DocumentMode.ReadOnly) that lets you see whether the document can or cannot be written to.
If the document is read-only, you won’t be able to insert any content. Allowing your users to try to write to a read-only document will cause the insertion call to fail. It’s a good idea to watch for this and to notify your user if and when this occurs.
Inserting data with setSelectedDataAsync()
You can insert content into your documents by calling Office.context.document.setSelectedDataAsync. The parameters passed through to the method change depending on the content being placed, but mainly focus on the data being inserted, what the content should be rendered as (we’ll call this the coercion type), and the function that is called when the method returns. The apps for Office API docs have a good overview of the details—check them out to learn more.
Text
Oftentimes, you want to insert some kind of text into your user’s document. The user can then format and adapt the inserted text to fit his or her needs. In the Wikipedia app, we use this to insert snippets of articles, but for simplicity here, we insert a static line of text.
To insert text, pass a string object as the data in setSelectedDataAsync. No coercion type is necessary.
Tables and matrices
If you have tabular data, you can insert content through tables or matrices. Matrices are simple grids of information and can be inserted as two-dimensional arrays.
If you want to include headers, or want to use the data as a JavaScript object before it is inserted, you can create an Office.TableData object and insert the data that way.
HTML
If you want to format some content before putting it in your document, you can do so using HTML.
Although your inserted text takes the document formatting, you must insert HTML to do app-specific styling.
OOXML
In the event that you cannot insert content through any of the above methods, and if you are in Word 2013, you can directly alter the structure of the document by inserting OOXML nodes. This gets complicated fast—refer to the Apps for Office CustomXmlNode APIs for more information.
Images
There is no image coercion type for setSelectedDataAsync. If the image you are trying to insert already exists, and you have a path to it, you can insert it as HTML. If you have programmatically created the image or do not have a URL to include in your HTML snippet, you can insert the binary image in an OOXML node. Inserting the image through HTML is much simpler, but if your document goes offline or the image URL changes, the image won’t appear in the document. Make your design decision based on your situation and what format your data is in.
I have a cross-platform app. How can I know what data I can use?
“But I’m writing a cross-platform app!” you say, and, “I don’t know if my users are in Word or Project! Can I add HTML? What should I do?”
Instead of checking the product that your app is operating in, check whether the feature you want to use is enabled. Here, we are checking if the product the app is living in can even insert data into the first place:
Once you determine that the product can actually insert content, you can check whether your coercion type is supported in your document. The following example checks if OOXML is supported by your app’s document.
Once those two checks have successfully completed, go ahead and insert your data.
If you want to make sure the content is successfully inserted, you can add a simple if statement within the return function:
The status property of AsyncResult (result in the above code sample) returns an AsyncResultStatus enumeration, which indicates success or failure by its type.
What about Project and Outlook?
For now, apps living in Project and Outlook are consumption oriented. That is, they provide contextual information that complements your user’s work. While there are great apps you can write for these platforms, focus on consuming document data instead of inserting your own.
Where can I find some working examples?
If you’d like some working examples of app insertion, we have several examples to check out. All of the above examples are available in the attached Visual Studio solution, so you can see the code in action. Alternatively, the Wikipedia app for Office is open source – you can dig through the source on GitHub.
Use data in your documents!
Apps for Office that insert content into documents allow users to gather information without leaving Office. It saves time for the user and improves efficiency. Write apps that insert data to help your users get things done!