Click here to Skip to main content
Click here to Skip to main content

WordML Templates Editor – data visualization using Office 2003 WordML features

, 27 Oct 2006
Rate this:
Please Sign up or sign in to vote.
This article explains how to use Office 2003 WordML features to display data stored in .NET datasets.

Introduction

Many of us have worked with data manipulation and data presentation. Probably, many times, your manager or your customer requested that the data reports or documents be Office compatible. They are used to working with Office, they are Office-dependent, and you cannot change this fact. They can use export features provided by reporting tools, but I guess they prefer to create their own templates and they would like to see data there. Rather than offer an unmanageable alternative to Office documents, you better "dress" their data in Office clothes. They will appreciate it.

WordML Templates Editor utility

Visualization file obtained by template transformation

The utility application, WordML Templates Editor, allows users to configure and fill with data an Office 2003 XML template, which is written in WordML language (the markup language used to define a MS Word document). This "template" is a simple XML file with some predefined constructs, not an MS Word ".DOT" template.

The idea comes from the MS Word feature which allows users to work with external data sources (MailMerge) and to manage metadata (mergefields). Unfortunately, a problem occurs in the MailMerge case when you want to display many records in the same document. When using the MailMerge feature directly from an MS Word application, it is difficult enough to display all the records in the data source. You must configure the main document to be as "Directory" type, and the processing repeats for all the document content for each record. But if you wish to show in the same document two or more recordsets, the situation becomes more complicated.

Suppose we want to extract from the Northwind database information about an order and its details, and the products list. Because the output will be an official document, we want to display information about the Northwind company, from a configuration file. So, we have four recordsets: two with only one record (the order and the company information), and two with many records (order details and products list).

The template can be built from an MS Word application, as well as from the utility application WordML Templates Editor, which hosts the MS Word application and has full internal access to its active document.

If you want to set the template directly from the MS Word application, you must link it to an external data source which contains the fields required by MailMerge. The easiest solution is to set as data source, a text file which contains only field definitions and a dummy row as a fake record. The disadvantage is that if you want to move the template to another machine, you have to move the data source too. For uniqueness and to distinguish between fields belonging to different tables, the field name must contain the table name and the field name in the table (concatenated). You can avoid using an external data source, by adding in the template, objects of type MergeField. The disadvantage is that you must know the field names (built, of course, by concatenation with their table name).

If the template is built using the utility application, you don't need an external data source, but you need to use the dataset (the structure, not the data) you want to display. The utility displays the dataset tables list, and the fields corresponding to each table. You can insert any field in any text location of the active document.

Two of the the four tables have only one record. In the template, you can distinguish between elements which will be shown only once and those which will be repeated (corresponding to the number of records). For the former, the display is done by a simple insertion at the specified location. For the latter, the display is a little elaborated. Because an MS Word document doesn’t permit accessing elements by an identifier, I have chosen the bookmark insertion solution. The bookmarks used to duplicate elements have a standard name: datatable name + "WMLRepeat" token + index, where index >= 1 is used when the data table appears many times in the document. When the template is parsed, if a bookmark like this appears in the document, the analyzer tries to identify a table object and, if successful, the table row which contains at least a merge field is duplicated, and the fields are replaced with data, for each record in the data table.

When fields are replaced with data, you can perform some date and numeric formatting. The formatting information is stored in internal template variables.

Till now, only table row objects can be used as repeated elements, but if you want to use other objects, you can use a hidden table object and add text boxes, lists, formatted text, and so on.

Template creation

Template creation using WordML Templates Editor

The template creation steps are as follows:

  • create or provide datasets accessible to your users: this could be a customizable list of entries which internally provides data sources for a template editor;
  • open an MS Word document, or create a new one (the editor can handle either standard DOC MS Word documents or XML MS Word documents, but only XML documents can be used as templates for data visualization);
  • modify the "template" with the visual elements you need;
  • choose what data tables and fields you want to insert in the "template";
  • for "repeating" elements (records that appear more than once in the document), select the specified location (the row used as template row in a MS Word table object) in the active document, and insert a special bookmark (the new bookmark will be added in the "WMLRepeat" bookmarks list);
  • add optionally, language name, date-time format, numeric group separator, decimal separator, decimal digits number;
  • save the template as XML.

