There are typically three ways to add host controls to a document at design time. The first is to add the control as if you were adding the native object through Word's menus. For example, to add a Bookmark control, you click the Insert menu and select Bookmark. In the Bookmark's dialog box, you then type the name of the bookmark in the Bookmark Name box and click Add, as shown in Figure 6.3. VSTO automatically creates the bookmark as a VSTO control, complete with data binding capabilities and events that you can program against.
DOrt by: '"* Name C Location V Hidden bookmarks
| Add K | k
Figure 6.3. Adding a bookmark to a document using the Insert menu
Figure 6.3. Adding a bookmark to a document using the Insert menu
You can also add a Bookmark control to the document by using Visual Studio's Toolbox. When you drag the Bookmark control to the document, a dialog box gives you the opportunity to select the text you want to bookmark. Then you click OK to insert the bookmark at that location, as shown in Figure 6.4.
When you drag bookmarks from the Toolbox, VSTO automatically names them for you. The name is "Bookmark," with an incremental number appended. For example, the first bookmark you add is named Bookmarkl, the second is Bookmark2, and so on. You can change the name of the bookmark in the Properties window after it has been added to the document.
The fact that the Bookmark control is available in the Properties window in Visual Studio is another indication that this VSTO control is a first-class .NET object that you can access directly in code. In the Properties window, you have access to some of the properties, and all the events, of the bookmark. Figure 6.5 shows the events available on a Bookmark control named Bookmark1. To view the events in Visual Studio, select the bookmark either in the document or in the drop-down box in the Properties window, and then click the Events button.
Figure 6.5. Available properties of a bookmark
You can also add a data-bound Bookmark control to the document using the Data Sources window. By default, the Bookmark control is available for each field of the table listed in the Data Sources window when the Word document has focus. You select the field in the Data Sources window and drag it to the document, as shown in Figure 6.6. Data binding to controls is described in more detail later in this chapter.
For Word solutions, only the Bookmark control is available on the Toolbox and the Data Sources window. If you want to add an XMLNode or XMLNodes control, you must first attach a schema to the document and then drag the schema elements from the XML Structure task pane to the document. For an example of XML mapping, see Chapter 5.
When you map the XMLNodes control to your document, VSTO automatically creates a host item for each object. Whether the object is added as an XMLNode control or as an XMLNodes control is determined by whether the added element is a repeating schema element (where the
maximum number of occurrences is defined as greater than 1). Repeating schema elements are added as XMLNodes controls. Nonrepeating schema elements are added as XMLNode controls.
In this section you'll create a simple schema and then map it to a Word document.
1. Type the XML in Listing 6.7 into a text file, and name it Sample.xsd. You could also use the XML editor in Visual Studio to create your schema.
Listing 6.7. Sample schema
<?xml version="1.0" encoding="utf-8" ?> <xs:schema targetNamespace="http://schemas.samples" elementFormDefault="qualified" xmlns="http://schemas.samples" xmlns:mstns="http://schemas.samples" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="Sample" type="SampleType"></xs:element> <xs:complexType name="SampleType"> <xs:all>
<xs:element name="Name" type="NameType" minOccurs="0"
maxOccurs="1" /> <xs:element name="Address" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:all> </xs:complexType> <xs:complexType name="NameType"> <xs:sequence>
<xs:element name="FirstName" type="xs:string" minOccurs="1"
maxOccurs="1"/> <xs:element name="LastName" type="xs:string" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:schema>
2. On the Tools menu in Visual Studio, point to Microsoft Office Word Tools, and click Templates and Add-ins. If you do not see this menu option, make sure that the document is open in design mode and that the document has focus. Then try to click the menu item again.
3. In the XML Schema tab of the Templates and Add-ins dialog box, click Add Schema.
4. Select the Sample.xsd file that you saved in step 1, type the word Sample in the Alias text box, and click OK.
5. In the XML Structure task pane, click Sample to add the sample XMLNode to the document. (Select Apply to Entire Document if requested.)
6. Click inside the Sample node on the document, and then click Name on the XML Structure task pane.
7. Add the text First Name: to the document, and then map the FirstName element to the right of the text.
8. Add the text Last Name: to the document, and then map the LastName element to the right of the text.
If you click inside the FirstName node on the document and then look at the Properties window in Visual Studio, you will see that an XMLNode control has been created with the name NameFirstNameNode. VSTO automatically names each XMLNode that you add to the document by adding the child name to the parent name and appending the word Node. For example, if you click inside the Name node on the document, you'll see that the control's name is SampleNameNode. See the Properties window in Figure 6.7 for an example.
You can continue mapping XMLNode controls to the document so that you also have an Address node within the Sample node. You can uncheck the Show XML Tags in the Document check box to hide the actual nodes in the document. You can also set various options by clicking the XML Options link at the bottom of the XML Structure task pane. For example, you can check the Ignore Mixed Content check box so that you can mix text and XMLNode controls in the document, or you can uncheck the Hide Schema Violations in This Document option to turn off schema validation.
To see how you can write code to respond to an event of the XMLNode, click inside the FirstName node and type your first name. If you doubleclick the text you just typed, it will take you to the Select event handler of the XMLNode in code view. Add code to display a message box:
MsgBox("Hello " & Me.NameFirstNameNode.Text)
Press F5 to run the code. When you click the document in the area where your name appears, a message box is displayed.
Was this article helpful?