The problem: Table Of Content in Word exports

When exporting to Word using the default templates you will see that the Word document will contain the "description" part of each exported Work item.

This is nice works fine, however there is one problem with that: if the description of a Work item contains a Heading 1/Heading 2/etc... markup then these Headings will appear in the Table-of-Contents of Word and will also appear on the Navigation pane of Word.

This screenshot illustrates this, on the left side the exported Word document's Tabel-of-Content, on the right the original markup from codeBeamer.

So if you want that the Word's Table-Of-Content should not contains these Heading elements and only the names of the exported Work items, here is the solution below.

The solution how-to

These Heading elements from the description of Work items are appearing in the Words' Table-of-Contents, because the HTML Heading elements are automatically mapped by Word's "Heading 1"/"Heading 2"/etc... styles, and these are automatically appear in the TOC.

The fix is implemented in the attached custom template: download

The solution is:

• Create new Word styles for Heading1/Heading2/etc... which wont' appear in the TOC
• During the Word export capture the Heading elements in the generated HTML (built from the Wiki markup)
• rewrite the HTML markup and map to a new Word style which will not appear in the TOC
• Then adjust the CSS so the Heading elements will look same as the style in Word

Prepare a new template

Creating new Word styles for Heading elements that don't appear in TOC

Open your template and define a new style called "HiddenHeading1" there. To do that follow the steps on this screenshot:

1. Click on the small icon in the "Styles" toolbar. This shows you the Styles dialog.
2. Click on the "new" icon on the Styles dialog, this opens up the Create new style dialog
3. On the Create New style dialog enter the new style name "HiddenHeading1" in this example.
4. Then select the parent style (Style based on), which should be the Style where the new Style inherits its settings and look. This will be "Heading1" in this case
5. Next customize the new Style's look. For that click on the "Format" button below, and select "Paragraph"
6. Next the Paragraphs' dialog appears. Because in our "HiddenHeading1" we don't want this appearing in the TOC change the "Outline level" property to "Body Text" which will make that this Style will NOT appear in TOC.

Now we have created a "HiddenHeading1" which is a copy of "Heading 1" except that elements with this style will not appear in TOC. Repeat the same for "Heading 2" and "Heading 3" and create their similar pair like "HiddenHeading2" and "HiddenHeading3".

Rewrite the Heading Wiki/HTML elements of description

Now we have a "HiddenHeading1"/"HiddenHeading2" etc... Word styles. To use these styles the instead of the standard "Heading 1"/etc... the Word export template needs to rewrite the HTML generated from the Work Items' description to use them.

So if the description contains this wiki text:

!1 Heading one

content-one

That is exported/rendered as this HTML fragment:

<h1>Heading one</h1>
content-one

To make this to use the HiddenHeading1 Word style we must replace such "~<h1>" tags with this Word compatible markup:

<p class="HiddenHeading1">Heading one</p>
content-one

To perform this we must add some code which rewrites the HTML output in the Word export template. So use this script as replacement in the "Description" part of your custom Word export template:

## capture the HTML form of the Work item's description to a variable
#set($html = $wikiMarkupProcessor.transformToHtml(${describable.description}, ${describable.descriptionFormat}, false, false, $wikiContext))

<!-- ## Trick: adding an html comment block around this script to avoid any output appearing from here
## parse the HTML output of the item’s description using JSOUP
## calls the static method: JSoup.parse(String)
#set($Jsoup = $request.class.forName(“org.jsoup.Jsoup”))
#set($doc = $Jsoup.parse($html))

##following modifies all h elements adds red font-color
##${doc.select(“h1,h2,h3,h4,h5,h6”).attr(“style”,”mso-outline-level:6;color:red;”)}
## replace H1 with <p class=”HiddenHeading1” so the Word’s HiddenHeading1 style will be applied on this,
## therefore won’t appear in the Table-of-contents!
${doc.select(“h1”).tagName(“p”).attr(“class”,”HiddenHeading1”)}
${doc.select(“h2”).tagName(“p”).attr(“class”,”HiddenHeading2”)}
${doc.select(“h3”).tagName(“p”).attr(“class”,”HiddenHeading3”)}
-->
## print out the modified HTML
${doc.html()}

What does this do? The comments inside of the script helps to understand, but in short:

• Calls the standard wiki->HTML conversion method and captures its HTML output to a variable
• Uses Jsoup java HTML parser libary to parse the HTML. This libary is shipped with codeBeamer as default and we use it to clean up HTML elsewhere, but it is nicely usable here too.
• Using the Jsoup's selector-syntax look for H1/H2/H3 html tags, and using Jsoup's manipulation methods replace them with the appropriate <p> tags with the CSS classes set up correctly.
• Finally the modified HTML markup is printed out

Add CSS style for correct look and to bind with correct Word style

Now the "h1/h2/h3" HTML/wiki headings are replaced with a paragraph, still this does not get the correct Word style and does not look good in the final Word document.

To get this corrected you will need to add some CSS style rules. To generate these missing CSS styles do this:

• Go to Word, create a new paragraph in your template for each new style, so there should be one paragraph with "HiddenHeading1", and another one for "HiddenHeading2", and so on.
• Save the template using the "Save as" feature of Word, and save as HTML format:
• Open the created style.htm in a plain text editor (notepad)
• In the style.html search for the CSS rules for "HiddenHeading1" and the other new styles you need:
• The found custom style will contain an "mso-style-name" which binds this CSS style to the appropriate Word style. It also contains other look elements for example font's size and others.
• Copy all needed CSS rules to your template and add it to the "Custom CSS" block:

Now you are done. Save the template and try an export.

The final result will be:

• The Heading elements of an issue's description does not appear in the Words' Table-of-Contents
• But the remapped Heading elements will look the same as the normal "Heading 1" etc styles