MagicTree Documentation: Hyperlinks and Bookmarks

Microsoft Word Reporting Notes | Table of Contents | Hyperlinks in Microsoft Word Templates >

One part of a report often needs to reference another part of the report. For example, in each problem description we want to list affected hosts, and link those to the test log containing details regarding this host. Or in a section with host details we want to list all tasks executed for that host, and cross-reference each task to a section containing full task output.

Both in Microsoft Word and in OpenOffice this can be done using hyperlinks and bookmarks.

Hyperlinks work more or less in the same way as hyperlinks in HTML. A portion of document text is hyperlinked to a location, either in the same document or somewhere else.

To be able to link to some part of the same document, we can use bookmarks. Bookmark is somewhat similar to "a" tag in HTML that has a "name" attribute and does not have a "href" attribute. It marks a location in the document. Bookmarks are referred to by name. Each bookmark must have a unique name.

Since the contents of the report are generated from template, if we want to cross-reference dynamically generated content, we need bookmark names and hyperlink target to be dynamically generated as well. MagicTree supports that. You can place XPath placeholder expressions in bookmark names and in hyperlink targets. They will be processed and replaced by MagicTree report generator.

Creating bookmarks works in exactly the same way for Microsoft Word and for OpenOffice template. To place a bookmark in a document, you put an XPath placeholder with a "bookmark" flag in place where you want a bookmark. The result of the XPath expression evaluation will be used as the bookmark name. For example, a template may contain the following:

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

When the report is generated, the {{./@id|bookmark,leaf}} placeholder will be replaced by a bookmark, with the bookmark name set to the value of the "./@id" XPath expression (which in this case will be the id of the host).

We do not use the Microsoft Word or OpenOffice GUI to create bookmarks in report templates becuse of the restrictions on the characters that may be used in bookmark names.

For hyperlink creation see Hyperlinks in Microsoft Word Templates and Hyperlinks in OpenOffice Templates

Caveats

Bookmarks, just like any other placeholders modify the current scope. Quite often this is not what you want (in the example above you probably want the scope to be the host, not its @id attribute). Use "leaf" flag if you don't want the bookmark to modify the scope.

Microsoft Word Reporting Notes | Table of Contents | Hyperlinks in Microsoft Word Templates >