Creating LibreOffice templates

Tip

Advantages of using LibreOffice templates:

• Can produce an ODT file.
• Less time is required to create the document.

Caution

Disadvantages in comparison with Text templates:

• They produce larger documents.
• More difficulty in maintaining the templates over time.

Preliminaries

Register the Metadata group definition at Administration > Metadata.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.10//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.10.dtd">
<property-groups>
  <property-group label="Sample Template" name="okg:tpl">
    <input label="Name" name="okp:tpl.name"/>
    <input label="Birth Date" name="okp:tpl.birth_date" type="date" />
    <select label="Language" name="okp:tpl.language" type="simple">
      <option label="Java" value="java"/>
      <option label="Python" value="python"/>
      <option label="PHP" value="php" />
    </select>
  </property-group>
</property-groups>

In order to make a relation between the template form field and the property group, you have to name them following a naming convention: replace “:” and “.” with “_”. Here you can see the matching between the two fields:

Metadata field name	Template field name	Template field value
okp:tpl.name	okp_tpl_name	${okp_tpl_name!}
okp:tpl.birth_date	okp_tpl_birth_date	${okp_tpl_birth_date?date!}
okp:tpl.language	okp_tpl_language	${okp_tpl_language!}

Creating the template

The field that will be replaced with the value of a variable passed to the template can be specified using the standard FreeMarker expression notation by typing the variable name into the document as plain text as follows:

Hi ${name}!

However, mixing processing instructions and normal text into the document may become confusing and clutter the layout. So JODReports provides an alternative way of inserting fields. You can insert a visual field in LibreOffice Writer from the menu Insert / Fields / Other… (or just press Ctrl+F2), then click on the Functions tab and select Input field. Change the field Reference to JOOScript. In the Content field, enter the variable name (e.g. “$name”). This field will typically be displayed by Writer as a grayed rectangle with the variable name, and moving the mouse over it will reveal the field reference.

Caution

Do not use View > Toolbars > Form Controls to add the fields (Text Box, Check Box, etc.). Those insert real ODF form controls, which JODReports does not read or fill — the field will remain empty in the generated document regardless of the metadata group values provided. Only plain FreeMarker ${...} text or JODReports Input fields (Reference JOOScript) are substituted.

This is the LibreOffice document used in this sample tpl.odt.

Read about LibreOffice templates at JODReports.

Date format

JODReports uses FreeMarker internally, so you can take advantage of FreeMarker’s formatting flexibility. For example, you can set date formats in this way:

${okp_tpl_birth_date?string("yyyy-MM-dd")}

If the date may be null, then you need to check this (in the case of ODT templates you should use #if between “[” and “]”):

[#if okp_tpl_birth_date??]${okp_tpl_birth_date?string("yyyy-MM-dd")}[/#if]

Learn more about FreeMarker formatting at Built-in Reference.

Caution

Upgrading from a previous OpenKM version? Templates created before this change often use ${field_name!} for date fields, without ?date/?datetime/?string. That syntax used to work but now fails on newer OpenKM releases due to a stricter date-handling behavior introduced by a FreeMarker version bump (see below). Review all your existing LibreOffice templates and add ?date (or ?string(...)/?datetime, as appropriate) to every date-type field expression before generating documents on the upgraded version.

Note

A date field rendered with just the default-value operator (e.g. ${okp_tpl_birth_date!}, with no ?string/?date/?datetime) fails with Can't convert the date-like value to string because it isn't known if it's a date (no time part), time or date-time value. OpenKM passes date properties to the template as a plain, untyped java.util.Date, and current FreeMarker versions no longer assume a default format for it — it must be explicitly typed. Always use ?string(...) for formatted output, or append ?date before the ! if you just need the raw value with no formatting (e.g. ${okp_tpl_birth_date?date!}).

Dynamic tables

You can even use the template feature to generate dynamic tables. Let’s see an example.

In the screenshot you can see a document with a table. The header has a colored background and is also bold. The script shows the options to generate the table headers.

This is the LibreOffice document used in this sample: dynamic_table.odt

Learn more about this feature at:

• JODReports: Inserting Directives at Special Locations.
• Dynamic table column count

Configuring the sample

• Upload the tpl.odt file to /okm:templates/documents
• Register the metadata definition okg:tpl at Administration > Metadata
• Enable metadata from profiles at Administration > Profiles
• Add metadata group okg:tpl to the tpl.odt file.