How to: Bind a Content Control to a Node in the Data Store
|Word Developer Reference|
XML mapping is a feature of Microsoft Office Word 2007 that enables you to create a link between a document and an XML file. This creates true data/view separation between the document formatting and the custom XML data.
XML mapping enables you to map an element in a custom XML part that is attached to the document. The data store provides access to all of the custom XML parts that are stored in an open file. You can refer to any node within any custom XML part inside the data store.
For more information about content controls, see Working with Content Controls.
The objects used in this sample are:
- CustomXMLPart (2007 Microsoft Office system core object model)
- CustomXMLParts (2007 Microsoft Office system core object model)
The following steps enable you to bind a content control to a node in the document's data store.
Create the content control to bind to a node in the data store.
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 XML Path Language (XPath), 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. For more information about content controls, see Working with Content Controls.
The following code sample creates a plain-text content control and gives it a title of "MyTitle".
Dim strTitle As String
strTitle = "MyTitle"
Dim oContentControl As Word.ContentControl
Set oContentControl = ActiveDocument.ContentControls.Add(wdContentControlText)
oContentControl.Title = strTitle
Set the XML mapping on the content control.
The data store in a document in the Word 2007 object model is contained in the CustomXMLParts property of the Document object. The CustomXMLParts property returns a CustomXMLParts collection that contains CustomXMLPart objects. It points to all the custom XML parts that are stored in a document. A CustomXMLPart object represents a single custom XML part in the data store.
To load custom XML data, you must first add a new custom XML part to a Document object by using the Add method of the CustomXMLParts collection. This appends a new, empty custom XML part to the document. Because it is empty, there is no XML to map to. Next, you must load XML into the newly defined part by calling the Load method of the CustomXMLPart object, using a valid path to an XML file as the parameter, or by calling the LoadXML method of the CustomXMLPart and passing the XML directly.
The default custom XML parts stored with a Word document contain the document's standard document properties; you cannot delete these parts. You can always view the contents of a custom XML part by calling the read-only XML property on it. If you call the XML property of a CustomXMLPart object, a string is returned, which contains the XML in that data store.
Steps to Set an XML Mapping on a Content Control
Build a valid custom XML file and save it to your hard disk drive. Add a custom XML part to the document that contains the content control you want to map to custom XML data.
Suppose the content control will be mapped to the following sample custom XML file.
Now, suppose the content control is mapped to a \
<?xml version="1.0" encoding="utf-8" ?>
If you omit the optional PrefixMappings and CustomXMLPart arguments, Word searches each of the custom XML parts in order and maps the control to the first part that successfully retrieves a custom XML node using the specified XPath.