The main editor form (frmWordControl) hosts the MS Word application in a control, as explained in the two articles specified in the "Thanks" section. The required constructs are added in the template using the MS Word DOM. It uses data sources from a dataset object or a text file (built as it is described in the previous section). The form is instantiated like this:

dsData = new DataSet();
dsData.Tables.Add(dt1);
dsData.Tables.Add(dt2);
…
frmWordControl frm = new frmWordControl(dsData);
frm.Show();

After metadata is shown in the form, you can:

  • insert merge fields in a specified location:
    Word.Range rng = wordCtl.Application.Selection.Range;
    item = listFields.Items[fieldIndex].ToString();
    if(item.Trim() != string.Empty)
    {
        wordCtl.Application.ActiveDocument.MailMerge.Fields.Add(rng, item);
    }
  • inserted special "repeat" bookmarks in a specified location:
    Word.Range rng = wordCtl.Application.Selection.Range;
    object oRng = (object)rng;
    wordCtl.Application.ActiveDocument.Bookmarks.Add(tableName + 
            "WMLRepeat" + index.ToString(), ref oRng);
  • specify formatting information (language, date format, decimal separator, number group separator, decimal digits number – stored in internal document variables):
    object oVariableValue;
    object oVariableName;
    Word.Variable var;
    
    oVariableValue = (object)languageName;
    oVariableName = (object)"LanguageName";
    var = 
      wordCtl.Application.ActiveDocument.Variables.get_Item(
      ref oVariableName);
    if(var != null)
        var.Value = languageName;
    else
        wordCtl.Application.ActiveDocument.Variables.Add("LanguageName", 
                                                    ref oVariableValue);

You can create new documents, open them from the disk, and save them in standard DOC or XML format.

Template visualization and the CExWordMLFiller class

The template visualization can be performed either from a Windows application, or from a web application. In both cases, the client machine should have installed Office 2003 or just the Word Viewer 2003.

The CExWordMLFiller class is responsible for inspecting a WordML template and filling it with the data provided by the dataset. Assume that you have a dataset dsData and an XML document xmlTemplateDoc, which contains the template. The code below is the required sequence to have a new XML document which mixes dataset data with visual features provided by the template:

CExWordMLFiller filler = new CExWordMLFiller(dsData, xmlTemplateDoc.OuterXml);
if(!filler.OperationFailed)
{
    filler.Transform();
    if(filler.OperationFailed)
    {
        foreach(string err in filler.ErrorList)
        {
            MessageBox.Show(err);
        }
        return;
    }
}
string copyFileName = Path.GetTempFileName() + ".xml";
filler.WordMLDocument.Save(copyFileName);

The WordMLDocument property of the filler object contains the XML document object corresponding to the result obtained by the transformation. You can save the result in a file, or use it as a document, stream, or string.

The constructor needs two parameters: the dataset which will be displayed, and the template content as string. The content must be a valid WordML string, and it will be loaded in an XML document object. Also, the dataset will be loaded with its schema in an XML document, which will be used for removing unfilled fields at the end of the transformation. For some reasons (the corresponding data table is missing from the dataset), some fields could not be filled with data. The unfilled fields must be "removed", because the visualization file could contain "ugly" merge field definitions like "«OrderOrderID»".

The LoadTemplate method prepares date and numeric formatting for dataset values. The formatting information is loaded from docVar nodes (document internal variables):

XmlNode varNode = xmlTemplateDoc.SelectSingleNode("//w:docVar" + 
                  "[@w:name='LanguageName']/@w:val", nsmgr);
if(varNode != null)
{
    languageName = varNode.Value;
    try
    {
        ci = new CultureInfo(languageName, false);
        numberFormat = ci.NumberFormat;
    }
    catch
    {
        languageName = null;
        numberFormat = null;
    }
}
else
{
    languageName = null;
}

The Transform method performs the transformation. This method performs a loop into the dataset Tables collection, and calls the TransformDataTable method which checks every data table for visualization (if its rows are subject to be shown). After that, to eliminate dirty constructs, it removes the "mail merge" node (RemoveMailMergeNode) and the unfilled fields (RemoveUnfilledFields).

