< Creating Tree Data Templates | Credits >

Report Templates: Tips, Tricks and Troubleshooting

Contents

  1. Easy Table Templates

  2. XPath Placeholder Does Not Get Replaced

  3. Troubleshooting Hyperlinks

  4. Troubleshooting Tables

  5. If All Else Fails

Easy Table Templates

There is an easy way to generate table templates. Create a query in table view that returns the table data you want. Click on the query table to select it and press Ctrl+c (Command+c on Mac). Switch to your template and paste the query by pressing Ctrl+v (Command+v on Mac). This will create a table template producing the same data as your query. Add table headers if necessary.

XPath Placeholder Does Not Get Replaced

Most probably it means that the placeholder got split by some XML tag in the template. Most often this happens when OpenOffice sees an "@" in a string, thinks it is an e-mail address and automatically inserts a hyperlink. In Microsoft Word this sometimes happens because of the spell checker highlighting.

Select the whole placeholder and cut it using Ctrl+x (Command+x on Mac). Then paste it back using "Paste special..." function. (in OpenOffice Edit -> Paste Special...; in MS Word click on the arrow under the Paste button and select "Paste special"). Use "Unformatted text" format to paste. This will remove all XML markup that might be interfering with parcing the XPath placeholder.

Microsoft Word sometimes introduces additonal XML markup to indicate spellchecker and grammar checking errors. This markup may break the placeholder text, so it does not get replaced when the document is generated. If this happens, try switching off spell checker and grammar checker and saving the template. In Word 2003, go to "Tools" -> "Spelling And Grammar...", click on "Options.." button and uncheck "Check spelling as you type" and "Check grammar as you type", thenk click "OK" to dismiss Options dialog and "Cancel" to dismiss "Spelling and Grammar" dialog.

Troubleshooting Quotes

Both MS Office and OpenOffice tend to replace stright double quotes ("") with inverted quotes (“”). MS Office also tends to replace apostrophes with inverted single quotes.This breaks XPath parsing. Youi can disable this behavior.

In Microsoft Word click on Office button and select "Word options..." in the bottom of the menu. In "Word Options" dialog select "Proofing" in the list on the left and click on the "AutoCorrect Options..." button. Select "AutoFormat" tab and uncheck ""Stright" quotes with "Smart" quotes". Press OK.

In OpenOffice or LibreOffice go to Tools -> AutoCorrect Options... . In "AutoCorrect Options" dialog select "Localized Options" tab. In the bottom half of the tab uncheck "Single quotes Replace" and "Double quotes Replace". Click OK.

Troubleshooting Hyperlinks

In a generated report you can see where a hyperlink is pointing if you hover the mouse pointer over the hyperlink.

Hyperlink targets are evaluated before the hyperlink text and modify the current scope. Suppose you want to create hyperlinks to hosts sections, where each host has a bookmark with the name set to its @id.

Hosts section will look something like this:

Test Details By Host

Host {{//host}}{{./@id|bookmark,leaf}}

Some text related to this host

The section containing hyperlinks to hosts will look like this (without hyperlinks)

Affected Systems

Now if we want to hyperlink each host in Affected Systems section, we can do the following. First, set the scope to host using a placeholder with a "hidden" flag, and then use this scope both in the hyperlink text and target, making sure we put in the "leaf" flag in the hyperlink target. Now the Affected Systems section will look like this:

Affected Systems

The hyperlink target will contain the following placeholder: {{./@id|leaf}}

When the report generator processes the template first it will read the first placeholder, and create the copies of the paragraph, each with its own host as a base node. Then it will process the hyperlink target and replace it with the host @id. Since it is marked as leaf, it will not affect the current base node. Then it will process the hyperlink text "{{.}}" and replace it with the current host IP address. When the report is generated, this section will become a list of IP addresses each hyperlinked to the appropriate host details section.

Troubleshooting Headings

In OpenOffice if you see that placeholders in headings are not properly scoped (that is, heading seems to be treated like a normal text paragraph, not like a heading) it means that the heading style being used is represented by text:p rather than text:h tag in OpenOffice XML. This happens when a heading style is not assigned and outline level.

To correct this, go to Tools->Outline Numbering in OpenOffice Writer and assign the heading styles that are not handled correctly to appropriate outline levels. Save the template and regenerate the report.

Troubleshooting Tables

MagicTree report generator currently does not handle tables embedded inside other tables. It probably won't handle the placehodlers occuring inside lists embedded inside tables either.

Consider using tab stops for formatting instead of tables.

If this limitation really bugs you, contact us. We just thought that nowbody cares about embedded tables too much, so we did not implement recursing into tables. If somebody does care, we'll try to implement it.

If All Else Fails

Take your report template and unzip it. Look at content.xml file in OpenOffice or at word/document.xml in Microsoft Word template and try to find the placeholder that is problematic. If that does not provide any enlightenment, contact us.

< Creating Tree Data Templates | Credits >