Adding explanatory text to your forms

Some forms are complex, and form authors want to provide guidance to the end-users who will be filling out those forms. For every field, in addition to a label, form authors can provide:

• A hint, shown below the field. Using a hint works well for short pieces of information that fit comfortably below the field.
• A help message, shown in a popover when users click on a help icon next to the field. The help works well for longer pieces of texts that users won't necessarily need.

In some cases however, form authors would like to have the explanatory text displayed in-line in the form, instead of in a popover. For instance, this can make sense when end users are likely to need that information, or if the form author wants to draw users' attention to a piece of information. For this, the upcoming Orbeon Forms 4.9 introduces a new "control": the explanation control.

In Form Builder, the explanation control shows in the left sidebar, just like other controls, so form authors can add it anywhere in the form where other controls can be added. Upon inserting an explanation control, in Form Builder, form authors can type text in a rich text editor:

At runtime, when users fill out the form, this text will just show as-is:

Just like the text in the label, hint, and help, text entered in the explanation control is fully localizable, and forms can have different version of that text for all the different languages supported by the form. Form authors can localize the text in an explanation control directly from Form Builder, just like they do for the label, hint, and help.

We'd like to thank Aaron Spike, from the Martin Luther College for contributing a large part of the underlying code for this feature. Thank you, Aaron!