Binding Data to Content Controls


The ability to bind external data to Content Controls in a Word document means that you can use XML to populate parts of a document with information that’s stored in other sources. For example, use data binding to automatically populate the user’s contact information in a typical business document or to populate fields in a boilerplate contract form. You can use any data source for this purpose that can be translated by XML-from data stored directly in the custom XML in the document’s ZIP package, to data in a Microsoft Exchange Server directory or a Microsoft Windows SharePoint Services list.

In this section, we’ll look at the required elements of a bound control and then I’ll walk you through the process of binding Content Controls to a custom XML document part.

Note 

Keep in mind that binding data is a two-way street. That is, when you have a Content Control bound to custom XML data, content added to that control in the document is added to your custom XML. One of the nicest benefits of this is that, for example, if you have the client’s name as custom XML bound to several controls in your document, you can change the name in any one of those bound controls and all controls bound to the same data will automatically update.

For a simple example of this, insert a couple of instances of the same Document Property Quick Part into your document and then edit the value in one of them. Then, for further examination, open the ZIP package for that document and check out its document.xml file to view the data binding code for those Quick Parts.

The Components of a Bound Content Control

There are a few more elements to data binding than you’ve encountered for previous tasks covered in this chapter. However, most of the components required here are similar to those you’ve already used, as follows.

  • A folder stored in the root of the ZIP package, named customXML.

  • Three elements inside the customXML folder, including the following.

    • One or more files containing the custom XML data (that is, the data to be bound to controls in the document). In the exercise that follows, this file is named item1.xml.

    • A file that defines the properties used (specifically, the referenced namespaces) for each custom XML file. In the exercise that follows, this file is named itemProps1.xml.

    • A _rels folder in which you’ll create a relationship file for the custom XML. That relationship file in the following exercise is named item1.xml.rels.

  • One Content Control in document.xml for each piece of custom XML data that you want to bind to a control.

  • A relationship in the file document.xml.rels for the bound custom XML data.

image from book The section that follows walks you through the process of binding two Content Controls to custom XML stored in the document’s ZIP package. For working through the exercises that follow, you can use the file named image from book Data Binding.docx, located in the sample files that are included on this book’s CD. If you prefer to create your own file, you can base it on image from book Data Binding.docx, which is simply a Word document containing two lines of text and two plain text Content Controls.

Caution 

When binding data to Content Controls, use only plain text types of Content Controls, such as the Text, Drop-Down list, or Date Picker controls. Data binding doesn’t support rich text content, such as tables and graphics, so attempting to bind data to a control that supports rich text leaves your document open to possible errors. (Remember that plain text controls do allow font and paragraph formatting, so you don’t have to lose any formatting customization in the document when you want to bind controls to custom XML data.)

Binding a Control to Custom XML

To begin, save the file image from book Data Binding.docx (mentioned on the preceding page), or your own comparable file, to the Windows desktop and change the file extension to .zip. Then, follow the steps under each of the subheadings that follow.

