Visual Studio Tools for Office: Using C# with Excel, Word, Outlook, and InfoPath [Electronic resources] نسخه متنی

An End-to-End Scenario: Creating a Schema and Mapping It into a Word Document

This section examines an end-to-end scenario that puts together the schema creation capabilities of Visual Studio and the schema mapping capabilities of Word. When you take a schema and apply it in Word using the XML Structure task pane, you enable the exporting and importing of XML data in the document. We are going to create a Word document that can be used to record a customer's book order. The document will support the import and export of XML that conforms to our book order schema. The document will look like Figure 22-8.

Listing 22-1 shows the XML that this document will be able to import and export.

Listing 22-1. XML File Generated from Book Order Document

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Order xmlns=" http://dotnet4office.com/bookorder.xsd ">
<CustomerName>John Doe</CustomerName>
<Date>2005-09-30</Date>
<Book>
<Title>Windows Forms Programming in C#</Title>
<ISBN>0-321-11620-8</ISBN>
<Publisher>Addison-Wesley</Publisher>
<Price>49.99</Price>
</Book>
<Book>
<Title>Effective C#</Title>
<ISBN>0-321-24566-0</ISBN>
<Publisher>Addison-Wesley</Publisher>
<Price>39.99</Price>
</Book>
<Book>
<Title>The C# Programming Language</Title>
<ISBN>0-321-15491-6</ISBN>
<Publisher>Addison Wesley</Publisher>
<Price>29.99</Price>
</Book>
<Subtotal>119.97</Subtotal>
<Tax>10.80</Tax>
<Total>130.77</Total>
</Order>

Creating the Schema Using Visual Studio

To create our schema using Visual Studio, follow these steps.

Figure 22-9 shows the final schema as displayed by Visual Studio.

Listing 22-2 shows the generated XSD file. Note that the sequence of Book elements in an Order element is a sequence with a minimum (minOccurs) of one Book elements and a maximum (maxOccurs) of unbounded Book elements. This will allow our schema to represent one or more Books in an Order. Also, having a sequence where maxOccurs is greater than one or unbounded will allow Word to know that it can represent the Books in an Order using a Word table.

Listing 22-2. Book Order XSD Schema File

<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://dotnet4office.com/bookorder.xsd" 
 elementFormDefault="qualified" xmlns="http://dotnet4office.com/bookorder.xsd" xmlns
:mstns="http://dotnet4office.com/bookorder.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Order">
<xs:complexType>
<xs:sequence>
<xs:element name="CustomerName" type="xs:string" />
<xs:element name="Date" type="xs:date" />
<xs:element name="Book" maxOccurs="unbounded" minOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="Title" type="xs:string" />
<xs:element name="ISBN" type="xs:string" />
<xs:element name="Publisher" type="xs:string" />
<xs:element name="Price" type="xs:float" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Subtotal" type="xs:float" />
<xs:element name="Tax" type="xs:float" />
<xs:element name="Total" type="xs:float" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

An additional point to notice about our schema file is that it is element-centricwe use XML elements and do not use XML attributes at all in our schema. Although Word supports the mapping of XML attributes, it does so in a way that makes it difficult for the end user to edit the attributes. The user must show the XML tags in the document, right-click an XML tag, and use the Attributes dialog shown in Figure 22-10 to edit attributes. In this example, we have mapped a book order schema where Title, ISBN, and Publisher are attributes rather than elements. These attributes will not show directly in the document, so it is usually best to avoid having attributes in schemas you are going to use with Word and instead use only elements.

Adding a Schema to the Word Document

Now that we have created a schema, let's add it to a Word document. Launch Word and create a new empty document. Bring up the Word XML Structure task pane as described in the first section of this chapter. You should now see the XML Structure task pane with no schema as yet associated with the document in the task pane. To add an XML schema to the document, click the Templates and Add-Ins hyperlink in the XML Structure task pane. Then, as shown in the first part of this chapter, click the Add Schema button shown in Figure 22-3 to add your book order schema to the document. Give your schema the friendly name or alias of BookOrder in the Schema Settings dialog shown in Figure 22-4. Then close the Templates and Add-Ins dialog by clicking the OK button. The XML Structure task pane should now look like Figure 22-7.

The XML Options Dialog and Mixed Content

Before we start to construct the document shown in Figure 22-8, we need to briefly consider one additional dialogthe XML Options dialog. In the XML Structure task pane, there is a hyperlink at the bottom of the pane with the text XML Options. Click this hyperlink to bring up the XML Options dialog. Alternatively, you can click the XML Options button in the Templates and Add-Ins dialog. Figure 22-11 shows the XML Options dialog.

For the purpose of this end-to-end scenario, we need to make sure that the check box next to Ignore mixed content is checked. By checking this check box, it will allow us to intersperse text that is not part of our customer order schema with text that is. Mixed content allows us to have a structure similar to that shown in Listing 22-3, where arbitrary text (in bold) is mixed with the tagged XML data text.

