Creating HTML Templates#

You can create PDF documents from the wiki using HTML/Freemarker templates. This section explains how you can convert text and metadata from your wiki document into a PDF document using an HTML/Freemarker template.

Developing an HTML Template#

A web browser with debug functionality is sufficient for developing HTML templates. You should have project administrator rights or be logged in as a system manager or system administrator. Go to Administration > Templates > Wiki Export Templates. Open the “HTML Templates” folder and the desired template folder within it.

It’s easiest to start developing your own templates based on an existing one. You can change the CSS styles directly in Allegra.

The Template Structure#

An HTML template consists of a ZIP file with the extension “.hlx”. The template can be uploaded directly to the wiki or to the administration by authorized individuals.

The next figure shows an expanded template. The top level must contain the template files and cannot be a folder. You can create the file with the command

zip -r ../Framed.hlx *

executed in the template directory. The individual files and folders are explained below.

../_images/html-template1.PNG

Expanded template#

  • {template name}.html: Example: Framed.html. The ZIP file must contain an HTML template file at the top level, which has the same base name as the ZIP file. If, for example, the ZIP file is named “Framed.hlx”, it must contain a file “Framed.html”. The HTML file may contain Freemarker expressions, e.g.

  • {template name}.properties: Example: Framed.properties. This element is optional and contains parameters for controlling the display properties (see below). This file can contain FreeMarker expressions.

  • Directory “resources”. Must be named exactly like this. The directory contains images and other resources.

  • Directory “fonts”. Must be named exactly like this and contains fonts for creating a PDF document.

  • One or more CSS files

The Template File#

The template file is a simple XML file with Freemarker expressions. Please ensure that the template file is a valid xhtml file (all tags are closed). The template file and the template name must be identical. The extension must be .html. This file can contain Freemarker expressions. All document fields can be used by entering the unique field name as Freemarker expressions. The field names can be accessed via Perspective Administration > Customize > Item attributes or in the item overview via the column selection.

In addition, there are some other Freemarker variables:

  • cssBasePath: the absolute path to the template directory. Example: href = “${cssBasePath}/base.css”

  • imgBasePath: the absolute path of the resource directory as seen from the template directory. Example: ${imgBasePath}/allegraLogo.png

  • summary: the summary (table of contents) of the document

  • wikiContent: the content of the wiki document without summary

  • pageLbl: the localized word “page”

  • ofLbl: the localized word “of” (page 1 of 17 or page 1 / 17)

  • IssueNo: The ID of the document (global or workspace-specific)

  • parentSynopsis: The title of the parent item, if present

  • timeStamp: The time the PDF document was created

  • licenseHolder: Name of the license holder

  • locale: the user’s locale

The Template Configuration File#

If the template directory contains a file {templateName}.properties, it is used by the system. The file is optional. It can contain Freemarker expressions. All document fields can be used as Freemarker expressions. Available configurations are:

  • contentMaxWidth: An integer in pixels. If the “width” attribute of an image or table is greater than this value, the corresponding object is scaled.

  • watermarkImgName: The name of an image file, whose image should be used as a watermark

  • watermarkText: This text is displayed as a watermark in the center and possibly rotated on each page

  • watermarkTextSize: in points

  • watermarkTextColor: color in hex notation

  • watermarkTextRotation: rotation. 0 is horizontal, 90 is vertical.

All fields are optional. If both watermarkImgName and watermarkText are defined, `` watermarkImgName`` takes precedence.