Create a Document Template for Word or Excel that Contains an App for Office

Apps for Office within Documents and/or Templates

If you have already installed some apps from the Store on office.com into your Office 2013 clients, then you will have noticed that the app for Office only interacts with the document at the point where the user has placed the insertion point in the document, or has selected text, etc. Essentially, the app requires user actions for the app to interact with the document. This is great for apps where you want the user to be in control of the where and when in the document authoring experience. But what about line-of-business or other cases where you want to present the user with a preformatted document with “known” locations within the document that you want to manage/interact with programmatically?

A great example of this is the Bing financial portfolio template. Open Excel 2013 and type “bing” in the search bar to search for the Bing template. Then click on the template and choose Create. When the document loads, take whatever steps necessary to enable the app and you’ll see that the app is essentially pre-loaded in association with the document and can interact with the document by updating stock data even without some user interaction. Also if you search for a stock in the app that is not in the pre-loaded table in the document, you can choose to add it to the table by clicking the Add button. Notice that it adds it to the bottom of the table without you needing to have a location pre-selected where to add the row. This is because the app “knows” locations in the document that it can interact with. This is quite powerful and certainly something that you as a developer should be aware of how to do this. It may provide some neat opportunities for your apps for Office. So let’s get after it.

A Word app for Office with Content Controls

So we don’t reinvent the wheel here and so that we use a code sample that is available to all, the MSDN team has provided a sample app that will serve as a great starting point for us. Open the Apps for Office: Binding to and validating content controls in Word 2013 code sample landing page. Confirm that you have all the prerequisites in place, download the code sample and open it in Visual Studio.

