Mapping Word 2007 Content Controls to Custom XML Using the XMLMapping Object

Summary: This visual how-to topic shows you how to map content controls to elements in a custom XML part that is attached to a document by using the Developer tab in the Office Fluent Ribbon and the XMLMapping object.

Applies to: 2007 Microsoft Office System, Microsoft Office Word 2007

Erika Ehrli, Microsoft Corporation

June 2007

Microsoft Office Word 2007 enables you to create document templates and use content controls and XML mapping to bind to custom XML data. XML mapping is a feature of Office Word 2007 that enables you to create links between documents and XML files. This creates true data/view separation between the document formatting and custom XML data. This visual how-to topic shows you how to map content controls to elements in a custom XML part that is attached to a document by using the Developer tab in the Office Fluent Ribbon and the XMLMapping object. In this walkthrough, you map content controls to a sample custom XML file. To demonstrate this, you first build a document template with content controls. The document displays the following information: Company Name Contact Name Contact Title Phone Number Finally, you create a valid custom XML file, save it to your hard disk drive, add the custom XML file to the document’s data store, and add code to map the content controls to the data store using the XMLMapping object. The following steps allow you to bind a content control to a node in the document's data store. To create content controls by using the Developer tab on the Office Fluent Ribbon Start Office Word 2007. Display the Developer tab in the Ribbon. Note To display the Developer tab in the Ribbon, click the Microsoft Office Button, and then click Word Options. On the Popular tab, select the Show Developer tab in the Ribbon check box and click OK. In Word 2007, open a new document. Using the Developer tab, add four plain-text content controls in the following order: Company Name Contact Name Contact Title Phone Number Save the document as c:\CustomerLetter.docx. After you finish these steps, you are ready to map the content controls to custom XML by using XML Mapping. This sample code demonstrates how to attach an XML file to a document, so that it becomes an available data store item. To set XML mapping on content controls Create a text file and save it as C:\CustomerData.xml. Copy the following into the text file and save it. <?xml version="1.0"?> <Customer> <CompanyName>Alfreds Futterkiste</CompanyName> <ContactName>Maria Anders</ContactName> <ContactTitle>Sales Representative</ContactTitle> <Phone>030-0074321</Phone> </Customer> To load a custom XML part, you must first add a new data store to a Document object by using the CustomXMLParts.Add method of the CustomXMLParts collection. This appends a new, empty data store to the document. Because it is empty, you cannot use it yet. Next, you load a custom XML part from an XML file into the data store, by calling the CustomXMLPart.Load method of the CustomXMLPart object, using a valid path to an XML file as the parameter. Open the Microsoft Visual Basic editor and run the following Visual Basic for Applications (VBA) code to add a data store to your template document. ' Load CustomerData.xml file ActiveDocument.CustomXMLParts.Add ActiveDocument.CustomXMLParts(4).Load ("c:\CustomerData.xml") Next, you want to set an XML mapping on a content control that refers to a node in the added data store. To create an XML mapping, use an XPath expression to the node in the custom XML data part to which you want to map a content control. After you add a data store that points to a valid XML file to your document, you are ready to map one of its nodes to a content control. To do this, pass a string containing a valid XPath to a ContentControl object by using the SetMapping method of the XMLMapping object (by using the XMLMapping property of the ContentControl object). Open the Visual Basic editor and run the following VBA code to bind content controls to items in the data store. Dim strXPath1 As String strXPath1 = "/Customer/CompanyName" ActiveDocument.ContentControls(1).XMLMapping.SetMapping strXPath1 Dim strXPath2 As String strXPath2 = "/Customer/ContactName" ActiveDocument.ContentControls(2).XMLMapping.SetMapping strXPath2 Dim strXPath3 As String strXPath3 = "/Customer/ContactTitle" ActiveDocument.ContentControls(3).XMLMapping.SetMapping strXPath3 Dim strXPath4 As String strXPath4 = "/Customer/Phone" ActiveDocument.ContentControls(4).XMLMapping.SetMapping strXPath4 This code creates the mapping required to connect a custom XML file to content controls in a Word 2007 document template, as shown in Figure 1. Figure 1. Content controls linked to custom XML by using XML mapping   Office Word 2007 enhances the way documents work with custom XML, allowing simple mapping of data to content controls. Word 2007 separates XML data from the presentation of the document so that it is easier to modify both data and formatting programmatically. This new functionality increases the speed with which a template designer creates documents. Not only that, but the templates are more user-friendly and robust. You can load content controls with a wealth of information by mapping to custom XML data. Content controls are predefined pieces of content. There are several types of content controls, including text blocks, drop-down menus, combo boxes, calendar controls, and pictures. You can map these content controls to an element in an XML file. By using XPath expressions, you can programmatically map content in an XML file to a content control. This enables you to write a simple and short application to manipulate and modify data in a document. XML mapping is a property on a content control that links the content of the content control to an XML element in a data store that is stored with the document. With the new Office Open XML Formats, parts of an Office document are contained in individual XML files inside a compressed XML document. Inside the compressed document, in their own specific directories, are XML files that contain data mapped to content controls. Because of this file format change, XML mapping works on XML data that is separate from the document content. This separation of data from formatting enables you to create more robust documents than you could with Microsoft Office Word 2003. If the XML data is damaged, the document itself is untouched. In addition, any changes you make to the document formatting do not affect the structure of the XML data. This is a significant improvement over Word 2003, where you could accidentally invalidate a schema simply by moving text around in the document. The 2007 release of the Microsoft Office system associates every XML mapping with unique XML within the XML data store for the document. The data store in a document in the Office Word 2007 object model is contained in the CustomXMLParts property of the Document object. The CustomXMLParts property returns a CustomXMLParts collection that contains CustomXMLParts objects. It points to all the custom XML parts that are stored in a document. A CustomXMLParts object represents a single custom XML part in the data store. You can programmatically map content controls to elements in a custom XML part attached to a document by using the XMLMapping object. You can also map content controls to elements in a custom XML part using the Office Open XML Formats. You can manipulate the Word XML Format using two different approaches: Programmatically by using the [System.IO.Packaging] class to manipulate the document package and create custom XML parts and the corresponding relationships. Manually updating relationships and adding the custom xml parts to a document package. Note Office Word 2007 has no user interface (UI) to map controls to XML with one exception—SharePoint and Built-in properties listed in the Quick Parts | Linked Properties menu. You can also download the Word 2007 Content Control Toolkit. This tool provides the ability to map content controls to custom XML nodes through a simple drag-and-drop UI.

Watch the Video Video Length: 00:04:22 File Size: 3.69 MB WMV Word Developer Portal Office Developer Center on MSDN Creating Word 2007 Templates Programmatically The Microsoft Office Word Team's Blog: Content Controls XML Mapping Object Custom XML with Office Open XML Documents Word 2007 Content Control Toolkit