Preparing a Word document

Modified on Mon, 22 Apr at 1:24 PM

Actions of type Fill word document allow you to create a PDF document based on an existing word document.

Word form control element are replaced with the value of the corresponding form element. Use cases include summaries of contact forms or surveys.

Contents

Word version

All versions starting from Word 97 are supported.

Inserting values from form fields

Developer tools can be activated in the options under customize ribbon developer tools.

To insert values from the form into the the word document, you need to add form control elements to the word document. Form controls are found under the developer tools tab. In case this tab is not available, activate it by going to files options customize ribbon developer tools.

Go to the developer tools tab to insert a text field form control. Give it a name and it will be replaced with the value of that form element.

Click on the developer tools tab and insert a text field. Double click on the text field, which opens a new window. Enter the name of the form element under default text. This text field is then replaced with the value of the form element with that name.

If the form element is a repeated element, the text field is replaced with the value of all dynamically created fields separated by a comma. For example, if there are three dynamic field, the value could be Anton,Sabine,Odo.

The value of form elements is visible in the document. When you wish to avoid that, you can set the word function as the help text of the form element. When the help text contains a function, that function always takes precedence over functions in the value of form elements.

Example

Example for how to insert data from a form into a word document. Form fields are selected based upon their name and the default text of the form control element.

In this example, the text field form control with the default text tfFirstName is replaced with the content of the form element named tfFirstName. Similarly, the text field form control tfLastName and tfQuestion are replaced with the corresponding form elements as well.

Inserting placeholders

You can use placeholders as usual, e.g.

[%$DBQuery.RESULT.updateCount%]

However, if you do that, you cannot combine these placeholders with Word fill functions. If you wish to do so, you can use the Word fill function val to replace the placeholder first. For example, you can use this function in combination with the workflow action Encode as base64 to convert an uploaded image as a base64 string and insert that image into the Word document:

val("[%$EncodeAsB64.b64String]").b64img()

Word fill functions

Sometimes it is necessary to transform or edit the raw value of a form element before inserting it into the word document. This can be achieved with the following functions.

As an example, consider a form element of type selection. Its value is often numeric, eg. 0 (for no) or 1 (for yes). If you would like to insert the name of the option instead, use the function lsttxt(). That is, if the form element is named selQuestion, use selQuestion.lsttxt() as the default name for the form field control in the word document.

selQuestion.lsttxt()

You can also combine Word fill functions with placeholders by using the val function:

val("[%$EncodeAsB64.b64String]").b64img()

Available functions