Listing 22-3. Book Order XML with Mixed Content in Bold

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Order xmlns=" http://dotnet4office.com/bookorder.xsd ">
Customer Name:  <CustomerName>John Doe</CustomerName>
Date:  <Date>2005-09-30</Date>
Books that were ordered: 
<Book>
<Title>Windows Forms Programming in C#</Title>
<ISBN>0-321-11620-8</ISBN>
<Publisher>Addison-Wesley</Publisher>
<Price>49.99</Price>
</Book>
<Book>
<Title>Effective C#</Title>
<ISBN>0-321-24566-0</ISBN>
<Publisher>Addison-Wesley</Publisher>
<Price>39.99</Price>
</Book>
<Book>
<Title>The C# Programming Language</Title>
<ISBN>0-321-15491-6</ISBN>
<Publisher>Addison Wesley</Publisher>
<Price>29.99</Price>
</Book>
Subtotal:  <Subtotal>119.97</Subtotal>
Tax:  <Tax>10.80</Tax>
Total:  <Total>130.77</Total>
</Order>

Creating a Document with Mapped XML Structure

To begin, let's construct a document with some text in it but no schema mapping. Create a document that looks like the one shown in Figure 22-12. Create a place to put a customer name, date, subtotal, tax, and total. Create a single table with four columns and two rows where we will put a book with a title, ISBN, publisher, and price.

Now we can begin mapping our schema by inserting tags into the document. The experience of mapping schema into a Word document is quite different from mapping a schema into an Excel document. If you have ever edited a201 page in a text editor, you will find that mapping a schema into a Word document feels somewhat similar to the way HTML tags are used to mark up text in a201 page.

Make the XML Structure task pane visible and verify that the Show XML tags in the document check box is checked in the task pane. This will allow you to see the XML tags that Word is inserting into the document. Click anywhere in the Word document. Then in the bottom half of the XML structure task pane you will see an element list that is identified with the text "Choose an element to apply to your current selection." In that list is only one element, Order. Order is the root element of our schema, so it must be mapped first. Click Order in the element list. The dialog shown in Figure 22-13 will appear. For this example, we will choose Apply to Entire Document. It is possible to map multiple schemas into one document, but it is not possible to export valid XML from such a document. VSTO also does not support the mapping of multiple schemas into one document, so we will avoid constructing such a document.

After you click the Apply to Entire Document button, the Word document now looks like Figure 22-14. You can see that an Order tag has been applied to the entire document. This will give you an idea of where we are goingwe are effectively going to make the Word document look something like Listing 22-3.

The Order element has six child elements: CustomerName, Date, Book (which is a repeating element), Subtotal, Tax, and Total. Let's map these elements now. Select the text John Doe in the document. From the XML Structure pane, click CustomerName in the element list, as shown in Figure 22-15. If CustomerName does not appear in the element list along with the other child elements of Order, toggle the List only child elements of the current element check box until it appears.

Select the text 2005-09-30 and click the Date element in the element list. Select the text 29.99 and click the Subtotal element in the element list. Select the text 1.00 and click the Tax element in the element list. Select the text 30.99 and click the Total element in the element list. If you make a mistake and tag some text with the wrong element tag, right-click the element tag and choose the Remove tag menu option.

Figure 22-16 shows the document with the entire schema mapped except for the Book subelements. Note the pink squiggly line along the side of the document. This is Word's schema validation feature telling us that the mapped document has not yet been constructed in a way that conforms to the book order schema. This is because we have not yet mapped the Book subelements. You can right-click the squiggly line to get the exact error that is occurring that will prevent Word from exporting valid XML from this mapping.

We are going to map our repeating Book element into a table. If we map a Book element into a row of the table, Word will be smart about this and when additional rows are added to the table Word will automatically tag the newly inserted row as a new Book element with all related tags.

First, select the entire row with the book "The C# Programming Language" in it by clicking in the start of the row and dragging across the row. It is important that you do not select beyond the edge of the rowthat you only select the current row, as shown in Figure 22-17.

With the entire row selected, click the Book element in the element list. Figure 22-18 shows the resulting tagged row.

Now we need to tag the column values to mark them with the child elements of the Book element. The Book element has four child elements: Title, ISBN, Publisher, and Price. Once again, if the elements do not appear in the element list, toggle the List only child elements of the current element check box to make the elements appear. Select the text The C# Programming Language and click the Title element in the element list. Select the text 0-321-15491-6 and click the ISBN element in the element list. Select the text Addison Wesley and click the Publisher element in the element list. Finally, select the text 29.99 and click the Price element in the element list. Figure 22-19 shows the resulting tagged row.

Now let's verify that we have set up the table in a way that Word will automatically tag new rows as Book elements. Click somewhere in the table. From the Table menu, choose Insert and then Rows Below. As shown in Figure 22-20, Word automatically adds tags to the new row.

Now, fill out the remainder of the table to make it look like Figure 22-8. After you have filled out the table, you can hide the XML tags by unchecking the Show XML tags in the document check box in the XML structure pane or by pressing the keyboard accelerator Ctrl+Shift+X. Typically, when you deploy a document such as this to end users, you will not want to have the XML tags showing in the document. The only complication this causes is when a tag is emptyit is very hard for the user of your document to type text in the right place. To solve this issue, use the XML Options dialog box and check the Show placeholder text for all empty elements option. Figure 22-21 shows the final document with XML tags showing.

Also, note that the XML structure task pane shows the elements that have been mapped into the document in a tree view, as shown in Figure 22-22. You can right-click the elements in this tree view and a menu appears that allows you to unmap a particular element or edit attributes associated with a particular element.