Programmatically creating content controls

  • Article

The concept of content controls is one of the most powerful features in the new Open XML file formats. It allows developers to truly separate the presentation of custom XML fields in a rich word-processing document from the underlying XML nodes themselves.

Content controls let you create a complex-looking document that has a simple little XML part within it, and developers can repopulate the document with custom values (generated from a database system, say) by writing a simple little XML chunk that contains nothing more than the custom XML nodes. For a high-level look at the concepts involved, check out Erika Ehrli's very thorough article over on MSDN entitled "What's New for Developers in Word 2007."

If you have the Office 2007 Beta 2 TR version installed, you can also get a feel for custom content controls very easily in the Word UI itself. For example:

  • open Word, click the Insert tab, then click Quick Parts, Document Property, and Author
  • a content control will be inserted in your document, automatically bound to the selected document property (Author in this case)
  • click the Office button (the little circle in the top left corner), then Prepare, then Properties
  • this will make the Document Properties panel appear above your document

Now you can see how binding from content controls works. If you type something into the inserted content control, it will immediately be updated in the Author field of the document properties panel. And vice versa: change it in the panel, and your change immediately appears in the content control in the document below.

Note that this example doesn't include a custom XML part, actually -- the content control is bound to a document property, which is stored in the document properties part (core.xml). But the same concepts apply for custom XML mapping, it's just a matter of where the XML node resides that the content control is bound to.

Digging into the Details

One thing you'll find if you start playing around with custom XML is that the plumbing required to bind your custom XML nodes to the content controls is a bit complicated. It's a matter of hiding complexity, really: the custom XML mapping in Open XML makes things very simple for developers and users, but when you're creating one of these documents from scratch then you have to deal with the messy details that will be hidden from everyone after the document exists.

If you're a regular visitor to OpenXmlDeveloper.org (and I can't imagine why you wouldn't be!), you may recall an article that Wouter van Vugt wrote on Mapping Content Controls to Custom XML Parts using Notepad . This explained the details of binding your custom XML nodes to content controls, and Wouter used Notepad to lead the reader through the steps involved. That's a great way to learn these sorts of low-level details, by using a tool that adds no "magic" to the task. After you've set up a content control and custom XML part that way, you'll definitely understand the details involved.

Most developers don't actually work in Notepad, however. :-) So this week, Wouter has followed up his introduction to this topic with a great post entitled WordProcessingML Snippets: Part 6, Custom XML and Content Controls. It covers how to create custom XML parts and bind them to content controls from your own code, and it's the final piece in Wouter's series over on OpenXmlDeveloper.org about working with WordprocessingML. If you're writing code to create documents with content controls, you'll find this post extremely useful. It includes .NET code snippets that you can use to bind any arbitrary custom XML node to a text content control. Nice job once again, Wouter!