Building Document Generation Systems from Templates with Word 2010 and Word 2007

Summary:   Some business scenarios require generation of many documents by using a template document and a data source. This article contains guidance for this scenario and links to MSDN articles and blog posts.

Applies to: Office 2007 | Office 2010 | Open XML | Visual Studio Tools for Microsoft Office | Word 2007 | Word 2010

In this article
Building Document Generation Systems from Templates
Replacing Content Controls with Content
Binding Content Controls to XML in Custom XML Parts
Handling Events when Manipulating Content Controls
Conclusion

Published: March 2010

Provided by:Eric White, Microsoft Corporation

Contents

• Building Document Generation Systems from Templates

• Replacing Content Controls with Content

• Binding Content Controls to XML in Custom XML Parts

• Handling Events when Manipulating Content Controls

• Conclusion

Building Document Generation Systems from Templates

Sometimes software systems must automatically generate documents to support various scenarios. The design of the system may include the ability for a subject matter expert to create a template document that drives the generation. The template document must determine specific areas of the document for replacement with automatically-generated content. For example, a placeholder in the document must be replaced with the salutation and name of the addressee of a letter. In addition, the template document may delineate specific sections of the template to remove from the generated document. For example, a template for a legal document may include all possible legal clauses, but based on the specific circumstances, certain legal clauses are omitted in the generated document. The numbering of headings and sections in the resulting document should be automatically adjusted as necessary.

Content controls are ideally suited to this scenario. You can make it easy to insert content controls by including macros to do the insertion. You can automatically set the title and tag of the content control in the macro. Or, you can develop a managed add-in that creates a custom Ribbon with buttons to insert various instances of content controls. You could have buttons that insert content controls with one of a specific set of tags such as Name, Address, Phone, and Legal_Clause.

Sometimes you want to maintain auxiliary information about each content control. You may want to allow the document designer to set a specific set of properties for each one. Content controls do not have a facility such as a special element or attribute in the markup for storing such information. In addition, the Microsoft Word 2010 user interface (UI) and Microsoft Office Word 2007 UI do not allow the document designer to maintain auxiliary information for a content control. However, there is an approach where you can easily allow the document designer to create and configure information associated with each content control. For more information about this process, see Associating Data with Content Controls. This blog entry shows a managed add-in that creates a custom task pane for maintaining this information. This auxiliary information is stored in a custom XML part. The information for each content control is associated by a unique ID that Word automatically generates for each content control. The following figure from this example shows a task pane that allows the content author to set auxiliary information about a content control.

Figure 1. Example of a custom task pane for editing content control auxiliary data

Tip

The blog entry, Associating Data with Content Controls, shows how to create an application-level task pane. Another approach is to create a task pane associated with each document. This may be more appropriate for some scenarios, such as if you have many document types, and you want to maintain different information for content controls in each document type.

When you create a custom task pane in an application that uses multiple windows to display documents and other items, you must take additional steps to ensure that the task pane is visible when the user expects it to be. The article, Managing Custom Task Panes in Multiple Application Windows, explains what you must know about how to make task panes work with multiple document interfaces (MDI). The article, Managing Task Panes in Multiple Word and InfoPath Documents provides more detail and sample code.

Summary of Resources

Title	Description
Creating Custom Task Panes in the 2007 Office System	Introduces custom task panes.
Actions Pane Overview	Provides information about how to create document-level managed add-in projects.
Managing Custom Task Panes in Multiple Application Windows	Explains what you must know about how to make task panes work with multiple document interfaces (MDI).
Managing Task Panes in Multiple Word and InfoPath Documents	Provides detail about how to make managed add-ins that work correctly in an MDI environment.
Custom Task Panes, the Office Fluent Ribbon, and Reusing VBA Code in the 2007 Office System	Discusses a real-world project that uses custom task panes. Provides some insight into using the Word 2007 object model and the internal workings of the programmability features.
Working with Content Controls	Provides an introduction to content controls.
How To: Add Content Controls to Word Documents	Shows how to create document-level projects and application-level projects that add content controls at design time or run time.
Building Word 2007 Document Templates Using Content Controls	Shows how to write managed add-in code that accesses content controls.
Associating Data with Content Controls	Provides guidance and an example that shows how to associate arbitrary amounts of data with each content control in a document.
"How do I" articles on MSDN	Contains several topics around content controls, and binding to content controls in various scenarios.
Visual "How to" articles (with accompanying video) for Word 2007	Contains several topics with accompanying videos that show how to implement various scenarios that require programming.

Replacing Content Controls with Content

There are two approaches that you can take when you use content controls to replace content. You can completely replace the content control with the content, or you can bind the content control to XML in a custom XML part. The following sections explore each approach in more detail.

Sometimes you want to completely remove the content controls from the generated document, and replace them with the specific text or content. The following resources provide guidance and examples about how to implement this scenario.

Summary of Resources