1. Once loaded, click on the CorporateBio project and make sure that the Start Action property is set to CorporateBio.docx.
2. Press F5 to start debugging. Word will load the document but notice that you need to Insert the Corporate Bio app from the Apps for Office ribbon dropdown. This means that the app for Office and the document are not “coupled”. In other words the app and the document are independent from each other, the only thing is that the when the app opens, it can locate “known” locations on the document.
3. These “known” locations are in the form of content controls. Click on one of the content controls in the document. Notice that it has a name. The name is what the JavaScript method .addFromNamedItemAsync("EmployeeName", …) uses to bind to this known location in the document. You can see this in the $(document).ready(function () in the CorporateBio.js file. 
4. To add content controls to the document you need to enable the Developer tab in Word. Click File, Options, Customize Ribbon, and in the right-hand column under Main Tabs, check the Developer tab so that it will activate.
5. Return to the document and click anywhere within the document. Click the Developer tab, in the Controls group, click the Aa (the Rich Text Content Control is the only one the apps for Office JSOM can interact with).
6. Click on your newly inserted content control so it’s highlighted and click the Properties button in the Controls group. Notice that the title is empty by default, however, this is the property that the JSOM will bind to as a named item. Enter a Title of your choice, “TestTitle”, etc. and click OK and you’ll see that your content control is now named. The point here is that this is how the other three content controls on the page were created and named.
7. As noted above, when you pressed F5 and the document opened, you needed to insert the app so let’s now fix that and “couple/associate” that app with the document. Simply click Save. Now, close the document to stop debugging and then click F5 again. Notice that the app and document open together now.

The anatomy of the .docx file with an app for Office

1. Now let’s take a look inside the .docx file to see how this is all recorded in the OOXML. To do so you can copy the CorporateBio.docx file out of the project into another location if you like or just take my word for it as I step through this.
2. Once the file is in a new location, change its extension from .docx to .zip.
3. Right-click the .zip file and choose to extract all.
4. When the file is extracted, open the word folder, webextensions folder, and open the webextension1.xml file in any xml viewer.
   
5. There are a couple things to note here:
   1. Notice that the attribute storeType is “Registry” and the store is “developer”. These two attributes point to where the Office client needs to look for the manifest file for the app that is associated with this document. Because this document was saved while the app was running in Visual Studio, these are the settings that get saved within the document. Since our document will not always be opened within a Visual Studio context, we’ll come back to this below and show how to get these attributes set to another location for the manifest.
   2. Notice the bindings and binding elements. The id attribute is of interest here. See that it’s not the name of the content control that is in the document, but it’s the optional parameter name of the binding, e.g. { id: 'nameBinding' }, that we passed in to .addFromNamedItemAsync in the CorporateBio.js. This is just to show that the binding ids are recorded here in the OOXML.  

Getting the coupled/associated app for Office and Manifest file in sync

1. Ok, so now let’s say you’re done testing your coupled/associated app for Office and document and you’re ready to make it available within your enterprise. For this example we’ll just make it available using a network share to host the manifest file. If you need guidance on how to setup a network share for apps for Office manifest files see that section in my previous post for a step-by-step.
2. At this point you could also publish the CorporateBioWeb out to Windows Azure Web Sites if you like to lock in an absolute URL for the app, but that’s optional. Again, you can see this post for steps on how to do that. But to keep things straightforward, we’re simply going to use the URL for the app running in IIS Express.
3. In the Solution Explorer click on the CorporateBioWeb project and confirm that it’ SSL Enabled property is set to True. (If you needed to click it to True, you should run your app one more time so IIS Express will have your app running under https too.) Then copy the SSL URL value.
   
4. In the Solution Explorer under the CorporateBioManifest node, double-click the CorporateBio.xml file to open the manifest file. Replace the ~remoteAppUrl/ with your https://localhost:yourport/ you just copied.
   
5. Save the manifest file changes.
6. Now to work some “manual” magic for how to get things all wired up for use outside of Visual Studio.
7. In the Solution Explorer, right-click on the CorporateBio project and choose, Open Folder in File Explorer.
   1. Open the CorporateBioManifest folder, copy the CorporateBio.xml file and save it in the network share folder you setup for manifest files.
8. Since the CorporateBio.docx file within the Visual Studio project is now wired up to point to the Registry for its manifest file we can’t use that document outside of Visual Studio, if you do, you will get the following error when the app loads in Word.
   
9. Therefore, you’ll need to get a fresh copy of the CorporateBio.docx file that is in the sample .zip folder. Open the original .zip folder and copy the CorporateBio.docx file to a location of choice. (Note: if you copied the file directly out of the .zip, then right-click the .docx file, choose properties, and click the Unblock button.)
10. Double-click the CorporateBio.docx file, click the Insert tab, drop-down the Apps for Office and select See all…
11. In the Apps for Office dialog, click on the SHARED FOLDER and you should see the Corporate Bio app, if not click the Refresh button. Once you see the app click on it and then click the Insert button.
12. If you see an exclamation point icon warning click on it. And then click the Start button to load the app. (see the step 9 note to fix this)
13. Once the app loads, click File, Save As and provide a name. You can save this as either a Word Document .docx or a Word Template .dotx file. either will have the app coupled/associated with the document.
    
14. And how does the OOXML look now? The storeType is “Filesystem” and the store is you file share location.
    

 

An Excel app for Office with Named Ranges

So that’s great for Word, but what if I want to do the same this for Excel? Well, since the JavaScript Object Model for Office works across both Word and Excel let’s tweak the manifest and wire this up in Excel without needing to go into Visual Studio at all.

Update the app manifest to for Excel

1. Navigate to your network share location for the manifest files and open CorporateBio.xml in any text editor.
2. In the Capabilities node, add <Capability Name="Workbook" /> and save the file. (Note: you might want to increase the version number in the manifest file so the Office clients will load the updated manifest since the previous one may be cached by the clients.)
   
3. Now open Excel and a new blank workbook.
   1. In the first column, enter in each cell: Name: , Position: and About Me: .
      
   2. Click on cell B1, then in the upper textbox where you see B1, replace it with the name “EmployeeName” and press the ENTER key. After you type in the value you must press the ENTER key for Excel to retain it. You can confirm Excel knows this named range by clicking the B1 cell. EmployeeName should be showing.
      
   3. Repeat the above step for cells B2 and B3, providing the names “EmployeePosition” and “EmployeeAboutMe” respectively.
   4. Now, choose Insert app for Office and select Corporate Bio. Once it loads Save As an Excel Workbook .xlsx or an Excel Template .xltx.
   5. Wow, that was easy!! The only thing to note here is that the Validate data logic may need to be updated since the code sample was hard-coded to only compare against the default literal values within content controls to see if the data had changed and Excel cells do not have the default text.
      

Summary

In this post you used a MSDN code sample that does data binding to content controls within Word. You worked this forward to see how the app can be coupled/associated with a document. Then the OOXML was exposed to help provide understanding that the end result for the document you want to distribute, must have the known location for its manifest file saved within the document. This known location can be a network share, a corporate catalog on an on-premises SharePoint 2013 site or in Office 365 SharePoint Online, or in the Store on office.com. So, essentially the document you want to distribute with the coupled/associated app, must have been saved while accessing the manifest end-point that the users of the document will have access to.

Documents and templates with apps already in them is a great way to provide user experiences where you have done all the complex setup and you have predetermined locations within the document where you can programmatically push and retrieve information at will. New opportunities abound!

Enjoy!