Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0)

Applies to: 2007 Microsoft Office System, Microsoft Office Word 2007, Microsoft Visual Studio Tools for the Microsoft Office System (3.0), Microsoft Visual Studio 2008

Steve Hansen, Office Zealot

December 2007

Microsoft Office Word 2007 introduced a new type of control called a content control. Content controls are containers that you can place in a document for containing specific types of content such as dates, lists, pictures, or text. Content controls allow you to create structured blocks of content. You can also bind content controls to custom XML contained within a document. Finally, content controls are capable of firing several events that you can use to provide custom functionality. Microsoft Visual Studio Tools for the Microsoft Office System (3.0), part of Microsoft Visual Studio 2008, embraces content controls and provides an efficient way for adding content controls to a document and binding content controls to data. This visual how-to article demonstrates how to use content controls in a Visual Studio Tools for the Office system project to build a product brochure using Office Word 2007. The data for the brochure comes from a back-end database and content controls surface product data from the database to appropriate locations in the brochure. One of the best attributes of a content control is the ability to lock a control's contents and to lock the content control itself. This ability allows you to create structure in a document where the structure is needed, without the need to lock the entire document. When locking data-bound content controls however, make sure to wrap any data navigation or update events with the appropriate code to temporarily unlock the locked content controls and then relock the content controls after the update occurs. For example, in the accompanying video, there is a Warranty content control that contains the details related to a bike's warranty. This content control is locked so that the contents of the control cannot be changed. As you navigate through the data, however, the content control must be unlocked before moving to the next or previous record in the binding source. The MoveNext and MovePrevious procedures, shown in the following code examples, are called from button-click event handlers associated with buttons on the Microsoft Office Fluent Ribbon. public void MoveNext() { this.ptccWarranty.LockContents = False; this.SalesSummaryBindingSource.MoveNext(); this.ptccWarranty.LockContents = True; AdjustDatabar() } public void MovePrevious() { this.ptccWarranty.LockContents = False; this.SalesSummaryBindingSource.MoveNext(); this.ptccWarranty.LockContents = True; AdjustDatabar(); } Public Sub MoveNext() Me.ptccWarranty.LockContents = False Me.SalesSummaryBindingSource.MoveNext() Me.ptccWarranty.LockContents = True AdjustDatabar() End Sub Public Sub MovePrevious() Me.ptccWarranty.LockContents = False Me.SalesSummaryBindingSource.MovePrevious() Me.ptccWarranty.LockContents = True AdjustDatabar() End Sub Content controls also expose numerous events that you can use to modify their behavior. For example, you could use the Entering event to provide a mechanism that allows an end-user to unlock a locked control. For example in the video, while the content of the Warranty content control is locked initially, the Entering event handler provides an opportunity to unlock the warranty content control so that its contents can be edited. private void ptccWarranty_Entering( object sender, Word.ContentControlEnteringEventArgs e) { System.Windows.Forms.DialogResult response; response = MessageBox.Show("Some dealers offer extended " + "warranties and additional coverage. " + "Do you want to edit this warranty period?", "Edit Warranty?", MessageBoxButtons.YesNo, MessageBoxIcon.Question, MessageBoxDefaultButton.Button2, MessageBoxOptions.DefaultDesktopOnly, false); if ( response == DialogResult.Yes) ptccWarranty.LockContents = false; } Private Sub ptccWarranty_Entering( _ ByVal sender As System.Object, _ ByVal e As Microsoft.Office.Tools. _ Word.ContentControlEnteringEventArgs) _ Handles ptccWarranty.Entering Dim response As System.Windows.Forms.DialogResult response = MessageBox.Show("Some dealers offer extended " & _ "warranties and additional coverage. " & _ "Do you want to edit this warranty period?", _ "Edit Warranty?", MessageBoxButtons.YesNo, _ MessageBoxIcon.Question, MessageBoxDefaultButton.Button2, _ MessageBoxOptions.DefaultDesktopOnly, False) If response = DialogResult.Yes Then ptccWarranty.LockContents = False End If End Sub Content controls add structure to a document. You can have as little or as much structure as you need. Your need for structure can vary from little to no structure (you need only one or two content controls) to highly structured (nearly the entire document is composed of content controls, groups of content controls, or nested content controls). The best way to think about content controls is as containers for types of content within a document. You can easily envision and remember the types of things you can do with containers. Like most containers, content controls offer properties typical of objects meant to contain other objects. For example, content controls expose the following types of properties: LockContents. Gets or sets whether the contents of the control can be modified. The Warranty content control in the example has this property set to True. LockContentControls. Gets or sets whether the control can be deleted from the document. Name. Gets or sets the name for the control. Tag. Gets or sets metadata about the contents of the control. Title. Gets or sets the title of the control. Additionally, content controls raise events that allow you to respond to actions that affect a container. Content control events include: Added. Occurs after you add a control to the document. BindingContextChanged. Occurs when the value of the BindingContext property changes. ContentUpdating. Occurs in a control that is bound to a custom XML part after data in the custom XML part changes and before the control updates. Deleting. Occurs just before the control is deleted from the document. Entering. Occurs when the user clicks in the control, or when the cursor is moved into the control programmatically. The Warranty content control in the video has an event handler associated with this event. Exiting. Occurs when the user clicks outside the control, or when the cursor is moved outside the control programmatically. StoreUpdating. Occurs in a control that is bound to a custom XML part after text in the control changes, and before the custom XML part updates. Validated. Occurs after the control successfully validates. Validating. Occurs while the control is validating. Creating Content Controls You can add content controls to a document in several ways. If you intend to bind content controls to a data source that you defined in your project, you can create content controls by dragging a field from the Data Sources window onto the document surface. By default, text-based fields (such as nvarchar(n)) become plain text content controls. This is the technique used in the accompanying video. Another way to create a content control from within a project in Visual Studio Tools for the Office system is to use the controls found in the Toolbox under Word controls. To open the Toolbox, press CTRL+W+X. In this way, you can drag a content control onto the document surface and then use the Properties window to change the properties you want or create event handlers. Of course, you can also create content controls in Office Word. If you are starting your project based on an existing document that contains content controls, Visual Studio Tools for the Office system (3.0) recognizes the existing content controls and allows you to modify their properties in the Properties window. Finally, you can also dynamically create content controls at run time. Conclusion By using Visual Studio Tools for the Office system, you can take advantage of the benefits offered by content controls in Office Word 2007. These benefits include document protection, document structuring, drag-and-drop content control creation, drag-and-drop content control creation with data binding, an improved event model, and rich data binding including using relational data sources and custom XML parts.

Watch the Video Video Length: 00:09:51 File Size: 11.9 MB WMV Word Developer Portal Office Developer Center Building Word 2007 Document Templates Using Content Controls New VSTO Features Help You Customize Word and Outlook