Creating Word templates

Preliminaries

<?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 placeholder 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}
okp:tpl.language	okp_tpl_language	${okp_tpl_language}

Creating the template

Open Microsoft Word and type the placeholders directly into the document as plain text:

Name: ${okp_tpl_name}
Birth date: ${okp_tpl_birth_date}
Language: ${okp_tpl_language}

This is the Word document used in this sample: tpl.docx.

Placeholders are replaced in the document body, tables (including nested tables), headers, footers, footnotes and endnotes. The same placeholder can be used as many times as needed.

Word internally splits the text in several fragments because of spell checking, revisions or partial formatting. This does not affect the placeholders, but the replaced value takes the format of the first character of the placeholder (the $ sign). To apply a format to a value (bold, color, font size, etc.), apply it to the whole placeholder.

Formatting values

A placeholder can use these FreeMarker built-ins and the default value operator, with the same syntax and result as in FreeMarker:

Placeholder	Result
`${okp_tpl_name?upper_case}`	Value in upper case: `JOHN SMITH`
`${okp_tpl_name?lower_case}`	Value in lower case: `john smith`
`${okp_tpl_name?cap_first}`	First letter in upper case: `John smith`
`${okp_tpl_name?capitalize}`	First letter of each word in upper case, the rest in lower case: `John Smith`
`${okp_tpl_name?trim}`	Value without leading and trailing spaces
`${okp_tpl_birth_date?string("dd/MM/yyyy")}`	Date with the given format: `17/05/1990`
`${okp_tpl_birth_date?string("d MMMM yyyy")}`	Date with the month name: `17 May 1990`
`${okp_tpl_name!}`	Value, or empty text when there is no value
`${okp_tpl_name!"Unknown"}`	Value, or `Unknown` when there is no value
`${(okp_tpl_name!"Unknown")?upper_case}`	Value or `UNKNOWN`, in upper case

Notes:

Built-ins can be chained: ${okp_tpl_name?trim?upper_case}.
The date format uses the Java SimpleDateFormat patterns. Month and day names use the language of the server.
As in FreeMarker, built-ins written after a default value only apply to that default value: in ${okp_tpl_name!"Unknown"?upper_case} only Unknown is converted. To convert both, use parentheses: ${(okp_tpl_name!"Unknown")?upper_case}.
An empty metadata field is handled as a field without value: the default value is used and the built-ins return an empty text.
?string("...") can only be applied to date fields, and the other built-ins only to text fields.

Values

Each metadata field type is written in the document this way:

Metadata field type	Value in the document
Input text, Suggestbox	The text as it is.
Input date	The date in `yyyy-MM-dd` format (for example `2026-10-05`).
Textarea	The text; each line break is kept as a line break in the document.
Checkbox	`true` or `false`.
Select simple	The label of the selected option (not its value).
Select multiple	The labels of the selected options separated by `;`.

A placeholder without value, or that does not match any metadata field, is replaced with an empty text.

Values are always inserted as literal text: special characters like &, < or quotes are shown as they are, and a value that contains a placeholder (for example ${okp_tpl_name}) is not replaced again.

Configuring the sample

Upload the tpl.docx 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.docx file.

When creating a document from the template, choose whether the generated document is saved as DOCX or converted to PDF.