Create the Custom XML Files

  1. On your Windows desktop, create a folder named exactly customXML. Then, inside that folder, create another folder named exactly _rels.

  2. In Notepad, create a new file and save it in the root of your new customXML folder, as item1.xml Add the following code to this new file and then save and close the file.

     <?xml version="1.0" encoding="UTF-8" standalone="yes"?><myinfo xmlns="http:// www.arouet.net/AMOD/CustomXML.htm"><email>My e-mail address</email><motto>Add a favorite saying here.</motto></myinfo>

    For ease of reference, here’s the way the preceding code looks in Internet Explorer.

       <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> - <myinfo xmlns="http://www.arouet.net/AMOD/CustomXML.htm">     <email>My e-mail address</email>     <motto>Add a favorite saying here.</rnotto>   </myinfo>

    Notice what’s included in the preceding code. After defining the XML version, you identify a namespace for the set of fields you want to use as your custom XML items. The set of items in this sample is referred to as myinfo. The two fields included, which you’ll map to Content Controls in this exercise, are emai1 and motto. If you choose to do so, you can replace the placeholder text between the paired code with your own text for each of these fields.

  3. In Notepad, create a new file and save it in the root of your new customXML folder, as itemProps1.xml. Add the following code to this new file and then save and close the file.

     <?xml version="1.0" encoding="UTF-8" standalone="no"?>

     <ds:datastoreItem ds:item xmlns: ds="http://schemas.openxmlformats.org/officedocument/2006/2/customXml"xds: schemaRefs><ds: schema Ref ="http://www. arouet. net/AMOD/CustomXML. htm"/></ds: schemaRef s></ds: datastoreItem>

    For ease of reference, the following is the same code viewed in Internet Explorer.

       <?xml version="1.0" encoding="UTF-8" standalone="no" ?> - <ds:datastoreItem ds:itembold">{462820BB-4D2B-41C2–812E-F3CA7850A5A9}"     xmlns:ds="http://schemas.openxmlformats.org/officedocument/2006/2/customXml">   - <ds:schemaRefs>       <ds:schema Ref= "http://www.arouet.net/AMOD/CustomXML.htm" />     </ds:schemaRefs>   </ds: datastoreItem>

    This code in this file provides information about the namespace used in the file where you store the custom XML items. Note that the data store item ID is used to identify the custom XML where you bind the data to controls in document.xml The datastoreItem ID shown in the preceding code is what’s referred to as a GUID (globally unique identifier). GUIDs are used in many places in programming to provide unique identification for a particular item being referenced in the code. For example, if you’ve ever explored the Windows registry, you’ve probably seen many GUIDs.

    Note 

    Many professional development platforms, such as Visual Studio, provide tools for generating GUIDs. You can also find free tools on the Web for generating GUIDs. However, it takes just a fairly simple macro in VBA to get this done as well.

    image from book So, to save you some time when you need to generate your own GUIDs, I created a file named image from book Generate GUID.docm, that you can find in the sample files included on this book’s CD. When you open this file, enable macros and then click the single button available on the Ribbon.

    As mentioned in the Inside Out tip on page 1178 about the startFromScratchUI customization command, you can also check out image from book Generate GUID.docm to see an example of a startFromScratch Ribbon. The only tab available in that file is the one containing the GUID macro button. For those interested in the macro to generate GUIDs, you can also find that in the Visual Basic Editor once you open this file.

  4. Once again, in Notepad, create a new file. This time, save the file into the _rels subfolder in the customXML folder you created, naming it item1.xml.rds. Add the following code to this new file and then save and close the file.

     <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relations hips"><Relationship  Type="http: //schemas.openxml formats.org/officeD ocument/2006/relationships/customXml Props" Target="itemProps1.xml "/></Relation- ships>

    Following, for ease of reference, is a look at this code in structured format, as shown in Internet Explorer.

      <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> -<Relationships>    <Relationship       Type="http://schemas. openxmlformats.org/officeDocument/2006/relationships/customXmlProps"      Target="itemPropsl.xml"/>  </Relationships>

    Notice that this file simply creates a relationship to the custom XML properties file.

  5. Open the ZIP package for the file image from book Data Binding.docx (or your own similar file that you created for this exercise) and copy the entire customXML folder you created in the preceding steps into that ZIP package.

    Once you’ve done this, it’s time to bind that custom XML to controls in your document.

Binding Custom XML to Content Controls

To bind Content Controls to the custom XML you just created, you’ll need to add just one statement in document.xml for each control that you want to bind, as well as one statement in the document.xml.rels file to create a relationship to the custom XML. To begin, copy both of these files out of the ZIP package.

Note 

As you may recall from earlier exercises in this chapter, document.xml is located in the word folder in the ZIP package, and document.xml.rels is located in the _rels folder within the word folder.

Start by adding the data binding statements to document.xml To do this, let’s take a look at what the code looks like for the paragraph containing the first Content Control. That paragraph, including the control, looks like this when opened in Word:

image from book

Following is the way that same paragraph looks in document.xml.

 - <w:p>   - <w:pPr>       <w:pStyle w:val="BodyText" />     </w:pPr>   - <w:r>       <w:t xml:space="preserve">My e-mail address is:</w:t>     </w:r>   - <w:sdt>     - <w:sdtPr>         <w:id w:val="29485172" />       - <w:placeholder>           <w: docPart w: val="DefaultPlaceholder_22610167" />         </w:placeholder>         <w:showingPlcHdr />         <w:text/>       </w:sdtPr>     - <w:sdtContent>       - <w:r>         - <w:rPr>            <w:rStyle w:val="PlaceholderText" />            </w:rPr>            <w:t>Click here to enter text.</w:t>         </w:r>       </w:sdtContent>     </w:sdt>   </w:p> - <w:p>