The TransformDataTable method identifies locations where to "repeat" elements and where to show them only once. The TransformWordMLTableRepeat method identifies the MS Word tables which display the current data table rows using the aml:annotation WordML element, which corresponds to a "repeat" bookmark. It takes the template row node (w:tr) and calls the TransformDataRow method with three parameters: data row, table node, and template row node. After all the rows are processed, the template row node is removed from the table.

string tableName = dt.TableName;
XmlNodeList oColl = 
  xmlTemplateDoc.SelectNodes("//w:tbl[contains(descendant::aml:a" + 
  "nnotation/@w:name, '" + tableName + repeatAttribute + 
  "') and (contains(descendant::w:instrText, ' MERGEFIELD \"" + 
  tableName + "') or contains(descendant::w:instrText, ' MERGEFIELD " + 
  tableName + "'))]", nsmgr);
XmlNode templateRowNode;
if(oColl != null && oColl.Count > 0)
{
    foreach(XmlNode tableNode in oColl)
{
        templateRowNode = tableNode.SelectSingleNode("w:tr[contains" + 
                          "(descendant::w:instrText, ' MERGEFIELD \"" + 
                          tableName + "') or contains" + 
                          "(descendant::w:instrText," + 
                          " ' MERGEFIELD " + tableName + "')]", nsmgr);
        if(templateRowNode != null)
        {
            foreach(DataRow dr in dt.Rows)
            {
                TransformDataRow(dr, tableNode, templateRowNode);
            }
            tableNode.RemoveChild(templateRowNode);
        }
    }
}

The TransformDataRow method checks in the current table row node where the data row fields are displayed, and replaces their values with real data. The template row node is cloned, and it is inserted before the template row node in the MS Word table object.

The ReplaceFieldData method identifies field locations, and applies date and numeric formatting:

oColl = baseNode.SelectNodes("//w:p[w:r/w:instrText=' MERGEFIELD " + 
                             fieldName + " ']", nsmgr);
…
foreach(XmlNode fieldNode in oColl)
{
    //select run element containing the underlying data
    dataNode = fieldNode.SelectSingleNode("//w:t[.='«" + 
               fieldName + "»']", nsmgr);
    …
    if(colType == typeof(DateTime))
    {
        if(dateTimeFormat != null)
        {
            DateTime dt = DateTime.Parse(data);
            dataNode.InnerText = dt.ToString(dateTimeFormat);
        }
        else
        {
            dataNode.InnerText = data;
        }
    }
    …
}

A Windows application will open the result file simply by association with its type:

System.Diagnostics.Process.Start(copyFileName);

A web application needs more code to display the output in a browser:

Response.ClearContent();
Response.ClearHeaders();
Response.Clear();
Response.ContentType = "application/msword";
Response.Charset = ""; 

Response.AddHeader("Content-disposition", 
                   "inline; filename=\"" + 
                   copyFileName + "\"");
Response.AddHeader("Content-length", fi.Length.ToString());
Response.WriteFile(copyFileName);
Response.Flush(); 
Response.Close();

Template visualization and the CWordDOCFiller class

As Mr. Trevor Farley recommended, I have recently added the CWordDOCFiller class which is able to parse DOC templates. The class performs the same operations as the CExWordMLFiller class does, but using Word DOM. Unfortunately, some performance issues appear when you access the Fields collection, if the data to display is large (for the same Order template, the DOM version duration is 2-3 minutes, while the XML approach is almost instantly). Of course, the DOM approach is much readable and easy to maintain and it could be applied for previous versions of MS Word.

The code sequence needed to use CWordDOCFiller class is:

string templateFileName = Application.StartupPath + @"\Templates\Order.doc";
string copyFileName = Path.GetTempFileName() + ".doc";
File.Copy(templateFileName, copyFileName, true);

CWordDOCFiller filler = new CWordDOCFiller(dsData, copyFileName);
if(!filler.OperationFailed)
{
    filler.Transform();
    if(filler.OperationFailed)
    {
        foreach(string err in filler.ErrorList)
        {
            MessageBox.Show(err, "Error", MessageBoxButtons.OK, 
                            MessageBoxIcon.Error);
        }
        return;
    }
}
else
{
    foreach(string err in filler.ErrorList)
    {
        MessageBox.Show(err, "Error", MessageBoxButtons.OK, 
                        MessageBoxIcon.Error);
    }
}