Title	Description
Creating Documents by Using the Open XML Format SDK Version 2.0 CTP (Part 1 of 3)	Explores the architecture of content controls, and shows how to use the Open XML SDK 2.0 for Microsoft Office to find specific content controls and replace them with other content.
Creating Documents by Using the Open XML Format SDK 2.0 CTP (Part 3 of 3)	Shows how to use the altChunk functionality of the document format to assemble a document from multiple parts. Although the example that is presented in that article uses the altChunk object, another alternative is to replace the content control with content composed of WordprocessingML paragraphs, runs, and text elements.
Using DocumentBuilder with Content Controls for Document Assembly	Presents an approach for assembling a document by replacing content controls with content from other documents. The result is a document that does not contain altChunk elements, and can be additionally processed by Open XML-aware tools.
Comparison of altChunk to the DocumentBuilder Class	Compares and contrasts two approaches for replacing content controls with new content.
Generating Documents from SharePoint with Open XML Content Controls	Demonstrates an approach for completely replacing content controls with new content. It shows how to use content controls to configure a table that is replaced with a new table that has a generated row for each row in your data. Although the article focuses on SharePoint Server 2007, it presents some code that is not specific to SharePoint Server 2007 for creating Open XML documents.

Binding Content Controls to XML in Custom XML Parts

Another approach for using content controls to generate documents is to bind the content controls to custom XML data. This approach has the advantage that when generating the custom document, you do not have to form WordprocessingML to replace the content controls. Instead, if you start with a document that already has content controls that are bound to custom XML data, you only have to replace the custom XML part with XML that contains the data for the new document. The data-bound content controls are automatically updated with the new data.

<w:sdt>
  <w:sdtPr>
    <w:alias w:val="Name"/>
    <w:tag w:val="Name"/>
    <w:id w:val="13264407"/>
    <w:dataBinding
      w:xpath="/Root/Name"w:storeItemID="{F351E99C-3283-4B75-927A-A56C9FD3BFFC}"/>
    <w:text/>
  </w:sdtPr>
  <w:sdtContent>
    <w:tc>
      <w:tcPr>
        <w:tcW w:w="4410"
               w:type="dxa"/>
      </w:tcPr>
      <w:p>
        <w:r>
          <w:t>Eric White</w:t>
        </w:r>
      </w:p>
    </w:tc>
  </w:sdtContent>
</w:sdt>

The w:storeItemId element contains a GUID that provides the relationship to the specific custom XML part. The w:xpath element contains the path of the bound element in the custom XML part.

One characteristic of this approach is that the content controls remain in the generated document. This may not be appropriate for your specific scenario.

Summary of Resources

Title	Description
Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0)	Visual how to article with accompanying video that describes how to bind data to content controls.
Creating Documents by Using the Open XML Format SDK 2.0 CTP (Part 3 of 3)	Explains how to bind content controls to custom XML.
Creating Data-Bound Content Controls using the Open XML SDK and LINQ to XML	Explains how to use the Open XML SDK 2.0 for Microsoft Office with LINQ to XML to bind content controls to XML data.
Taking Advantage of Bound Content Controls	Shows another example for binding content controls to XML in a custom XML part. The Office Word Product team blog also contains an excellent post on data-bound content controls.
The Word Content Control Toolkit	CodePlex project that provides a drag-and-drop solution for binding content controls to XML data.
How to: Bind a Content Control to a Node in the Data Store	Shows an example for binding a content control to data in a custom XML part.
How to: Bind Controls to a Specific Row in the Data Store When Inserting a Building Block	Shows managed add-in code that binds a content control to a specific row in the data store.

Handling Events when Manipulating Content Controls

In your solution, you may want to take specific action when a content control is inserted, deleted, or updated. For example, you can write an event handler that is called when the user moves out of a content control. You can then validate the data that is entered by the user.

Content control events are associated with the Document object. You can write event handlers for the following events.

Title	Description
ContentControlAfterAdd Event	Occurs after you add a content control to a document.
ContentControlBeforeContentUpdate Event	Occurs before updating the content in a content control, only when the content comes from the Office XML data store.
ContentControlBeforeDelete Event	Occurs before removing a content control from a document.
ContentControlBeforeStoreUpdate Event	Occurs before updating the document's XML data store with the value of a content control.
ContentControlOnEnter Event	Occurs when a user enters a content control.
ContentControlOnExit Event	Occurs when a user leaves a content control.

Summary of Resources

Title	Description
Content Control Event Model in Word 2007	Excerpt of the book Visual Studio Tools for Office 2007: VSTO for Excel, Word, and Outlook by Eric Carter and Eric Lippert. Contains an overview of event handling for content controls.
Working with Content Controls	Provides an introduction to content controls.

Conclusion

Document generation systems are one of the most compelling uses of Open XML WordprocessingML. Content controls provide a great way to give structure to your content and to make it easier to build document generation systems.