The code representing the Content Control in this paragraph begins with the line <w:sdt> in the preceding code. The data binding statement needs to be placed two lines beneath that, between <w:stdPr> and <w:id>. Following is the statement to add to document.xml for binding the first control in the document to the emai1 field from the custom XML file.

 <w:dataBinding ng w:prefixMappi ngs="xmlns:ns0='http://www.arouet.net/AMOD/CustomXML. htm'" w:xpath="/ns0:myi nfo[1]/ns0:emai1[1]" w:storeItem />

For ease of reference, take a look at the same statement in Internet Explorer, shown with the immediately surrounding statements referenced earlier.

 - <w:sdtPr>     <w:dataBinding       w:prefixMappings="xmlns :ns0='http://www.arouet .net/ AMOD/CustomXML.htm"       w:xpath="/ns0:myinfo[1]/ns0:email[1]" w:storeItembold">{462820BB-4D2B-41C2       812E-F3CA7850A5A9}" />     <w:id w:val="29485172" />

The w:dataBinding statement includes the following.

  • w:prefixMappings is the namespace identified in item1.xml Notice that this namespace is identified as ns0.

  • w:xpath provides the path inside item1.xml where you can find the particular field being bound. In this case, the emai1 field is within the group of fields named myinfo.

  • w:storeItemID is the same GUID used in the itemProp1.xml file.

This statement will be identical, other than the xpath, for each control in this document that’s mapped to the same data source. In fact, the only difference in the statement that you need to add to map the second control to the motto field is to change the word emai1 to motto in the preceding statement, after you copy and paste that statement to the proper position for the Content Control that appears in the second paragraph.

Once you’ve finished adding these two statements to document.xml, save and close the file in Notepad. At this point, you might want to check the file in Internet Explorer to be sure you’ve added the code correctly. Remember that, if you made a structural error in adding the new XML, the code won’t open in Internet Explorer.

Copy your updated document.xml file back into the ZIP package, overwriting the existing file of the same name. Once you do, the last step is just to add the relationship to the custom XML in document.xml.rels. Open that file in Notepad, and add the following relationship before the </Relationships> code.

 <Relationship  Type="http://schemas.openxmlformats.org/officeDocument/2006/ relationships/customXml" Target="../customXML/item1.xml" /> 

Caution 

As with previous relationship statement samples in this chapter, be sure to replace the pound sign in the preceding statement with a number that is not already used in document.xml.rels.

Save and close the document and then copy it back into the ZIP package, overwriting the existing file of the same name. That’s it! You’ve bound your Content Controls to custom data. Open the file in Word to check out your results.

To try out your bound controls, modify the content inside the controls while the document is open in Word. Then, save and close the file, change the extension back to .zip, and view your changes in the custom XML.

Note 

Want to save yourself the steps of writing out the code to bind your custom XML data to each control in the document? Tristan Davis, the Word 2007 Program Manager who has generously shared his knowledge and insights at the end of Chapter 31, turned me on to a tool that I highly recommend checking out. Matt Scott, a Software Design Engineer in Microsoft Research and former member of the Microsoft Office Word team, created the “Word 2007 Content Control Toolkit,” which is free to download and available through a link you’ll find on the Resources tab of this book’s CD. Using this tool, which runs as a separate program outside of Word, you can simply drag a custom XML field and drop it on the control you want to bind to that data. It’s a very cool timesaver and a good resource as well for helping you to understand how the data is mapped to the controls.

Inside Out-Convert Control Types Between Plain Text and Rich Text 

In the code shown in this section for the first paragraph in the image from book Data binding.docx sample file, notice the <w:text /> code that appears near the middle of the XML that represents the first Content Control. This text code is used to identify the control as a plain text control. If you were to insert a Rich Text control into a document and then view the XML, you’d see that this code (or anything like it) doesn’t appear. In fact, this text code is the thing that separates rich text and plain text controls.

To turn any plain text control into a rich text control, all you need to do is delete the <w:text /> code from the XML representing that control in document.xml. Similarly, if you want to bind data to controls in your document, but you’ve used the Rich Text control type, you can add the <w:text /> code in the same position relative to those controls where they appear in document.xml to turn those controls into plain text controls, rather than spending extra time to replace the controls throughout your document.




2007 Microsoft Office System Inside Out
2007 MicrosoftВ® Office System Inside Out (Bpg-Inside Out)
ISBN: 0735623244
EAN: 2147483647
Year: 2007
Pages: 299

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net