DocxTemplateHandler

Generating documents based on docx template

RunaWFE Free Workflow System (BPMS) Version 4.5.0

© 2003 - 2015, Consulting Group Runa

© 2015 - 2024, "Process Technologies" Ltd, this document is available under GNU FDL license. RunaWFE Free is an open source system distributed under a LGPL license (http://www.gnu.org/licenses/lgpl.html).

# Overview

ru.runa.wfe.office.doc.DocxHandler handler is used to generate document from template.

This handler can run in strict mode or not. In case of strict mode any error in template or if template requires variable that is missing from process an error will be propagated. Strict mode can be set via checkbox in handler configuration.

Note. Characters (semicolons and sequence ' as ') in variable names in templates are known to cause errors.

# Settings

See office.properties configuration guide. Properties docx.placeholder.start, docx.placeholder.end define control statements syntax. Default values are "${" and "}".

# Replacements

Expression of the form

${variable}
will be replaced by variable variable in the format defined in Developer Studio.

Note. To begin a new line variable must contain \r\n sequence.

# Container Element Replacements

Elements of container type can be accessed with square brackets [].

Integer (or long) value or variable can be used as list element index.

String value or variable can be used as map key.

Examples:

map[key1]
${list[3]}

# Executor Field Replacement

Fields output can be done in a usual way. For example to output full name from the variable processStarter of Executor type:

${processStarter.fullName}

Note. In early versions ^4.0.6- it was possible to set another type for variable replacement in configuration. This feature is available in backward compatibility mode ^4.2.0-, but in this case the current features are not available. If there's such setting with type specification present in configuration then handler automatically switches to backward compatibility mode.

# Images

In a usual way a pointer ${image1} in template can be replaced by file variable with image.

Note. If file variable contains not an image (or if image format is unknown) there will be an error while processing template.

# Iterators

The following iterators are used while working with containers:

• indexes for index iteration (starting with 0)
• items for values iteration
• keys for maps, iteration by keys
• values for maps, iteration by values

# Tables

Note. In early versions ^4.0.6- tables were configurated in configurators. This feature is available in backward compatibility mode ^4.2.0-, but in this case current features are not available. If table is configurated in configuration then handler automatically switches to backward compatibility mode.

You can create table only with fixed number of columns in template. Note that table style stays the same after replacements. Table rows can be created automatically from maps or lists. In order to do so put one of the following in each table row cell:

${VARIABLE} 
${ITERATOR:VARIABLE}
${ITERATOR:VARIABLE as SELECTOR}

, where

ITERATOR is the name of iterator type; if not set then default iterators items, values are used for the corresponding container types.

VARIABLE is the name of container variable of map or list type

SELECTOR is field or attribute specification of iterator current variable, if not present then variable value is used

It's necessary to fill the first row with the some of the following in order for the rest of the rows to be filled with containers elements.

Variants of first row cells:

${indexes:list}
${items:list}
${items:userList as fullName}
${list}
${keys:map}
${map}
${values:map}
${values:mapWithGroups as name}

In case of maps linked by key sorting is carried out by keys. Say we have map1 and map2 with keys1=keys2 (linked maps) and we want to create a table with 3 columns with all elements from those maps. Then first row, first cell is ${keys:map1}; second cell is ${values:map1}; third cell is ${values:map2}.

Note^4.1.0-. Syntax was ${ITERATOR:VARIABLE SELECTOR}

# User Types

Point is used to separate name of variable of user type from its attribute to designate value of user type variable attribute for replacement.

Example:

${car 1.name}

# Programming Capabilities

# Loops ^βeta

Loop is defined by 3 elements: loop start, loop body and loop end.

Loop start is of the following form:

${ITERATOR:VARIABLE as ITERATOR_VARIABLE}

, where

ITERATOR is iterator type

VARIABLE is container variable name(of map or list type)

ITERATOR_VARIABLE is variable name with the current iteration variable, the value depends on iterator type

Loop body can contain only text. Current iteration variable is accessed in a usual replacement way.

Note. Tables are not permitted in loop body.

Note. Inner loops are not permitted in loop body.

Note. Loop body if copied do not preserve all its attributes, for example background color.

Note^4.1.0-. Syntax was ${ITERATOR:VARIABLE ITERATOR_VARIABLE}

Loop end is of the following form:

${/ITERATOR}

, where

ITERATOR is iterator type name that must correspond with loop start iterator type

Note. Loop start and loop end strings must be on their own lines and those lines must not contain anything besides them.

Examples:

${items:list as value}
 ${value}
${/items}

${indexes:list as index}
 value = ${list[index]} for element ${index}
${/indexes}

${keys:map as key}
 ${key} = ${map[key]}
${/keys}

${values:map as value}
 ${value}
${/values}

# Decisions ^planning

${if (map.size() == 0)}
 map empty
${if (map.size() > 100)}
 map is considerably filled 
${if else}
 input data
${/if}