Over the last few days, I have completed a new prototype of an approach to Open XML WordprocessingML document generation. In this approach, I control the document generation process by placing XPath expressions in content controls. In contrast, the previous approach in this series of posts on document generation was controlled by writing C# code in content controls.
This post is the 13th in a series of blog posts on generating Open XML documents. Here is the complete list: Generating Open XML WordprocessingML Documents Blog Post Series
When I started down this path of discovery around document generation, I would not have predicted it, but the XPath-in-Content-Controls approach is, in my opinion, much superior to the C#-in-Content-Controls approach. Going forward, I am going to abandon the C#-in-Content-Controls approach, and focus on this approach using XPath. There are some very cool places that we can take this approach.
To compare and contrast, the C#-in-Content-Controls prototype consists of less than 400 lines of code. While it was not fully fleshed-out, and there remain many necessary refinements, I would expect that a finished version would be perhaps 3000 lines of code.
The XPath-in-Content-Controls prototype that I am introducing in this post is even smaller. It is less than 240 lines of code. It is simpler, more robust, and more amenable to polishing. I expect that the finished example, including integration into a document-level add-in for Word 2010 will be less than 1000 lines of code. I’ll be posting V1 of the prototype with the next post in this series.
Driven from an XML Document
One of the nice things about the C#-in-Content-Controls approach is that you could drive the document generation process from literally any data you could get your hands on from the .NET framework. In contrast, with this approach, there is one and only one form of data source, which is an XML document. And in this first prototype, I am restricting the data to an XML document that contains XML in no namespace. Allowing for namespaces in the XML means that I would need to provide mapping between namespaces and namespace prefixes, and that would get in the way of discussing the architecture and merits of this approach. I’ll deal with this in the future.
In the meantime, if you have XML that uses namespaces (or any other variety of data sources), your first task is to transform that data source to XML in no namespace.
The XML document should look something like this:
<Customers>
<Customer>
<CustomerID>1</CustomerID>
<Name>Andrew</Name>
<HighValueCustomer>True</HighValueCustomer>
<Orders>
<Order>
<ProductDescription>Bike</ProductDescription>
<Quantity>2</Quantity>
<OrderDate>5/1/2002</OrderDate>
</Order>
<Order>
<ProductDescription>Sleigh</ProductDescription>
<Quantity>2</Quantity>
<OrderDate>11/1/2000</OrderDate>
</Order>
<Order>
<ProductDescription>Plane</ProductDescription>
<Quantity>2</Quantity>
<OrderDate>2/19/2000</OrderDate>
</Order>
</Orders>
</Customer>
<Customer>
<CustomerID>2</CustomerID>
<Name>Bob</Name>
<HighValueCustomer>False</HighValueCustomer>
<Orders>
<Order>
<ProductDescription>Boat</ProductDescription>
<Quantity>2</Quantity>
<OrderDate>8/9/2000</OrderDate>
</Order>
<Order>
<ProductDescription>Boat</ProductDescription>
<Quantity>4</Quantity>
<OrderDate>3/25/2001</OrderDate>
</Order>
<Order>
<ProductDescription>Bike</ProductDescription>
<Quantity>1</Quantity>
<OrderDate>6/5/2002</OrderDate>
</Order>
</Orders>
</Customer>
<Customer>
<CustomerID>3</CustomerID>
<Name>Celcin</Name>
<HighValueCustomer>False</HighValueCustomer>
<Orders>
<Order>
<ProductDescription>Bike</ProductDescription>
<Quantity>2</Quantity>
<OrderDate>2/24/2001</OrderDate>
</Order>
<Order>
<ProductDescription>Boat</ProductDescription>
<Quantity>4</Quantity>
<OrderDate>5/6/2001</OrderDate>
</Order>
</Orders>
</Customer>
</Customers>
While it isn’t required, it is more convenient to use a form where the Orders element is a child of the Customer element. The reason for this will become clear.
The XPath-in-Content-Controls Template Document
The next step in introducing this approach is to take a look at the template document that will drive document generation. While looking at this template, you can compare and contrast it to the template that contains C# code in content controls.
In this template document, I am going to borrow some nomenclature from XSLT. One of the attributes of the xsl:apply-templates element is the select attribute. If you place an XPath expression in the optional select attribute, XSLT will apply templates to the set of nodes that are selected by the XPath expression. The XPath expression is applied relative to the current context of the node that is currently being transformed by the sequence constructor. I am going to use a very similar approach in the template document. In effect, I am going to turn an Open XML WordprocessingML document into something that is analogous to an XSLT style sheet. Don’t worry if this is not immediately clear. It will be before the end of this blog post series. The point of this paragraph is that I’m going to use the term Select to indicate an XPath expression that will be evaluated, and the results of the evaluation will become the current context for other operations.
As usual, I am going to show content controls in design mode. Here is the template document, in its entirety. Of course, the circles and arrows are added by me to aid in explanation.
The Config Content Control (*1)
Starting at the bottom of the document, there is the Config content control, which contains XML, with a root element of Config.
The DataFileName element specifies the source XML document that contains the data that drives the document generation process.
The SelectDocuments element specifies an XPath expression that when evaluated against the root element of the document returns a collection of elements, each of which represent a document to be generated. In the case of the XML data file that I presented earlier, the XPath expression “./Customer” returns a collection of the Customer child elements of the root Customers element. Given that source data file, the document generation process will generate three documents.
The DocumentGenerationInfo element, and its child elements contains the necessary information to control the actual physical generation of the documents – the directory where the documents will be placed, a .NET StringFormat that works in conjunction with the SelectDocumentName XPath expression to assemble the generated FileName.
As an aside, I initially played around with nested content controls instead of having a single content control that contains XML. While this approach works, maintaining nested content controls using the Word 2007 or Word 2010 user interface is idiosyncratic. I could write a pretty detailed bug report around the maintainability of nested content controls. Maintaining the XML in a single content control is a more satisfactory approach.
The SelectValue Content Control (*2)
At the top of the template document, you can see the SelectValue content controls. As mentioned in the last section, the SelectDocuments XPath expression selects multiple Customer elements. While generating each document in turn, each Customer element becomes the current context. The SelectValue XPath expression is then evaluated in the context of each Customer element in turn. One of the circled SelectValue XPath expressions selects the Name child element of the Customer element. The other circled SelectValue XPath expression selects the CustomerID child element of the Customer element. In XML, the value of an element is defined to be the concatenated descendant text nodes (in other words, its textual content). The document generation engine retrieves the value of the selected element and replaces the content control with the value.
The Table Content Control (*3)
Just as the SelectValue content control is evaluated in the context of a Customer element, the SelectRows content control is also evaluated in the context of a Customer element. The difference is that SelectValue is expected to select a single element, whereas the SelectRows expression is expected to select a collection of elements, one for each row in the table. For customer #1 (Andrew), the SelectRows XPath expression selects three Customer elements. The XPath expressions (pointed to by *4) stored in the prototype row (the second row in the table) are evaluated in the context of each row selected by the SelectRows expression.
You also often see a similar pattern in properly written XSLT style sheets. One template is evaluated in the context of the root element, which selects a set of elements. An xsl:apply-templates causes an XPath expression to be evaluated in the context of each element selected by the first template. And an xsl:apply-templates in the sequence constructor of the second template causes an XPath expression to be evaluated in the context of each element selected by the second template, thereby causing a third set of templates to be applied.
Once you are familiar with this approach (sometimes called the ‘pull’ approach), you never write XSLT style sheets in any other way. Inexperienced XSLT developers sometimes try to write style sheets by using loops and calling templates explicitly, instead of letting the pattern matching power of XSLT to do the heavy lifting. This incorrect approach is sometimes called the ‘push’ approach.
To summarize, the SelectDocuments expression selects multiple elements, one for each document. The SelectRows expression, evaluated in the context of the elements selected by SelectDocuments, selects multiple elements, one for each row. The XPath expressions in the prototype row are evaluated in the context of the row elements selected by SelectRows.
The Conditional Content Control (*5)
The conditional content control works in exactly the same way as SelectValue and SelectRows. The SelectTestValue expression is evaluated in the context of the Customer element. The retrieved value is compared to the contents of the Match content control. If there is a match, the Conditional content control is replaced by the contents of the Content content control in the generated document.
Advantages of the XPath-in-Content-Controls Approach
There are several advantages to the XPath-in-Content-Controls approach over the C#-in-Content-Controls approach:
- We eliminate the two-step process for generating documents. The program that processes the template (and processes all of the XPath expressions in the template) does the actual document generation. We don’t need to generate code, and then compile and run the generated code.
- We can catch errors in the XPath expressions, and supply the template designer with good error messages that indicate the specific XPath expression that contains the error.
- We eliminate all of the issues associated with typing C# code into content controls. When entering C# code in Word, of course there is no Intellisense. It could be difficult to catch errors in the C# code. The issues associated with replacing single or double quotes with smart quotes is significantly reduced. Note that the issues around quotes is not entirely eliminated. There are circumstances where the template designer may need to use single or double quotes in XPath expressions.
In the next post, I’ll show a video of this approach in action.
Future posts:
- Show this approach at scale
- Review XPath semantics of LINQ to XML
- Examine the issues around namespaces in the source XML document
- Show the process of changing the schema
- Add robustness and error handling
- Integrate as a document-level managed add-in for Word 2010.
This is fun!
