Associating Data with Content Controls

**

Background reading
What is Custom XML- ... and the impact of the i4i judgment on Word,
Regarding Custom XML Patch distribution and availability,
Using Content Controls vs. Custom XML Elements,
Scanning tool to detect documents with custom XML

By popular demand, Eric White has returned to provide more guidance regarding the use of Content Controls. Eric's guest post today outlines more of how you can use Content Controls in your environment.

......

In a previous post on Gray's blog, I discussed an approach for building a content publishing system using styles and content controls. This is only one of the scenarios where content controls are useful. Another scenario is where you have a sophisticated document generation system where content controls are replaced with automatically generated text. The replacement instructions could be fairly elaborate - perhaps including the database server name, table name, filter, and column name, for example. In a different scenario, you may have a system that automates testing of code listings that are contained in documents, and you may have build instructions for each snippet in the document. I blogged about this approach in OpenXmlCodeTester: Validating Code in Open XML Documents.

Note: I co-wrote this post with Anil Kumar. Many thanks to Anil for writing the managed add-in code.

In all of the above scenarios, you may have the need to associate arbitrary amounts of data with each content control. You may also have the requirement that the document author can create and edit this auxiliary information. Content controls don't directly have a facility for storing and maintaining such information, but there is a fairly easy approach to solving this problem.

Note: In this post, I refer to 'custom XML parts'. Open XML documents are stored using the Open Packaging Conventions. They are essentially zip files (packages) that contain multiple XML and other types of files (parts) within them. These parts are related to each other by a very specific mechanism called relationships. A custom XML part is a part (a file in XML format) of your own design stored in the package. You can design your own XML vocabulary for this part. I've written an MSDN article, The Essentials of Open Packaging Conventions, which explains what you need to know to work with packages and parts. 'Custom XML parts' in this sense are not affected by January 2010 update  for Office Word that Gray has blogged about previously . Custom XML parts will continue to be supported in Word.

The gist of the technique for associating data with content controls is as follows:

You create a custom XML part that contains some XML that looks something like this:

If you need to maintain more than one value for each content control, you can have as many child elements of the Content element as necessary.

Each content control contains a unique ID that is assigned by Word upon creation of the content control. The data in the custom XML part is related to the content control using this ID. Following is the markup for one of the content controls that is related to the above XML:

You can make it easy for users to edit this auxiliary information in a custom task pane. To create this functionality, you create an Office managed add-in. When the focus is in a content control, the task pane is updated with information from the custom XML part, and when the user updates the data, the managed add-in updates the custom XML part. The following screen shot shows the task pane that is created by the example presented in this post:

As the user moves from content control to content control, the example updates the contents of the task pane. If the user moves to text in the document that is not in a content control, the example clears the text box in the task pane, and disables the "Update CustomXml Part" button. Another approach that you can take is to hide and show the task pane as the selection moves into and out of content controls. The example contains commented-out code that shows how to do this.

This example relies on the user pressing the "Update CustomXml Part" button. You may want to take another approach of updating the custom XML part data when the user changes any data in the task pane.

Custom Task Panes Overview provides a detailed explanation of custom task panes, and how to create them. Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System Using Windows Installer provides what you need to know to deploy an add-in.

There are three source files for this example:

You can download the code, along with a Visual Studio solution here.