Wordlayout revisited

I remember well, when Wordlayout was introduced in NAV 2015 and everyone got excited and hoped, that designing reports for NAV would now become more easy and efficient. But the excitement soon calmed down, when from the first experiments with the new functionality, it became evident, that there are quite many things, which won’t work as expected, like for example nested repeaters. Besides, there seemed to be some bugs, which still persist to version NAV 2016. For those reasons other third party report building solutions came into play, which offered quite intuitive report design capabilities for NAV. And so, today, a serious NAV report developer tends to wave aside, if someone suggests to use Wordlayout as an alternative to RDLC. But Wordlayout functionality is quite wrongly refused, as I will try to demonstrate in this article…At first, some basic knowledge about the underlying functionality of Wordlayout is required. You should have at least Word 2013 installed, in order to test the examples below.

How the Word developers made everything wonderfully…

This functionality has been introduced into Word with Office 2007 together with the fundamental change of the office file format from a proprietary one to Office Open XML format (see https://en.wikipedia.org/wiki/Office_Open_XML , e. g.), resulting in new filename extensions (docx, xlsx, etc.). Essentially, a Word docx file is nothing else than a zip archive. You can simply rename a .docx file to .zip and unzip it. You will get some folders with files in xml format. You can edit these xml files, zip them again and rename the resulting .zip file back to .docx without any problems. Here is an example of an unzipped Word docx file with custom xml part (see below):

A Word document R91304.docx unzipped.
A Word document R91304.docx unzipped.

One of the basic functionalities of Word in connection with NAV is the usage and mapping of so called custom xml parts. A custom xml part is nothing else than a xml file (usually named item1.xml), containing data in a structured format, which is added to the docx zip-archive and the data xml nodes are referenced (mapped) from so called content controls in the main Word document (document.xml) via XPath expressions. The format of this custom xml part file is quite simple. Here is an example:

Custom XML Part item1.xml
Custom XML Part item1.xml

Since Word 2013 you can add your own custom xml file to an existing Word document via the XML Mapping Pane in the Developer tab. By the way, such an xml file is also created from NAV, when you add a new Wordlayout to a NAV report or export an existing layout or call the WORDXMLPART function. The content of this xml file is based upon the DataItems and Fields defined in the Report Dataset Designer of NAV. In Word there are several types of content controls available. In connection with NAV, mainly the plain text, rich text, image and repeating section content control (RSCC) are used. The latter is available since Word 2013. These content controls can be inserted into a Word document from the Developer tab in Word (This tab is not visible by default). The procedure of inserting is well known (see https://msdn.microsoft.com/en-us/library/office/jj889465.aspx, for example). Furthermore, a content control can be directly bound to a custom xml node, if it is inserted via the XML Mapping Pane. Each element node in the custom xml file is supposed to occur at most once, except the nodes that are bound to a RSCC. For each occurence of such a repeating node, a new section (for example a new table row) is automatically created within the word document. There a hardly any limiations for creating a word document with content controls and a custom xml part. For example, VBA (macros) can be used, RSCC can contain other RSCC (nested repeaters), arbitrary paragraphs containing whole tables can be surrounded by a RSCC. You can use manual line breaks within plain text controls (provided the property “Allow carriage returns” is enabled), and so on. One limitation for nested RSCC is, that the starting/ending tag of two nested RSCC may not lie within the same paragraph or table cell (see https://msdn.microsoft.com/en-us/library/office/jj889465.aspx). In order to quickly add a custom xml data file to an existing word layout file, I wrote a small command file, which you are kindly invited to share for your own experiments (just download the file and rename it to AddCustomXML.cmd):


In addition, the zip.exe and unzip.exe utilities are required. They can be downloaded here, http://www.info-zip.org/Zip.html, e. g.
The cmd file has three input parameters, where the third one can be omitted. The command line call is:
AddCustomXMLPart [wordTemplateFile] [xmlFile] ([wordOutputFile])
If [wordOutputFile] is omitted, the [wordTemplateFile] will be overwritten and become the output file. Of course you can modify the cmd file to suit your own needs.

… and how the NAV developers messed up something…

Now lets take look on how these features are used within NAV Wordlayout functionality. In Codeunit 1 ApplicationManagement of NAV 2016, there is a function MergeDocument with ID 77, which essentially calls the function MergeWordLayout in Codeunit 9651 “Document Report Mgt.”. In this function, a server based AddIn NAVWordXMLMerger is called, which merges the resulting word file from the word layout template (custom or build in report layout) and an xml data file, which is nothing more than the output of the REPORT.SAVEASXML command as an InStream:

OutStrWordDoc := NAVWordXMLMerger.MergeWordDocument(InStrWordDoc,InStrXmlData,OutStrWordDoc) ;

The resulting OutStrWordDoc text variable is in docx format and can be directly opened or printed with Word. Though I don’t not know how the MergeWordDocument method is working in detail, it does definitely not merely substitute the item1.xml file of the word template with the xml data file, as would suggest itself. Instead it looks like, the automatic merging process of word has been replaced by a manual one. This is the only explanation for the severe limitations and “features”, that this function provides to the user, for example:

  • RSCC seems to only work for single table rows. Repeaters can neither be nested, nor put around more than one table row nor paragraphs not to mention a whole table.
  • There seems to be no way to introduce a manual line break into a plain text or rich text content control.
  • The sizes of images may be messed up, if their pixel size varies within a RSCC.
  • All content controls are removed from the output word file.
  • Word templates with macros (dotm files) cannot be used (though this might not be due to a restriction of the MergeWordDocument  method but has its reason elsewhere in the NAV code).

One complication arises from the fact, that the format of the SAVEASXML output does not conform with the custom xml part syntax. But with a small XSL transformation, this can be cured.

A XSL transformation converts the NAV XML output to custom XML part format.
A XSL transformation converts the NAV XML output to custom XML part format.

… and how they should have done it the obvious way.

The simplest way in my opinion would be to merely substitute the custom xml part (item1.xml) of the word template with the (xsl transformed) xml output of the SAVEASXML function. After this step, the empty content controls (especially image controls) should be removed from the resulting word document, because otherwise they may consume space (image controls) or print annoying input prompts (text controls). If some extensions are to be implemented for which the standard word functionalitiy is insufficient like Transheader/-footer line calculations, e. g., this would be the right place to do that programatically, too. If this is not possible in the upcoming version of NAV (NAV 2017 or NAV 365, respectively), I’m pretty sure, that a small third party tool will soon be available…
Here is a sample preview with nested RSCC (one table row and the whole table based on the sample xml data above), which shows, that grouping may no longer be a great dream in Wordlayout reports.

Word report layout with grouping.
Word report layout with grouping.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s