The constructor receives two parameters: the dataset and the path of the template. To avoid altering the template, copy it in the %TEMP% folder. The class uses Word.Application (in a private object oApp) object to load and to modify the document. The formatting information is stored in the Word.Variables collection, and used when the fields content is replaced with data. The main method used to apply transformation is Transform, which applies all transforming operations over the data tables in the dataset:

bOperationFailed = false;
try
{
    foreach(DataTable dt in dsData.Tables)
    {
        TransformTableRepeat(dt);
    }
    //fill with data no repeat
    ReplaceFieldDataNoRepeat();
    oApp.Visible = true;
}
catch(Exception ex)
{
    while(ex != null)
    {
        errorList.Add(ex.Message);
        ex = ex.InnerException;
    }
    bOperationFailed = true;
}

The TransformTableRepeat method performs transformation for every DataRow object, consuming the meta information from the template Word table row. The template row is copied and the copy is the subject to be filled with data (in the TransformDataRow method). At the end, the template row is deleted.

string tableName = dt.TableName;
foreach(Word.Bookmark bmk in oTemplateDoc.Bookmarks)
{
    if(bmk.Name.StartsWith(tableName + repeatAttribute))
    {
        Word.Table tbl = bmk.Range.Tables[1];
        Word.Row row = bmk.Range.Rows[1];
        for(int i = 0; i < dt.Rows.Count; i++)
        {
            TransformDataRow(dt.Rows[i], tbl, row, bmk.Name, i);
        }
        row.Delete();
    }
}

The TransformDataRow method creates new fields and add them to the specified location, ensuring that new fields names are unique in the document. As well, it completes data fulfilling for the new created fields:

DataTable dt = dr.Table;
string tableName = dt.TableName;
object oTemplateRow = (object) templateRow;
Word.Row row = tbl.Rows.Add(ref oTemplateRow);
string fieldName;
Word.Fields fields;
int fieldIndex;
Word.Field field = null;
string dataFieldName = string.Empty;
Type dataFieldType = typeof(object);
foreach(Word.Cell cell in templateRow.Cells)
{
    fieldName = cell.Range.Fields[1].Code.Text.Trim();
    fieldName = fieldName.Replace("MERGEFIELD ", string.Empty);
    fieldName = fieldName + bmkName + rowIndex.ToString();
    oTemplateDoc.MailMerge.Fields.Add(
       row.Cells[cell.ColumnIndex].Range, fieldName);
    fields = row.Cells[cell.ColumnIndex].Range.Fields;
    fieldIndex = fields.Count;
    field = fields[fieldIndex];
    dataFieldName = field.Code.Text.Trim();
    dataFieldName = dataFieldName.Replace("MERGEFIELD " + 
                             dt.TableName, string.Empty);
    dataFieldName = dataFieldName.Replace(bmkName + 
                rowIndex.ToString(), string.Empty);
    dataFieldType = dt.Columns[dataFieldName].DataType;
    ReplaceFieldData(field, dr[dataFieldName].ToString(), 
                                          dataFieldType);
}

The ReplaceFieldDataNoRepeat method completes data fulfilling for "non-repeated" fields:

bOperationFailed = false;
DataRow firstRow;
foreach(Word.Field field in oTemplateDoc.Fields)
{
    if(field.Code.Text.IndexOf(repeatAttribute) == -1)
    {
        foreach(DataTable dt in dsData.Tables)
        {
            if(dt.Rows.Count > 0)
            {
                firstRow = dt.Rows[0];
                for(int j = 0; j < dt.Columns.Count; j++)
                {
                    if(field.Code.Text.Trim() == "MERGEFIELD " + 
                         dt.TableName + dt.Columns[j].ColumnName)
                        ReplaceFieldData(field, firstRow[j].ToString(), 
                                               dt.Columns[j].DataType);
                }
            }
        }
    }
}