Function	Description	Examples	Explanation
empty	Checks whether the list of values is empty or one of the values is empty.	sel1.empty()	Returns 1 when no option or an option with an empty value was selected for a select element. Otherwise, returns 0.
lsttxt	Replaces the value of the option of a selection element with its text (display) value. Stands for list text.	sel1.lsttxt()	Returns the text value of the selected option of the selection element with the name sel1.
lsttitle	Replace the value of the selected option of a selection element with its title. Stands for list title.	sel1.lsttitle()	Returns the title (if given) of the selected option of the selection element with the name sel1.
lst	Replaces all values of a select element with the corresponding value of a certain column from the data source that provides the options for the select element. The name of the column must be given as an argument. When the data source does not given any names for its columns, you must use col0, col1, col2 etc.	sel1.lst("CountryName")	Returns the value of the column with the name "CountryName" from the data source of the select element with name sel1.
con	Checks whether the value exists in the list. Useful for selection elements with multiple choices. Stands for contains.	sel1.con("5")	Returns 1 if an option with the value 1 was selected for the selection element named sel1, or 0 otherwise.
cnt	Counts the number of values for dynamic elements. Stands for count.	sel1.cnt()	Returns the number of dynamically generated elements for the dynamic selection element sel1.
rmp	Deletes the current paragraph if the value is empty. Stands for remove paragraph.	tf1.rmp()	Deletes the current paragraph if the form element tf1 is empty.
rmr	Deletes the current table row. Stands for remove row.	tf1.rmr("x")	Deletes the current row of the table if the text field tf1 has a value equal to x.
rmt	Deletes the current table. Stands for remove table.	tf1.rmt("y")	Deletes the current table if the text field EL1 has a value equal to y.
rmtp	Deletes the current table and the following paragraph. Stands for remove table paragraph.	tf1.rmtp("y")	Deletes the current table and the following paragraphs if the text field tf1 has a value equal to y.
rep	Replaces the value with another value. The argument syntax is EL.rep("W1"\|"W2"#"R1"\|"R2") or EL.rep("W1"#"R1"). Stands for replace.	EL1.rep("on"\|"off"#"x"\|"o")	The value on is replaced with xand the value off is replaced with o.
cf	Changes the character set to Wingdings. Mostly used in combination with the rep function. Stands for change font.	SEL1.rep(on\|off#x\|o).cf()	The value on is replaced with x, off with o. Afterwards the values x and o are replaced with their corresponding Wingdings symbols (cross and circle).
image	Interprets the value as an URL and replaces it with the image found at that URL. You can also set width and height for the image.	tf1.image(), tf1.image("100"\|"100"), tf1.image("100"), tf1.image(\|"100")	Inserts an image found at the URL pointed to by the value of the text field tf1. Examples for height specifications: tf1.image(width\|height), eg. tf1.image("579"\|"410"). If you only specify an width (tf1.image("579")) or height (tf1.image(\|"410")), the resulting image will be scaled to maintain the aspect ratio.
b64img	Converts a base64 string to an image. You can also transfer width and height information.	tf1.b64img(), tf1.b64img("100"\|"100"), tf1.b64img("100"), tf1.b64img(\|"100")	Interpretes the field value as a base64 string and inserts it as an image into the document. The base64 string should look like iVBORw0KGgoAAAANSUhEUgAAABAAAA.... Examples for height specifications: tf1.b64img("width"\|"height"), eg. tf1.b64img("579"\|"410"). If you only specify an width (tf1.b64img("579")) or height (tf1.b64img(\|"410")), the resulting image will be scaled to maintain the aspect ratio.
url	Interprets the value as an URL and generates a link to that URL.	tf1.url() (since version 8.0.2) tf1.url("Click here")	Adds a link to the PDF document with the address taken from the value of the text field tf1. 8.0.2 Optionally, you can also pass the display text as a parameter.
cb	Generates a checked checkbox if the the value contains the given parameter. Generates an unchecked checkbox otherwise. Stands for Checkbox.	SEL1.cb("1")	Generates a checked checkbox, if there is a selected option with the value 1 for the selection element SEL1, or an unchecked checkbox otherwise.

Available top-level functions

At the beginning of an expression, you can use either the name of a form field directly or one of the following top-level functions:

Function

Description

Example

val

Replaces all placeholders in the given text and uses that text for the following Word fill functions.

val("[%$Base64Kodieren.b64String%]").b64Img()

Inserts an image into the Word document, which is taken from the Encode as base64 action.

const

Takes the given text verbatim and uses that text for the following Word fill functions, without performing any replacements.

val("[%tfFirstName%] [%tfLastName%]").rmp("John Doe")

Joins the first name with the last name and checks whether the full name equals John Doe. If so, removest the current paragraph from the Word document.

Problems creating checkboxes

If no checkboxes are created in the generated PDF document when using the function cb(), it is probably due to missing fonts on the server. This problem usually occurs only when formcycle is installed on a Linux server.

To solve the problem, try:

Log in to the Linux server with formcycle
Go to the system fonts folder (eg. /usr/share/fonts/truetype/ for Debian/Ubuntu) and check whether the fonts windings.ttf and windings2.ttf are installed.
If not, copy these fonts to the folder. Due to licensing issues we cannot ship the product with these fonts, so you must copy them yourself from a Windows installation.
Restart the Tomcat server.

Placeholder replacement

It is possible to insert placeholders into the created form control elements.

Insert HTML 8.0.0

Starting with version 8 of formcycle, merge fields are no longer required for inserting HTML. For security reasons, values in merge fields are no longer interpreted as HTML by default.

To insert a value as HTML, use the function html, for example tfComment.html(). This works for both normal fields and merge fields.

Note: This feature can be used to insert arbitrary user input as HTML. You should treat this with caution, as it might enable users filling out your form to evaluate arbitrary HTML on the server.

Insert HTML 7.2.0

Adding a field.

Creating a MergeField.

In case the text value of the form elements or placeholders need to be interpreted as HTML, they have to be added through MergeFields. MergeFields can be inserted through Insert Quick Parts Field. In the pop up window, under the menu Place choose a field, the field name MergeField has to be selected. After selecting MergeFields, under the menu Field properties, in the field Field name, the name of the form element or placeholder has to be inserted.

Format

Word fill functions always have the following syntax:

Word function

<Word-Function> = <Field-Name> ["." <Function-Name> "(" <Argument>? ")" ] *

A word function consists of the name of a form field, followed by any number of functions, separated with a dot.

Function-Call

<Function-Name> "(" <Argument>? ")"

Each function may also specify an optional argument, but does not have to.

sel1
sel1.function1()
sel1.function1(argument)
sel1.function1().funktion2()
sel1.function1(argument).function2().function3()

val("sel1").function1()
val("[%sel1%]]").function1()

const("text").function1()

Argument

<Argument> = <ArgList> | <ArgMap>

The argument can be either a list of values or a mapping between keys and values. Which type of argument needs to be used depends on the function.

ArgList

<ArgList> = <Value> [ "|" <Value> ] *

The argument can be a list of values, separated by a bar character. The number of required arguments depends on the function.

sel1.function(value1)
sel1.function(value1|value2)
sel1.function(value1|value2|value3)

ArgMap

<ArgMap> = <ArgList> "#" <ArgList>

The argument can also be a mapping between keys and values. The keys and values are separated by hash tag. Which keys are required depends on the function.

sel1.function(key1#value1)
sel1.function(key1|key2#value1|value2)
sel1.function(key1|key2|key3#value1|value2|value3)

Value

<Value> = <Unquoted-String> | <Singly-Quoted-String> | <Doubly-Quoted-String>

Each value can be just a series of characters.

sel1.function(Ein Wert)
sel1.function(Noch ein Wert)
sel1.function(Wert1|Wert2)

Certain special characters such as parentheses or hash tags cannot be used normally. Then it is also possible to put the value in single or double quotes (supported since 7.1.0+ ). Values without quotation marks exist for compatibility reasons, the use of quotation marks is recomended and never wrong.

sel1.function('Value (with) parentheses')
sel1.function("Value with a dot and a hash tag #.")
sel1.function('Value#1'|'Value#2')

You can also use escape sequences within quoted values:

sel1.function("John said: \"It rains\"")
sel1.function("The backslash \\ starts an escape sequence")
sel1.function("Line break: \r\n")
sel1.function("Tab: \t")
sel1.function("Unicode character: \u578b")

Note: When quotation marks are not used, all spaces belong to the value. The following are two distinct values (with and without a leading space):

sel1.function(Test)
sel1.function( Test)

If you use quotation marks, spaces are ignored. The following is the same:

sel1.function("Test")
sel1.function( "Test")