Monkeybread Software - DynaPDF Manual

DynaPDF Manual - Page 60

Interactive Forms

Page 60 of 839

Field Names

Interactive Form Fields are identified over the field name in a viewer application. A field name

is an Ansi string that should be human readable. Beginning with PDF 1.5 field names can also

be defined as Unicode string. However, all functions to create new fields in DynaPDF support

Ansi strings only. All characters within the Ansi character set (code page 1252) can be used with

exception of the period character (.) and characters below index 32 .

A field name should also not end with a space character because Adobe's Acrobat is then

sometimes unable to access such a field with a JavaScript Action or function.

The period (.) is a reserved character because it is used to build the fully qualified field name in

a viewer application. The fully qualified field name is constructed from the partial field name of

the field and all of its ancestors.

For a field with no parent group field, the partial and fully qualified names are the same. For a

field that is the child of another field, the fully qualified name is formed by appending the child

field’s partial name to the parent’s fully qualified name, separated by a period, e.g.

Address.Street.

Fields with identical names

It is possible to create two or more fields of the same type which use all the same name. Such

fields contain always the same value if the value of one field of the group is changed.

Fields with identical names are internally represented as a special type of field group, which is

automatically created by DynaPDF. This makes the handling more complicated because the

children of such a group do not contain a field name. The name is set to the parent's group field

but not to the children of the group. This can normally be ignored but when enumerating fields

with GetField() or GetPageField() you must consider that not all fields contain a name, the

parent field's handle is set instead.

However, with the exception described above, field names must be unique within the hierarchy

in which they appear. This is especially important when multiple Interactive Forms are

imported.

When importing multiple Interactive Forms it is highly recommended to check for invalid

duplicate field names. This can be done with the function CheckFieldNames(). The function

returns the handle of the first field which contains a field name that is already in use. You can

then change the field name with SetFieldName() and execute CheckFieldNames() again until all

invalid field names are changed.

After changing a field name you must also check whether the field is used within a JavaScript

Action or function. Such scripts must be changed so that they do not become invalid. Due to the

possible references of fields within JavaScript functions and Actions, merging of Interactive

Forms is very complicated and should be avoided whenever possible.

Next topic: Actions