Using XML Mapping as Part of a Document Generation Solution in Word 2010
Summary: Learn how to use content controls and XML mapping as part of a document generation scenario. This article is a revision of the article published with the How To video, Mapping Word 2007 Content Controls to Custom XML Using the XMLMapping Object.
Applies to: Office 2007 | Office 2010 | Open XML | Visual Studio Tools for Microsoft Office | Word 2007 | Word 2010
In this article
Understanding Content Controls and XML Mapping
Document Generation Scenario
Mapping XML Nodes to Content Controls
Conclusion
Additional Resources
Published: February 2011
Provided by: Microsoft Corporation
Contents
Understanding Content Controls and XML Mapping
Office Word 2007 and Word 2010 enhance the way documents work with custom XML, which allows simple mapping of external data to content controls. You can load content controls with a wealth of information by using XML mapping to map them to custom XML data.
Content controls are predefined pieces of content. There are several kinds of content controls. These include text blocks, drop-down menus, combo boxes, calendar controls, check boxes, 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 or binds the content of the content control to an XML element in a data store that is stored with the document. In the 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.
By using XML mapping, XML data is separated from the presentation of the document so that it is easier to modify both data and formatting programmatically. This separation of data from formatting enables you to create more robust documents than you could with previous versions of Word. If the XML data is damaged, the document itself is untouched.
Document Generation Scenario
In a document generation solution, documents are generated programmatically and populated with business data. One approach that you can use to implement a document generation solution involves using content controls and XML mapping to custom XML.
In this approach, an initial document is created that acts as a template for document generation. Content controls in the template document are bound to custom XML. New documents are then programmatically generated as copies of the template document. The content controls in the new documents keep the XML mapping created in the template document. A unique custom XML part data store is added to each new document. When the new document is opened, the placeholder content controls in the document are populated with business data from the attached custom XML part.
Mapping XML Nodes to Content Controls
This walkthrough shows how to bind content controls to elements in a custom XML part that is attached to a document by using the XMLMapping object. To do so, you must complete the following steps:
Creating the Template Document
The template document that you create in this walkthrough contains four content controls that display information about a customer contact.
To add content controls by using the Developer tab on the Office Fluent ribbon
Start Microsoft Word 2010.
Display the Developer tab in the ribbon.
Note
To display the Developer tab in the ribbon, click File, click Options, and then click Customize Ribbon. Under Customize the Ribbon, verify that Main Tabs is selected in the drop-down. Under Main Tabs, select Developer, and then click OK.
In Word 2010, open a new document.
Using the Developer tab, add and title four plain-text content controls to the document surface in the following order:
Company Name
Contact Name
Contact Title
Phone Number
Save the document as c:\CustomerLetter.docx.
Creating the Custom XML File
With the template document created, you create the custom XML file that contains the XML that you then bind to the content controls in the template document.
To create the custom XML file
Open a new text file for editing.
Copy the following into the text file and save it as C:\CustomerData.xml.
<?xml version="1.0"?> <Customer> <CompanyName>Adventure Works</CompanyName> <ContactName>Terry Adams</ContactName> <ContactTitle>Sales Representative</ContactTitle> <Phone>030-0074321</Phone> </Customer>
To map the content controls to custom XML by using the Word XML Mapping feature, a custom XML part must be added to the document, and the XML file must be loaded into the custom XML Part.
Mapping Content Controls to Nodes in the Custom XML File
To bind a content control to a node in a custom XML file, the custom XML file must be attached to the Word document. You attach custom XML files to a Word document by adding a custom XML part data store to the document and then loading the custom XML file into the custom XML part.
Note
For more information about the data store, see Walkthrough: Word 2007 XML Format.
To add a new custom XML part, use the CustomXMLParts.Add method of the CustomXMLParts collection. This appends a new, empty custom XML part to the document. Because it is empty, you cannot use it yet. Next, you load XML from an XML file into the custom XML part, by calling the CustomXMLPart.Load method of the CustomXMLPart object that uses a path of an XML file as the parameter. The following steps show how to bind a content control to a node in the document's data store.
To add a custom XML part to the document
Open the Microsoft Visual Basic editor and run the following VBA code to add a data store to your template document.
' Add a new, empty custom XML part to the document.
ActiveDocument.CustomXMLParts.Add
' Load XML from CustomerData.xml file.
ActiveDocument.CustomXMLParts(4).Load ("c:\CustomerData.xml")
Next, set XML mapping on a content control that refers to a node in the added custom XML part data store. To create an XML mapping, use an XPath expression to the node in the custom XML part to which you want to map a content control. After you add a custom XML part and load a valid XML file into it, you are ready to map one of its nodes to a content control.
To do this, pass a string that contains 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).
To map a node in the custom XML part to a content control
In the Visual Basic editor, after the code entered in the last procedure, add 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 or Word 2010 document. When the document is opened, the bound content controls are populated with data from the attached custom XML part.
Conclusion
The Microsoft Office 2007 system and Office 2010 associate every XML mapping with unique XML within the XML data store for the document. The data store in a Word 2007 or Word 2010 document 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 approaches:
Programmatically by using the Open XML SDK 2.0 for Microsoft Office SDK [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
Microsoft Word has no user interface 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.