ITP instructions in Microsoft Word Forms

The Microsoft Word Form Protection prevents a user from editing a result document except for Form Fields and unprotected sections.

The Form Fields in such a protected document have a number of properties which control the content and formatting of these fields. Because the content of these properties are restricted to whatever is allowed in these fields, it is not possible to use ITP instructions in these fields.

Example

As the ITP expression @(…) is not a valid number, it cannot be used in combination with a numerical field.

To work around this restriction the model developer can use the pragma function to override selected attributes in a form field.

Note

This functionality is not currently available in Microsoft Word DOCX models.

Basics

ITP allows you to override properties in Text Form Fields and Check Box Form fields.

The following properties can be changed:

Default value

4.242,42

Format

#,##0,00(#,#0,00)

Help text

Not shown here, accessible through the Add Help Text…button

Status bar text

Not shown here, accessible through the Add Help Text…button

Checkbox status

Not shown here

All other properties are copied into the result document without any modifications.

Form Fields are identified by their unique bookmark ("Amount" in the example above). If a Form Field has no bookmark, its properties cannot be modified from an ITP model.

Setting a value

Settings are overridden using the pragma function.

The function pragma("FormField:bookmark:propertyname"; "value") will produce a word processor instruction that override the property propertyname in the Form Fields with the bookmark bookmark. This word processor instruction must be put in the result document before the Form Field to have effect.

Example

@(pragma("FormField:Amount:Default"; "12,00") will set the Default Number value in the above example to 12,00.

The following properties are allowed with the pragma function:

Property

Value

Effect

Default

Any text

Will set the default contents for the Form Field. The formatting of the Default text should match the formatting mask.

Format

A formatting mask

Will set the formatting mask for the Form Field.

Help

Any text

Sets the text that is shown if the user presses F1.

Status

Any text

Sets the text that is shown in the status bar.

Checked

Y or N

Y sets the check boxes in the Checked state.
N unchecks the check box.

The Default and Format properties are ignored for check boxes.

Unique bookmarks

Bookmark names must be unique in a Microsoft Word document. If the result document must contain Form fields which are produced within a FORALL, the model developer must generate unique bookmark names for each Form Field and use this unique bookmark name with the pragma function.

The bookmark names in the form Fields use the same convention as regular bookmarks; if the bookmark name starts with ItP (note the lower case 't'), ITP will treat the remainder of the bookmark name as an expression which is evaluated during the execution of the model.

Refer to Bookmarks for more details.

Updates

Microsoft Word will automatically update the contents of a Form Field in the following situations:

During this update the Default property will be (re) formatted using the Format property.

The model developer must match the Default property and the Format property to ensure that the field contents do not need to change during the reformatting.

Forms and put_in_document

The pragma function generates a special word processor instruction which will override a property for a Form Field following this word processor instruction. This modification is done after the ITP result document has been split by the put_in_document or similar functions. Therefore the model developer must make sure that the output of the pragma function is placed in the same result document as the Form Field it is expected to modify.

Protecting the Form

The result document must be protected to restrict the user from modifying its contents. There are two ways in which the Form protection can be activated:

Use the pragma function to activate Form protection in the result document:

Activating Form Field support

The Form Field support is by default disabled to support existing ITP model documents. In order to activate the enhanced support, the following settings must be added to the ITP configuration file that is used to translate models:

If these settings are not used when the model is translated, the pragma(FormField:…; …) function is ignored during model execution.

Example

Refer to the sample document in the Examples folder of the support section of the Aia Software website for a documented example.