Hyphenation Under the Hood (HUH)

Designer now supports automatic hyphenation of text on a form. We anticipate that this feature is going to be very popular with some clients (especially with German clients – from what I understand, German is a language that benefits a lot from auto-hyphenation.) In this post, I’ll be providing a summary of how the hyphenation feature works in Designer, along with some “under the hood” descriptions of what’s really going on when hyphenation is used.

The Nuts and Bolts

At it’s base, hyphenation instructions are really an XFA tag <hyphenation> that is a child of the <para> tag. According to the XFA grammar, any <para> tag in the whole form can have a <hyphenation> child and set specific hyphenation settings for that <para> element.

However, we did not choose to expose hyphenation in Designer as a per-<para> property. Instead, hyphenation is implemented on a per-form basis, with each individual text object either having hyphenation on or off.

The way hyphenation works is that the five different variables that control hyphenation are set at the form level and get applied to any object that has hyphenation turned on. The way we chose to implement the form level hyphenation is through the XFA <protos> mechanism. A <proto> is like a snippet of re-usable XFA; you can declare it once and then have any element “use” that proto.

We have one proto definition for a hyphenation node:

<field name="designer__defaultHyphenation">
<hyphenation hyphenate="1" wordCharacterCount="3" remainCharacterCount="2" pushCharacterCount="2"/>

Then, every object for which hyphenation is turned on gets a <hyphenation> entry on it’s <para> element that uses that proto node:

<para vAlign="middle">
<hyphenation use="designer__defaultHyphenation.para.hyphenation"/>

How Designer Implements Form-Level Hyphenation Settings

There are actually two mechanisms that come into play when setting form-level hyphenation. The first mechanism is the application level hyphenation settings. These settings can be found under Tools | Options | Formatting. These settings control hyphenation options for new forms. So every new form created in Designer will have these hyphenation settings a a default. The goal of this menu is to allow users to customize hyphenation behavior for all forms they create, so they don’t have to constantly update the Form Properties of every new form.


The second mechanism that comes into play is to change settings on a per-form basis, in File | Form Properties | Formatting. Changing the settings here only affects the current form; new forms will still inherit the settings from the Tools | Options | Formatting menu. Changing the form-level hyphenation properties has an immediate effect on the current form: once the dialog is dismissed, all hyphenated text in the form should change to reflect the new hyphenation settings. This dialog also contains two buttons that are shortcuts for removing all hyphenation from the form and adding hyphenation to all the elements of the form. Note that these buttons have an instantaneous result – you don’t have to press “ok” on the dialog for the action to take place.


The proto hyphenation node will only be present if it is needed (i.e. some real node, somewhere in the document, is hyphenated and thus needs to use the proto.) In certain cases, if there is no proto node, but the form has hyphenation settings that differ from the default, then a Hyphenation processing instruction (PI) will be added to the document in order to save the form’s hyphenation settings.

How to Use Hyphenation in a Form

When you are actually working with your form, hyphenation is really simple to use. It’s one checkbox control on the Paragraph Inspector.


A couple of “gotchas” with hyphenation on the form:

  • By default, allowing hyphenation of field captions and static text is disabled. This means that the hyphenation checkbox control will be disabled on the dialog if a static text control is selected. It also means that on a control that has both caption and value text (i.e. a TextField), when the hyphenation checkbox is checked, it will fill with a square rather than a check, indicating a dual-state check (where half the control is hyphenated and the other half is not.) In order to change this behavior, enable the “Allow Hyphenation in Text and Field Captions” option in Tools | Options | Formatting (for all new forms) or in File | Form Properties | Formatting (for the current form).
  • Another situation where the checkbox may fill with a square rather than a check is if multiple objects are selected and some of them have hyphenation enabled and others have it disabled. The checkbox will show the “mixed” square indicator in this situation as well.

Comments on Compatibility

Hyphenation works with XFAF. However, hyphenation cannot be applied to background content.

Using hyphenation can result in target version warnings, since not all versions of Acrobat support all types of hyphenation. For the most part, hyphenation in value text is not supported in earlier versions of Acrobat (< 9.0). Hyphenation in boilerplate text is supported in older version of Acrobat for static forms. If the form is dynamic, then hyphenation of boilerplate will not be supported in older versions of Acrobat (< 9.0).

One last note on compatibility: there is a risk that using hyphenation could cause text shifting in newer versions of Acrobat. Hyphenation depends on hyphenation dictionaries to figure out where to hyphenate text. Hyphenation dictionaries can change over time: it is conceivable that new dictionaries could be introduced that would change where hyphenation points occur, leading to changes in text layout for hyphenated text. These changes would probably be very minor, but it could lead to a difference of adding/losing a line of text. The risk is fairly small, but it does exist. We strongly urge customers who have forms that are sensitive to text shifting not to make use of hyphenation.

Hyphenation and Fragments

(The following is straight from the functional specification for hyphenation:)

Hyphenation in fragments works in the same way as hyphenation in regular forms. That is, any object that is hyphenated in a fragment will have a <hyphenation use=“designer__defaultHyphenation.para.hyphenation”/> child defined under the appropriate <para> element.

When a fragment is created in a separate XDP file, if any object in the fragment contains hyphenation instructions then the fragment will be created with a <proto> element on the root subform that contains a <hyphenation> child inside a named field that is a copy of the <hyphenation> definition from the original form. The use attribute does not need to be updated, since the SOM of the hyphenation proto is the same in the fragment as it was in the original document.

If a fragment is defined within an existing XDP, nothing changes in regards to hyphenation; the <hyphenation use=“designer__defaultHyphenation.para.hyphenation”/> elements are still valid, and continue to point to the root subform’s <proto> <hyphenation> element.

In both of the cases above, when a fragment is referenced from another form, it (potentially) has different hyphenation settings than the form that is referencing the fragment. The fragment’s hyphenation settings are self-contained within the fragment and separate from the referencing form’s fragment settings.

When a referenced fragment is embedded within a form, it loses its unique hyphenation settings; any <hyphenation use=“designer__defaultHyphenation.para.hyphenation”/> elements will be changed so that the use attribute points to the SOM of the root subform’s <proto> hyphenation node. Or, in other words, the fragment will now inherit the form’s hyphenation settings, rather than having different hyphenation settings that are defined in the fragment. This could potentially lead to a change in appearance and layout when a fragment is embedded.

If a hyphenated fragment is embedded within a form that does not have any hyphenation, then the fragment’s hyphenation will be lost (i.e. it still inherits the form’s hyphenation settings, namely “no hyphenation”).

To Conclude

This was an overview of the Hyphenation feature from an “under the hood” perspective. For details on how the feature works from a functional point of view, please read Designer’s Help documentation.

One Response to Hyphenation Under the Hood (HUH)

  1. This information is truly valuable. Thank You!