The ReplaceFieldData takes a reference for a Word.Field object and sets data, using formatting information. The code used to open the file is not needed anymore, as the Application object embedded in the CWordDOCFiller class allows showing the result of the transformation.

Using the application

The solution WordDataSetTemplateEditor.root contains four projects:

  • WinWordControl – the user control which hosts the application;
  • WordDataSetTemplateEditor – the main editor project;
  • NorthwindDA – the data access component for the Northwind database;
  • Test – the test application for a specified order and order details visualization, and for an alphabetical list of products.

The templates Order.xml and Order.doc in the Templates folder are the needed templates for the Test application. When the project is compiled, these templates are copied into a similar folder in the application startup path.

I have remarked that if you want to update a field, the data replacement is cancelled and impossible to recover. I guess it is a good reason to eliminate just the FIELD definition. In WordML approach, this supposes to remove specific XML nodes (w:r/w:fldChar and w:r/w:instrText) for each field, while in Word DOM approach this issue is solved much more elegant using the Unlink method of the Fields collection (oTemplateDoc.Fields.Unlink();).

Thanks

Many thanks to Matthias Hänel and Anup Shinde for their excellent articles (Word Control for .NET and Integrating Microsoft Word in your .NET application). Thanks to Trevor Farley for its recommendation to create the CWordDOCFiller class for Word DOM approach.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Dan Radu
Web Developer
Romania Romania
I live and work in Bucharest, Romania. I am programmer since 1998, when I have developed a "good taste" application for a catering company. Now I develop .NET applications (windows and ASP.NET) for large SQL Server database systems, with tens of millions of records.
I like to develop also in other languages like Object Pascal (Delphi), PHP, C++, VB, scripting. I enjoy the XML power, both on client side and server side.

Comments and Discussions

 
QuestionHow to run you application in 64Bit web form application PinmemberMember 100416336-Aug-13 15:53 
GeneraloApp Location PinmemberBoipelo13-Dec-10 1:13 
GeneralFill in Footer/Header Pinmembercode8517-Jun-10 17:02 
Generalhi Word is DLL or what PinmemberSALEEM MULLA29-Mar-10 0:32 
GeneralRe: hi Word is DLL or what PinmemberDan Radu29-Mar-10 1:50 
GeneralInsert XML into table repeater PinmemberMember 182719622-Jan-09 5:53 
QuestionSimple example to export a word document with an image and a table in ASP.NET PinmemberPeter Derwa2-Oct-08 22:50 
GeneralVery good PinmemberMircea Puiu5-Jan-08 21:27 
QuestionPost Build Event Failed Pinmemberjomree15-Oct-07 1:01 
GeneralPreview PinmemberMarcel Vreuls25-Jul-07 22:45 
Questionhow to insert a img in the world PinmemberPenny082123-Jul-07 20:53 
AnswerRe: how to insert a img in the world PinmemberDan Radu24-Jul-07 2:24 
GeneralRe: how to insert a img in the world PinmemberPenny082124-Jul-07 15:32 
Generalchange numberFormat.nativeDigits Pinmemberhamid_m17-Feb-07 7:58 
GeneralUsing fields around the merge fields Pinmemberglassenbury7-Feb-07 15:03 
GeneralRe: Using fields around the merge fields PinmemberDan Radu10-Feb-07 16:20 
GeneralRe: Using fields around the merge fields Pinmemberdgortemaker19-Mar-07 2:30 
GeneralRe: Using fields around the merge fields PinmemberDan Radu19-Mar-07 13:45 
GeneralRe: Using fields around the merge fields Pinmemberdgortemaker19-Mar-07 21:59 
GeneralRe: Using fields around the merge fields PinmemberDan Radu21-Mar-07 2:50 
Generalxml fields in order Pinmemberglassenbury31-Jan-07 15:21 
GeneralNewLine PinmemberAbrian11-Jan-07 23:01 
GeneralRe: NewLine PinmemberAbrian14-Jan-07 20:55 
GeneralRe: NewLine PinmemberDan Radu21-Jan-07 19:47 
GeneralRe: NewLine Pinmemberkiennt23-Jun-09 23:44 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web01 | 2.8.140821.2 | Last Updated 27 Oct 2006
Article Copyright 2006 by Dan Radu
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid