An example of customizing Word templates in round-trip export

Tags: not added yet

In following simple tutorial we will customize the default Word export template to show the value of a custom property of the exported requirement.

Inspect tracker configuration

In this example we will use the standard Test-Case tracker which has several custom properties. Let's look at the configuration of that tracker (to access this click on "Customize" menu of the tracker):

The most interesting information on this configuration is the "Property" column. This contains the property which stores the custom field. Here the

customField[0]

contains the Pre-Action and

customField[1]

contains the Post-Action values. Make a note of these.

Customize Word template

Now we have the information where the custom field is stored. Let's customize the Word export template.

First you should download the default template as starting point of customizations. You can access the default template as it is described in the Word Templates in CB 7.2 - 9.2 document.

Save the default template in the local file system, and open it in Word. To customize the "Properties" section which is appearing above each exported issue/requirement please find the "Properties Velocity Template" block in the template document. This should appear as a blue box in the template document like this:

In the default template this contains a quite complex script which displays the association and references of the export issue. In our example we don't want that, but instead we just want to export the "Pre-Action" and "Post-Action" custom fields.

So as first let's delete all content from here, but keep only the beginning:

#*
   This is a velocity template renders HTML fragment for Properties of entities
*#
## load Properties specific macros:
#parse("/html/mhtml-properties-macros.vm")

#set($requirement = $describable)

Two important things to know about the Properties part:

This part can contain a Velocity script, which is a simple but powerful templating language. If you're not familiar with Velocity it is advised to read the Velocity User Guide
The output of the Velocity script here should produce a valid HTML markup. We use HTML here for simplicity, as that is one of the most widely known presentation markups used by the whole internet. See: What is HTML?. The HTML is then automatically converted to native Word content later...

So if you would run an export this template what you would see now that the "Properties" part is completely missing, which is OK, as this script does produce any output.

Let's now add few lines of Velocity code to the end of the script to access the Pre-Action and Post-Action fields:

## clear variables may have set previously
#set($preAction = "")
#set($postAction = "")

## access custom field values
#set($preAction = ${requirement.getCustomField(0)})
#set($postAction = ${requirement.getCustomField(1)})

Two thing is happening here:

First we clear the "preAction" and "postAction" variables. This is necessary because the Velocity scripts in the template are preserving variables between rendering runs. So if we don't clear the "preAction" we may get some value from the previous issue in the export document here, which would be not a good idea.

Second: we set the preAction variable to the "requirement.getCustomField(0)". As you may remember the Pre-Action field appeared as "customField(0)" on the Tracker customization screen. That can be accessed using the "getCustomField(0)" method call on the exported requirement. The ${requirement} variable contains the current requirement being exported.

So that is fine, we have the Pre- and Post-actions' values, however still there is no output appearing in the export document. Let's add some more code to the end of the script to produce HTML output:

#if ("$!{preAction}" != "")
<b>Pre-Action:</b>&nbsp;$wikiMarkupProcessor.transformToHtml($!{preAction}, “W”, false, false, $wikiContext)
<br/>
#end
#if ("$!{postAction}" != "")
<b>Post-Action:</b>&nbsp;$wikiMarkupProcessor.transformToHtml($!{postAction}, “W”, false, false, $wikiContext)
<br/>
#end

What is happening here is that we check using and "if" statement if the "preAction" contains a non-empty value and then output a bold "Pre-Action" text, followed by the content of the pre-action field, and then a new line.

The "$wikiMarkupProcessor.transformToHtml(...)" method call will convert the Wiki text to HTML, so if the Pre/Post-Action contains rich text (bold/italic) or even images those will be also appearing correctly in Word export.

The output in the word export will look like this:

That's about it. The complete template which was used in this tutorial is available here: CB:/displayDocument/Custom-fields-template.docx?doc_id=1740293