Adding Ghost Text to LiveCycle Designer form

Problem

Ghost Text is a common way of adding instruction text to a web form, especially if space is tight, but Designer has no built in support.

Solution

Using a null category picture clause and some JavaScript we can achieve a similar effect.

Detailed explanation

Below is an example of ghost text in a form, if the field is empty and has not been selected then we want some information text displayed (in a lighter color and in italics). If the field is selected then we want the information text cleared so the user can enter their response.

In the ready:form event for this field there is the following statements which just set the initial state of the field; (Note: I originally had this code in the initialize event, but as Joe McGloin pointed out in his comments below this does not fire when a Reset button is clicked).

this.execEvent("exit");
this.format.picture.value = "null{'" + this.assist.toolTip.value + "'}";

The trick to this whole approach is setting the format.picture.value to "null{ some text }" which causes Reader to display the some text whenever the field is null/empty. In this example I am displaying the text from the toolTip for the field but this could be any text.

In the enter event I change the font to black and normal posture so it looks like a regular text field once the user starts typing into it.

this.fontColor = "0,0,0";
this.font.posture = "normal";
   
In the enter event I change the font to black and normal posture so it looks like a regular text field once the user starts typing into it. 

In the exit event I change font back to grey, italic if the field is null so it looks like help text. This is also called from the initialize event to set the fields state initially.

if (this.isNull)
{
      this.fontColor = "153,153,153";
      this.font.posture = "italic";
}

There is some more code in the prePrint and postPrint events so the instruction text doesn't get printed out.

this.format.picture.value = "";

And then after printing setting it back;

this.format.picture.value = "null{'" + this.assist.toolTip.value + "'}";

Note: this method will only work on dynamic forms.

I have also added an example to the sample form of using proto elements to define the scripts required for this once and have the fields just reference the script. This requires editing the form in the XML Source view but does save duplicating the script. A proto field can be created by dragging a field from the Hierarchy view to the "Referenced Object" node, make a copy of the field first as this drag is a move not a copy. Once under the "Referenced Object" node it can be renamed and references to it (or parts of it) can be made from the "use" attribute which is common to all elements in the template. So now we can go into the XML Source view and add the following lines to refer to the required scripts.

<event use="protoGhostText.event__enter"/>
<event use="protoGhostText.event__exit"/>
<event use="protoGhostText.event__prePrint"/>
<event use="protoGhostText.event__postPrint"/>
<event use="protoGhostText.event__form_ready"/>

Download sample, GhostText.pdf.